AgentSkillsCN

spring-boot-observability

Spring Boot 4可观测性，配备Actuator、Micrometer与OpenTelemetry。当配置健康指标、健康检查、自定义指标、分布式追踪、暴露生产端点、Kubernetes探针、Cloud Run探针、日志记录或监控时，就使用此技能。涵盖Actuator端点安全、Micrometer计时器/计数器/仪表模式、OpenTelemetry跨度定制、存活/就绪探针设置以及指标标签最佳实践。

SKILL.md
--- frontmatter
name: spring-boot-observability
description: Spring Boot 4 observability with Actuator, Micrometer, and OpenTelemetry. Use when configuring health indicators, health checks, custom metrics, distributed tracing, production endpoint exposure, Kubernetes probes, Cloud Run probes, logging, or monitoring. Covers Actuator endpoint security, Micrometer Timer/Counter/Gauge patterns, OpenTelemetry span customization, liveness/readiness probe setup, and metric tag best practices.
spring-boot-version: "4.0"

Spring Boot Observability

Production observability with Actuator endpoints, Micrometer metrics, and OpenTelemetry tracing.

Core Components

ComponentPurpose
ActuatorHealth checks, info, metrics exposure, operational endpoints
MicrometerMetrics abstraction (Timer, Counter, Gauge, DistributionSummary)
OpenTelemetryDistributed tracing (default in Spring Boot 4)

Core Workflow

  1. •Add starters → actuator, micrometer-registry-*, opentelemetry
  2. •Configure endpoint exposure → Secure sensitive endpoints
  3. •Define health groups → Separate liveness from readiness
  4. •Add custom metrics → Business-specific measurements
  5. •Configure tracing → Sampling, propagation, export

Quick Patterns

See EXAMPLES.md for complete working examples including:

  • •Production Actuator Configuration with health groups and Kubernetes probes
  • •Custom Health Indicator with latency monitoring (Java + Kotlin)
  • •Custom Micrometer Metrics with Counter, Timer, and Gauge patterns
  • •OpenTelemetry Span Customization with Observation API
  • •OpenTelemetry Configuration for OTLP export
  • •Actuator Endpoint Access Control (Boot 4)

Spring Boot 4 Specifics

  • •OpenTelemetry is the default tracer (replaces Brave)
  • •Health Indicator imports from org.springframework.boot.health.contributor.*
  • •Endpoint Access Control with access: none/unrestricted/read-only

Detailed References

  • •Examples: See EXAMPLES.md for complete working code examples
  • •Troubleshooting: See TROUBLESHOOTING.md for common issues and Boot 4 migration
  • •Actuator Endpoints: See references/ACTUATOR.md for endpoint configuration, security, custom endpoints
  • •Micrometer Metrics: See references/METRICS.md for Timer, Counter, Gauge, DistributionSummary patterns
  • •Distributed Tracing: See references/TRACING.md for OpenTelemetry, span customization, context propagation

Anti-Pattern Checklist

Anti-PatternFix
DB checks in liveness probeMove to readiness group only
100% trace sampling in productionUse 10% or less
Exposing all endpoints publiclySeparate management port + auth
High-cardinality metric tagsUse low-cardinality tags only
Missing graceful shutdownAdd server.shutdown=graceful
No health probe groupsSeparate liveness and readiness

Related Skills

NeedSkill
Dependency validationspring-boot-verify
Actuator securityspring-boot-security
Actuator testingspring-boot-testing
Module metricsspring-boot-modulith

Critical Reminders

  1. •Separate liveness from readiness — Liveness: "is process alive?", Readiness: "can handle traffic?"
  2. •Low cardinality tags only — User IDs, request IDs = bad; status codes, regions = good
  3. •Secure Actuator endpoints — Use separate port or authentication
  4. •Sample traces in production — 100% sampling overwhelms collectors
  5. •Graceful shutdown — Allow in-flight requests to complete