Spring Boot 3 Application Observability

naftiko: "1.0.0-alpha1"

info:
  label: "Spring Boot 3 Application Observability"
  description: >-
    Workflow capability for monitoring and observing Spring Boot 3 applications
    using Actuator endpoints. Provides unified access to health status, JVM and
    application metrics, environment configuration, logger management, and
    thread diagnostics for platform engineers and SREs.
  tags:
    - Spring Boot
    - Observability
    - Monitoring
    - SRE
    - Platform Engineering
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SPRING_BOOT_BASE_URL: SPRING_BOOT_BASE_URL

capability:
  consumes:
    - import: spring-boot-actuator
      location: ./shared/spring-boot-3-actuator.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: observability-api
      description: "Unified REST API for Spring Boot 3 application observability."
      resources:
        - path: /v1/health
          name: health
          description: "Application and component health status"
          operations:
            - method: GET
              name: get-health
              description: "Get overall application health"
              call: "spring-boot-actuator.get-health"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/health/{component}
          name: component-health
          description: "Individual component health"
          operations:
            - method: GET
              name: get-component-health
              description: "Get health for a specific component"
              call: "spring-boot-actuator.get-health-component"
              with:
                component: "rest.component"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/info
          name: info
          description: "Application build and git metadata"
          operations:
            - method: GET
              name: get-info
              description: "Get application information"
              call: "spring-boot-actuator.get-info"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/metrics
          name: metrics
          description: "Micrometer metrics list"
          operations:
            - method: GET
              name: list-metrics
              description: "List all available metric names"
              call: "spring-boot-actuator.list-metrics"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/metrics/{metricName}
          name: metric-detail
          description: "Single metric measurements with tag filtering"
          operations:
            - method: GET
              name: get-metric
              description: "Get measurements for a named metric"
              call: "spring-boot-actuator.get-metric"
              with:
                metricName: "rest.metricName"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/env
          name: environment
          description: "Application environment and configuration"
          operations:
            - method: GET
              name: get-environment
              description: "Get all environment properties"
              call: "spring-boot-actuator.get-environment"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/loggers
          name: loggers
          description: "Logger configuration"
          operations:
            - method: GET
              name: list-loggers
              description: "List all loggers with their levels"
              call: "spring-boot-actuator.list-loggers"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/loggers/{name}
          name: logger-detail
          description: "Individual logger management"
          operations:
            - method: GET
              name: get-logger
              description: "Get logger configuration"
              call: "spring-boot-actuator.get-logger"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: set-logger-level
              description: "Set logger level at runtime"
              call: "spring-boot-actuator.set-logger-level"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/threads
          name: threads
          description: "JVM thread diagnostics"
          operations:
            - method: GET
              name: get-thread-dump
              description: "Get JVM thread dump"
              call: "spring-boot-actuator.get-thread-dump"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/scheduled-tasks
          name: scheduled-tasks
          description: "Scheduled task registry"
          operations:
            - method: GET
              name: get-scheduled-tasks
              description: "List all scheduled tasks"
              call: "spring-boot-actuator.get-scheduled-tasks"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: observability-mcp
      transport: http
      description: "MCP server for AI-assisted Spring Boot 3 application observability and diagnostics."
      tools:
        - name: check-app-health
          description: "Check the overall health of the Spring Boot application including database, cache, and infrastructure components"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-health"
          outputParameters:
            - type: object
              mapping: "$."

        - name: check-component-health
          description: "Check health status for a specific component like db, redis, diskSpace, or rabbit"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-health-component"
          with:
            component: "tools.component"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-app-info
          description: "Get application build version, git commit hash, and runtime environment information"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-info"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-metrics
          description: "List all available Micrometer metrics registered in this application"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.list-metrics"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-metric
          description: "Get current measurements for a metric such as jvm.memory.used, http.server.requests, or hikaricp.connections.active"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-metric"
          with:
            metricName: "tools.metricName"
            tag: "tools.tag"
          outputParameters:
            - type: object
              mapping: "$."

        - name: inspect-environment
          description: "Inspect all application environment properties and their sources to diagnose configuration issues"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-environment"
          outputParameters:
            - type: object
              mapping: "$."

        - name: lookup-property
          description: "Look up the value and origin of a specific configuration property by key"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-environment-property"
          with:
            toMatch: "tools.propertyKey"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-loggers
          description: "List all loggers with their configured and effective log levels for debugging"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.list-loggers"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-logger
          description: "Get the current log level configuration for a specific logger class or package"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-logger"
          with:
            name: "tools.loggerName"
          outputParameters:
            - type: object
              mapping: "$."

        - name: set-logger-level
          description: "Temporarily set the log level for a logger (TRACE, DEBUG, INFO, WARN, ERROR) without restarting"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "spring-boot-actuator.set-logger-level"
          with:
            name: "tools.loggerName"
            level: "tools.level"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-thread-dump
          description: "Get a JVM thread dump to diagnose deadlocks, high CPU usage, or thread starvation"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-thread-dump"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-scheduled-tasks
          description: "List all @Scheduled tasks with their cron expressions or fixed-rate intervals"
          hints:
            readOnly: true
            openWorld: true
          call: "spring-boot-actuator.get-scheduled-tasks"
          outputParameters:
            - type: object
              mapping: "$."