openapi: 3.1.0
info:
  title: Spring Boot 3 Actuator API
  description: >-
    Production-ready monitoring and management endpoints provided by Spring Boot 3
    Actuator. Includes health checks, Micrometer metrics, environment inspection,
    logger configuration, thread dumps, scheduled tasks, HTTP exchange tracing,
    and more. Endpoints are served under the /actuator base path and can be
    secured via Spring Security.
  version: 3.2.0
  contact:
    name: Spring Team
    url: https://spring.io/team
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:8080/actuator
    description: Local Spring Boot 3 application with Actuator enabled
tags:
  - name: Health
    description: Application and component health indicators
  - name: Metrics
    description: Micrometer-based application metrics
  - name: Environment
    description: Application environment properties and configuration
  - name: Loggers
    description: Logger configuration management
  - name: Info
    description: Application information endpoints
  - name: Threads
    description: Thread and heap diagnostics
  - name: Scheduling
    description: Scheduled task inspection
paths:
  /health:
    get:
      operationId: getHealth
      summary: Get Application Health
      description: >-
        Returns the overall health status of the application. Aggregates all
        registered HealthIndicators. When security is enabled, full details
        are only shown to authorized users.
      tags:
        - Health
      responses:
        '200':
          description: Application is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Application is unhealthy or in OUT_OF_SERVICE state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /health/{component}:
    get:
      operationId: getHealthComponent
      summary: Get Component Health
      description: >-
        Returns the health status of a specific component (e.g., db, diskSpace,
        redis, rabbit, kafka).
      tags:
        - Health
      parameters:
        - name: component
          in: path
          required: true
          description: Health component name (e.g., db, diskSpace, redis)
          schema:
            type: string
            example: db
      responses:
        '200':
          description: Component health status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentHealth'
        '404':
          description: Component not found
  /info:
    get:
      operationId: getInfo
      summary: Get Application Info
      description: >-
        Returns arbitrary application information from registered InfoContributors
        (build, git, environment, OS).
      tags:
        - Info
      responses:
        '200':
          description: Application information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
  /metrics:
    get:
      operationId: listMetrics
      summary: List Available Metrics
      description: >-
        Returns a list of all registered Micrometer metric names available
        in this application.
      tags:
        - Metrics
      responses:
        '200':
          description: Available metric names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsList'
  /metrics/{metricName}:
    get:
      operationId: getMetric
      summary: Get Metric Detail
      description: >-
        Returns measurements and available tags for a specific Micrometer metric.
        Use tag parameters to filter by dimension.
      tags:
        - Metrics
      parameters:
        - name: metricName
          in: path
          required: true
          description: Name of the metric (e.g., jvm.memory.used, http.server.requests)
          schema:
            type: string
            example: jvm.memory.used
        - name: tag
          in: query
          required: false
          description: Tag filter in name:value format (may be repeated)
          schema:
            type: string
            example: area:heap
      responses:
        '200':
          description: Metric measurements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricDetail'
        '404':
          description: Metric not found
  /env:
    get:
      operationId: getEnvironment
      summary: Get Environment Properties
      description: >-
        Returns all application environment properties grouped by property source
        (application.properties, system properties, environment variables, etc.).
      tags:
        - Environment
      responses:
        '200':
          description: Environment properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
  /env/{toMatch}:
    get:
      operationId: getEnvironmentProperty
      summary: Get Environment Property
      description: >-
        Returns the value and origin of a specific environment property key.
      tags:
        - Environment
      parameters:
        - name: toMatch
          in: path
          required: true
          description: Property key to look up (e.g., spring.application.name)
          schema:
            type: string
            example: spring.application.name
      responses:
        '200':
          description: Property value and origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyDetail'
        '404':
          description: Property not found
  /loggers:
    get:
      operationId: listLoggers
      summary: List Loggers
      description: >-
        Returns all loggers with their configured and effective log levels.
      tags:
        - Loggers
      responses:
        '200':
          description: Logger configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoggersResponse'
  /loggers/{name}:
    get:
      operationId: getLogger
      summary: Get Logger
      description: Returns the configuration for a specific logger by name.
      tags:
        - Loggers
      parameters:
        - name: name
          in: path
          required: true
          description: Logger name (e.g., com.example.service)
          schema:
            type: string
            example: com.example.service.UserService
      responses:
        '200':
          description: Logger configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoggerDetail'
        '404':
          description: Logger not found
    post:
      operationId: setLoggerLevel
      summary: Set Logger Level
      description: >-
        Configures the log level for a specific logger at runtime. Pass null to
        reset to the parent logger's effective level.
      tags:
        - Loggers
      parameters:
        - name: name
          in: path
          required: true
          description: Logger name
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogLevelRequest'
      responses:
        '204':
          description: Logger level updated
        '400':
          description: Invalid log level
  /threaddump:
    get:
      operationId: getThreadDump
      summary: Get Thread Dump
      description: >-
        Returns a snapshot of all live threads in the JVM including stack traces,
        thread states, and lock information.
      tags:
        - Threads
      responses:
        '200':
          description: Thread dump
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadDumpResponse'
            text/plain:
              schema:
                type: string
  /scheduledtasks:
    get:
      operationId: getScheduledTasks
      summary: Get Scheduled Tasks
      description: >-
        Returns all scheduled tasks registered in the application context,
        including cron, fixed-rate, and fixed-delay tasks.
      tags:
        - Scheduling
      responses:
        '200':
          description: Scheduled tasks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTasksResponse'
components:
  schemas:
    HealthResponse:
      type: object
      description: Overall application health aggregating all health indicators
      properties:
        status:
          type: string
          description: Overall health status
          enum: [UP, DOWN, OUT_OF_SERVICE, UNKNOWN]
        components:
          type: object
          description: Health status of individual components
          additionalProperties:
            $ref: '#/components/schemas/ComponentHealth'
    ComponentHealth:
      type: object
      description: Health status of a single component
      properties:
        status:
          type: string
          description: Component status
          enum: [UP, DOWN, OUT_OF_SERVICE, UNKNOWN]
        details:
          type: object
          description: Additional component-specific health details
          additionalProperties: true
        components:
          type: object
          description: Nested component health (for composite indicators)
          additionalProperties:
            $ref: '#/components/schemas/ComponentHealth'
    InfoResponse:
      type: object
      description: Application information from registered InfoContributors
      properties:
        build:
          type: object
          description: Build information from META-INF/build-info.properties
          properties:
            artifact:
              type: string
            group:
              type: string
            name:
              type: string
            version:
              type: string
            time:
              type: string
              format: date-time
        git:
          type: object
          description: Git commit information from git.properties
          properties:
            branch:
              type: string
            commit:
              type: object
              properties:
                id:
                  type: string
                time:
                  type: string
                  format: date-time
        java:
          type: object
          description: JVM runtime information
          properties:
            version:
              type: string
            vendor:
              type: object
            runtime:
              type: object
            jvm:
              type: object
        os:
          type: object
          description: Operating system information
          properties:
            name:
              type: string
            version:
              type: string
            arch:
              type: string
    MetricsList:
      type: object
      description: Available Micrometer metric names
      properties:
        names:
          type: array
          items:
            type: string
          example:
            - jvm.memory.used
            - jvm.gc.pause
            - http.server.requests
            - process.uptime
            - system.cpu.usage
    MetricDetail:
      type: object
      description: Measurements and metadata for a specific metric
      properties:
        name:
          type: string
          description: Metric name
        description:
          type: string
          description: Human-readable metric description
        baseUnit:
          type: string
          description: Base measurement unit (bytes, seconds, etc.)
        measurements:
          type: array
          items:
            type: object
            properties:
              statistic:
                type: string
                enum: [COUNT, TOTAL, MAX, VALUE, ACTIVE_TASKS, DURATION, TOTAL_TIME]
              value:
                type: number
        availableTags:
          type: array
          items:
            type: object
            properties:
              tag:
                type: string
              values:
                type: array
                items:
                  type: string
    EnvironmentResponse:
      type: object
      description: Application environment organized by property source
      properties:
        activeProfiles:
          type: array
          description: Currently active Spring profiles
          items:
            type: string
        defaultProfiles:
          type: array
          description: Default Spring profiles
          items:
            type: string
        propertySources:
          type: array
          description: Ordered list of property sources
          items:
            $ref: '#/components/schemas/PropertySource'
    PropertySource:
      type: object
      description: A single property source with its properties
      properties:
        name:
          type: string
          description: Property source name
        properties:
          type: object
          description: Properties from this source
          additionalProperties:
            type: object
            properties:
              value:
                description: Property value (may be masked for sensitive values)
              origin:
                type: string
                description: Where this property was defined
    PropertyDetail:
      type: object
      description: Detail for a specific environment property
      properties:
        property:
          type: object
          properties:
            source:
              type: string
              description: Property source name
            value:
              description: Current property value
        activeContexts:
          type: array
          items:
            type: string
    LoggersResponse:
      type: object
      description: All loggers with their levels
      properties:
        levels:
          type: array
          description: Available log levels
          items:
            type: string
          example: [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF]
        loggers:
          type: object
          description: Logger configurations keyed by logger name
          additionalProperties:
            $ref: '#/components/schemas/LoggerDetail'
        groups:
          type: object
          description: Logger groups (Spring Boot defined groups)
          additionalProperties:
            type: object
    LoggerDetail:
      type: object
      description: Configuration for a single logger
      properties:
        configuredLevel:
          type: string
          description: Explicitly configured level (null if not set)
          enum: [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF]
          nullable: true
        effectiveLevel:
          type: string
          description: Effective level inherited from parent if not explicitly set
          enum: [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF]
    LogLevelRequest:
      type: object
      description: Request body to set a logger level
      properties:
        configuredLevel:
          type: string
          description: Log level to set (null to reset)
          enum: [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF]
          nullable: true
    ThreadDumpResponse:
      type: object
      description: JVM thread dump snapshot
      properties:
        threads:
          type: array
          items:
            type: object
            properties:
              threadName:
                type: string
              threadId:
                type: integer
                format: int64
              blockedTime:
                type: integer
                format: int64
              blockedCount:
                type: integer
                format: int64
              waitedTime:
                type: integer
                format: int64
              waitedCount:
                type: integer
                format: int64
              lockName:
                type: string
                nullable: true
              lockOwnerId:
                type: integer
                format: int64
              lockOwnerName:
                type: string
                nullable: true
              daemon:
                type: boolean
              inNative:
                type: boolean
              suspended:
                type: boolean
              threadState:
                type: string
                enum: [NEW, RUNNABLE, BLOCKED, WAITING, TIMED_WAITING, TERMINATED]
              priority:
                type: integer
              stackTrace:
                type: array
                items:
                  type: object
                  properties:
                    classLoaderName:
                      type: string
                    moduleName:
                      type: string
                    moduleVersion:
                      type: string
                    methodName:
                      type: string
                    fileName:
                      type: string
                    lineNumber:
                      type: integer
                    className:
                      type: string
                    nativeMethod:
                      type: boolean
    ScheduledTasksResponse:
      type: object
      description: All scheduled tasks registered in the application
      properties:
        cron:
          type: array
          description: Tasks scheduled with cron expressions
          items:
            $ref: '#/components/schemas/ScheduledTask'
        fixedDelay:
          type: array
          description: Tasks scheduled with fixed delay
          items:
            $ref: '#/components/schemas/ScheduledTask'
        fixedRate:
          type: array
          description: Tasks scheduled with fixed rate
          items:
            $ref: '#/components/schemas/ScheduledTask'
        custom:
          type: array
          description: Tasks using custom scheduling triggers
          items:
            $ref: '#/components/schemas/ScheduledTask'
    ScheduledTask:
      type: object
      description: A single scheduled task
      properties:
        runnable:
          type: object
          properties:
            target:
              type: string
              description: Fully qualified method name
        expression:
          type: string
          description: Cron expression (for cron tasks)
        initialDelay:
          type: integer
          format: int64
          description: Initial delay in milliseconds
        interval:
          type: integer
          format: int64
          description: Fixed rate or delay in milliseconds