Observability Starter

受众：开发者摘要：基于 Spring Boot Actuator 的健康检查 / 应用信息 / 基础指标。框架扩展 springOpen 健康指示器和 info 端点，提供 Micrometer / Prometheus 指标出口和业务指标 contract，并预留 OpenTelemetry 首段配置 contract。

何时使用

场景	建议
容器存活 / 就绪探针	`/actuator/health/{liveness,readiness}`
确认当前部署版本	`/actuator/info` 看 `springOpen.version`
查 JVM / HTTP / 线程基础指标	`/actuator/metrics`
Prometheus 抓取指标	`/actuator/prometheus`
业务指标接入	注入 `BusinessObservationMetrics`
业务事件 / 错误定位	不用本 starter，用 logging.md
链路追踪 / 调用拓扑	不在本 starter 范围，后续接 OpenTelemetry / SkyWalking
全套监控告警平台对接	使用 Prometheus 样板和外部告警平台组合

观测回答「应用是否健康、版本是什么、基础指标是否可读」。事件记录和问题定位走日志。

快速开始

默认应用装配已显式引入 spring-open-starter-observability，启动后无需额外配置即可获得默认端点：

bash

curl http://localhost:8000/api/health
curl http://localhost:8000/actuator/health
curl http://localhost:8000/actuator/info
curl http://localhost:8000/actuator/metrics
curl http://localhost:8000/actuator/prometheus

按需引入：

xml

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-observability</artifactId>
</dependency>

默认端点

端点	说明
`/api/health`	统一 API 健康状态，返回 `Result` 包装的轻量存活 / 就绪摘要
`/actuator/health`	应用健康状态
`/actuator/health/liveness`	存活探针
`/actuator/health/readiness`	就绪探针
`/actuator/info`	应用和框架信息
`/actuator/metrics`	Micrometer 基础指标入口
`/actuator/prometheus`	Prometheus 文本格式指标，非生产默认可通过 `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE` 暴露

/api/health 面向前端、网关或外部调用方，用统一业务响应结构快速判断服务是否可用；详细运维探针、组件详情和 Kubernetes liveness / readiness 仍使用 Spring Boot Actuator 的 /actuator/health 系列端点。

默认不开放全部 Actuator 端点。生产环境如需开放更多端点，应结合网关、内网、鉴权或运维网络控制。

配置项

yaml

management:
  endpoints:
    web:
      base-path: /actuator
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      probes:
        enabled: true
      show-details: never        # 生产建议 never，开发可 always
  info:
    env:
      enabled: true
  metrics:
    web:
      server:
        max-uri-tags: 1000
  prometheus:
    metrics:
      export:
        enabled: true

spring:
  open:
    observability:
      enabled: true
      info:
        enabled: true
        include-java: true
        include-spring-boot: true
      health:
        enabled: true
        include-details: true
      metrics:
        enabled: true
        business-enabled: true
        max-tag-length: 80
      open-telemetry:
        enabled: false
        service-name: spring-open-application
        environment: dev
        endpoint: http://localhost:4318
        trace-sample-ratio: 1.0
        metrics-enabled: true
        logs-enabled: false

配置	默认值	说明
`spring.open.observability.enabled`	`true`	启用开关
`spring.open.observability.info.enabled`	`true`	是否向 `/actuator/info` 写入 `springOpen` 字段
`spring.open.observability.info.include-java`	`true`	是否输出 Java 版本
`spring.open.observability.info.include-spring-boot`	`true`	是否输出 Spring Boot 版本
`spring.open.observability.health.enabled`	`true`	是否注册 `springOpen` 健康指示器
`spring.open.observability.health.include-details`	`true`	是否为健康指示器附加框架信息（受 `show-details` 限制）
`spring.open.observability.metrics.enabled`	`true`	是否启用指标扩展
`spring.open.observability.metrics.business-enabled`	`true`	是否注册业务指标门面
`spring.open.observability.metrics.max-tag-length`	`80`	指标 tag 最大长度，控制 provider / model / queue 等外部值带来的基数
`spring.open.observability.open-telemetry.enabled`	`false`	OpenTelemetry 配置 contract 开关；首段不自动装配 SDK exporter
`spring.open.observability.open-telemetry.service-name`	空	上报服务名，后续装配层可按 `spring.application.name` 兜底
`spring.open.observability.open-telemetry.environment`	空	部署环境，例如 `dev`、`staging`、`prod`
`spring.open.observability.open-telemetry.endpoint`	空	OTLP endpoint，例如 `http://localhost:4318`
`spring.open.observability.open-telemetry.trace-sample-ratio`	`1.0`	Trace 采样概率，运行时摘要会归一到 `0..1`
`spring.open.observability.open-telemetry.metrics-enabled`	`true`	是否导出 metrics 信号
`spring.open.observability.open-telemetry.logs-enabled`	`false`	是否导出 logs 信号

Provider

不提供 Provider 切换（Spring Boot Actuator 是唯一实现）。可通过扩展点：

实现 HealthIndicator 注册自定义健康检查
实现 InfoContributor 扩展 /actuator/info 内容
注入 BusinessObservationMetrics 写入第一批业务指标 contract
集成 MeterRegistry 桥接 Datadog 等其它指标平台；Prometheus registry 已随 starter 提供

源码机制骨架

类	职责
`ObservabilityAutoConfiguration`	在 Actuator info / health contract 存在且配置启用时，注册框架信息贡献器和健康指示器
`ObservabilityProperties`	绑定 `spring.open.observability.*`，控制全局开关、info 输出和 health 详情
`ObservabilityProperties.Metrics`	控制指标扩展、业务指标门面和 tag 长度
`ObservabilityProperties.OpenTelemetry`	绑定 OpenTelemetry 首段配置 contract，描述服务名、环境、OTLP endpoint、采样率和信号开关
`OpenTelemetryObservationSettings`	在 `open-telemetry.enabled=true` 时注册为运行时配置摘要 Bean；会按 `spring.application.name` 和 active profiles 兜底服务名 / 环境，并只向 info 暴露 endpoint 是否配置
`BusinessObservationMetrics`	框架中性业务指标门面，覆盖 queue 深度、scheduler 失败、payment callback 失败和 AI gateway 用量
`ObservabilityOperationsCatalog`	只读运维目录，汇总 `/api/health`、Actuator、Prometheus、OpenTelemetry 和告警样板 runbook；starter 内不暴露 HTTP，也不改变端点安全边界
`ObservabilityAdminApiController`	后台只读 API `/api/v1/admin/observability/operations`，由 `spring-open-core-observability` 提供，复用运维目录快照
`SpringOpenInfoContributor`	向 `/actuator/info` 写入 `springOpen` 信息块，默认包含应用名、版本、框架、Java 和 Spring Boot 版本
`SpringOpenHealthIndicator`	注册轻量健康指示器，默认返回 `UP`，可附加安全框架信息
`SiteHealthApiController`	提供 `/api/health` 统一 API 入口，返回轻量 liveness / readiness 摘要

运行链路：

应用启动时，只有 classpath 中存在 Actuator 的 InfoContributor 和 HealthIndicator contract，且 spring.open.observability.enabled=true 时才激活自动配置。
info.enabled=true 时注册 SpringOpenInfoContributor，在 /actuator/info 输出 springOpen 信息块。
health.enabled=true 时注册 SpringOpenHealthIndicator，在 /actuator/health 汇总中提供框架层健康状态。
端点是否暴露、health 详情是否展示、liveness / readiness 探针是否启用，仍由 Spring Boot 标准 management.* 配置决定。
/actuator/metrics 继续走 Micrometer / Actuator 标准入口；Prometheus registry 随 starter 提供，是否暴露 /actuator/prometheus 由 management.endpoints.web.exposure.include 决定。
open-telemetry.enabled=true 时注册 OpenTelemetryObservationSettings，后续 exporter 装配层或运行时诊断可读取服务名、环境、采样率和信号开关；/actuator/info 只展示 endpoint 是否配置，不输出 endpoint 原文。
站点模块提供 /api/health 轻量入口，基于 Spring Boot ApplicationAvailability 返回统一业务响应，不替代 /actuator/health 的运维详情。
open-telemetry.* 只作为稳定配置 contract，默认不开启，也不引入 OpenTelemetry SDK；后续独立装配层可读取该配置接入 trace / metrics / logs exporter。
ObservabilityOperationsCatalog 始终保持只读，starter 内不注册 Controller，不读取业务数据，不绕过 Actuator 暴露配置；后台管理、诊断脚本或部署检查需要观测入口摘要时注入该目录即可。默认应用通过 spring-open-core-observability 提供 /api/v1/admin/observability/operations 与 Admin 观测运维页。

运维目录 Contract

ObservabilityOperationsCatalog 面向后台管理面、部署检查和诊断脚本提供统一只读快照：

字段	说明
`enabled`	当前 `spring.open.observability.enabled` 是否启用
`actuatorBasePath`	当前 Actuator Web base path，默认 `/actuator`
`businessMetricsEnabled`	是否启用 `BusinessObservationMetrics` 业务指标门面
`openTelemetry*`	OpenTelemetry 配置 contract 的启用状态、服务名、环境和 endpoint 是否配置
`prometheusAlertRulesPath`	仓库内告警样板路径，默认 `docker/prometheus/alerts.yml`
`endpoints`	`/api/health`、`/actuator/health`、`/actuator/info`、`/actuator/metrics`、`/actuator/prometheus` 等端点路径和当前暴露预期
`runbookHints`	生产暴露边界、Prometheus 告警样板、OpenTelemetry exporter 和业务指标接入提示

运维目录只描述“当前配置预期”，不替代真实 HTTP 探测。发布或部署前仍应按目标环境执行 curl /api/health、curl /actuator/health、Prometheus 抓取和外部告警联动 smoke。后台管理员可在「观测运维」菜单查看同一份只读摘要，用于确认端点路径、暴露预期和 runbook 提示。

后台运维入口

spring-open-core-observability 默认随应用装配，提供：

后端 API：GET /api/v1/admin/observability/operations
权限码：observability:view
后台菜单：任务运维下的「观测运维」
前端页面：/observability/operations

该入口只读展示 ObservabilityOperationsCatalog 快照，不主动探测外部系统、不修改 Actuator 暴露配置、不替代 Prometheus / OTLP / 告警平台的真实联通验证。

业务指标 contract

业务模块不需要直接依赖 Prometheus。需要写入第一批生产指标时注入 BusinessObservationMetrics：

方法	Micrometer 名称	Prometheus 名称	说明
`updateQueueDepth(queueName, depth)`	`spring.open.queue.depth`	`spring_open_queue_depth`	队列深度快照
`incrementSchedulerFailure(taskName)`	`spring.open.scheduler.failures`	`spring_open_scheduler_failures_total`	调度任务失败次数
`incrementPaymentCallbackFailure(provider)`	`spring.open.payment.callback.failures`	`spring_open_payment_callback_failures_total`	支付回调失败次数
`recordAiGatewayUsage(provider, model, inputTokens, outputTokens)`	`spring.open.ai.gateway.requests` / `spring.open.ai.gateway.tokens`	`spring_open_ai_gateway_requests_total` / `spring_open_ai_gateway_tokens_total`	AI 网关请求和 token 用量

Tag 会做空值兜底和长度裁剪，避免 provider、model、queue 等外部输入造成无界高基数。业务侧仍应优先传稳定 code，不传用户输入、URL、traceId 或订单号。

Prometheus 告警样板和 Runbook

仓库提供 docker/prometheus/alerts.yml 作为 Prometheus 告警样板，覆盖：

实例宕机：SpringOpenInstanceDown
5xx 增长：SpringOpenHttpServerErrorsHigh
队列堆积：SpringOpenQueueDepthHigh
调度失败：SpringOpenSchedulerFailures
支付回调失败：SpringOpenPaymentCallbackFailures
磁盘剩余空间低：SpringOpenDiskFreeLow

接入步骤：

在 Prometheus 配置中抓取应用 /actuator/prometheus。
按部署环境复制或引用 docker/prometheus/alerts.yml。
生产环境如仍保持 application-prod.yml 的 health-only 暴露口径，需要显式设置 MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=health,info,metrics,prometheus，并确保端点只在内网、网关鉴权或运维网络可达。
触发告警后优先按 traceId、请求日志、业务审计日志和对应模块运维页定位，不把 /actuator/info 或 health 详情对公网开放。

可用时执行：

bash

promtool check rules docker/prometheus/alerts.yml

扩展边界

本 starter 不做业务审计、操作日志、请求 TraceId、慢请求记录或敏感字段脱敏，这些能力走 Logging / Audit 等对应模块。
本 starter 不内置 SkyWalking / Zipkin / Loki / ELK 等平台适配；OpenTelemetry 首段只提供配置 contract，需要 exporter 时通过后续独立装配层或部署配置接入。
自定义健康检查应实现 HealthIndicator，并为外部依赖探测设置超时，避免拖慢 readiness。
自定义 /actuator/info 内容应实现 InfoContributor，不要输出密钥、token、用户信息、租户数据或业务敏感统计。
生产环境 health 详情展示建议继续由 management.endpoint.health.show-details=never 或 when-authorized 控制。

返回示例

/actuator/info：

json

{
  "springOpen": {
    "name": "spring-open-application",
    "version": "0.7.0",
    "framework": "SpringOpen",
    "java": "17.0.x",
    "springBoot": "4.1.0",
    "openTelemetry": {
      "enabled": true,
      "serviceName": "spring-open-application",
      "environment": "prod",
      "endpointConfigured": true,
      "traceSampleRatio": 0.25,
      "metricsEnabled": true,
      "logsEnabled": false
    }
  }
}

openTelemetry 只有在 spring.open.observability.open-telemetry.enabled=true 时输出；其中 endpointConfigured 只表示是否配置 OTLP endpoint，不回显 endpoint 原文。

/api/health：

json

{
  "code": "0",
  "data": {
    "status": "UP",
    "liveness": "CORRECT",
    "readiness": "ACCEPTING_TRAFFIC",
    "name": "spring-open-application",
    "version": "0.7.0",
    "timestamp": 1781295390155
  },
  "message": "success",
  "timestamp": 1781295390155,
  "traceId": "..."
}

/actuator/health：

json

{
  "status": "UP"
}

是否展示 health 详情由 Spring Boot 标准配置 management.endpoint.health.show-details 控制。

与日志的边界

能力	归属
健康 / 信息 / 基础指标	`spring-open-starter-observability`（本文档）
请求日志、TraceId、慢请求、敏感字段脱敏	`spring-open-starter-logging`
业务运维日志（操作 / 登录 / 调度 / 通知 / 支付 / 开放平台调用）	`spring-open-core-iam` / `spring-open-core-audit` / `spring-open-core-scheduler` / `spring-open-core-queue` / `spring-open-core-runtime` / `spring-open-core-cashier` / `spring-open-module-open-platform`

常见搭配：

容器健康检查 → /actuator/health
部署版本确认 → /actuator/info
JVM / HTTP / 线程指标 → /actuator/metrics
Prometheus 抓取 → /actuator/prometheus
事件 / 错误定位 → 请求日志 + 业务日志

后续扩展（不在本 starter 默认范围）

OpenTelemetry trace / metrics / logs
日志采集平台对接（Loki / ELK）
SkyWalking / Zipkin 链路追踪
后台健康检查聚合页

注意事项

生产环境 show-details 建议 never 或 when-authorized，避免泄露依赖版本和内部信息
不要在 /actuator/info 输出业务统计或敏感字段
自定义 HealthIndicator 必须有超时控制，避免拖垮 readiness 探针

验证命令

bash

./mvnw -pl spring-open-starters/spring-open-starter-observability -am test -DskipITs
./mvnw -pl spring-open-starters/spring-open-starter-observability -am -Dtest=ObservabilityAutoConfigurationTest test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
./mvnw -pl spring-open-core/spring-open-core-site -am -Dtest=SiteHealthApiControllerTest test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
curl http://localhost:8000/api/health
curl http://localhost:8000/actuator/health
curl http://localhost:8000/actuator/info
curl http://localhost:8000/actuator/prometheus

Observability Starter ​

何时使用 ​

快速开始 ​

默认端点 ​

配置项 ​

Provider ​

源码机制骨架 ​

运维目录 Contract ​

后台运维入口 ​

业务指标 contract ​

Prometheus 告警样板和 Runbook ​

扩展边界 ​

返回示例 ​

与日志的边界 ​

后续扩展（不在本 starter 默认范围） ​

注意事项 ​

验证命令 ​

相关 ​

Observability Starter

何时使用

快速开始

默认端点

配置项

Provider

源码机制骨架

运维目录 Contract

后台运维入口

业务指标 contract

Prometheus 告警样板和 Runbook

扩展边界

返回示例

与日志的边界

后续扩展（不在本 starter 默认范围）

注意事项

验证命令

相关