Apache SkyWalking MicroMeter Observations 接入指南Spring 应用观测指标的上报与 OAP 后端配置【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalkingMicroMeter Observations 是 Micrometer 项目的一部分提供了统一的 Observation观测API。Apache SkyWalking 通过集成 Micrometer 1.10 系列的 API让 Spring 应用能够基于 Observation 语义把运行指标HTTP 请求、JVM、系统资源等发送到 SkyWalking 的 Meter 系统。本文从 Java Agent 端准备、OAP 后端接收器配置、Meter 分析规则文件解析到 Dashboard 展示完整讲解基于当前仓库v10 分支将 Spring Micrometer 观测指标接入 SkyWalking 的实战流程读完即可在自己的环境中落地 Spring Sleuth / Micrometer 观测数据的上报与可视化。整体工作链路Micrometer Observation 指标接入 SkyWalking 的完整链路由三段组成Spring 应用Java Agent 侧通过 SkyWalking Java Agent 的 Micrometer 1.10 工具包application-toolkit-micrometer-1.10拦截并采集 Spring 应用中的 Observation 指标通过 Meter 协议上报给 OAPOAP 后端接收与分析receiver-meter模块接收指标数据并送入 Meter 系统再由agent-analyzer模块根据meter-analyzer-config目录下的 MAL 规则文件如spring-micrometer.yaml对原始指标进行二次计算与命名UI 展示SkyWalking 默认提供 Spring Sleuth Dashboard展示由 Spring 上报的默认指标自定义指标需要按 自定义 Dashboard 文档 手动添加。从源码结构看Meter 系统的定位在 MeterFunction.java 中有明确说明“meter system accepts data from any number based metrics ecosystem, typically like Prometheus and Micrometer Application Monitoring”即 Meter 系统天然面向 Micrometer 这类基于数值的指标生态。前置条件Java Agent 端启用 Micrometer 工具包OAP 只能处理已经上报上来的指标因此在配置后端之前必须先确保 Spring 应用侧完成了 Agent 设置。请参照 SkyWalking Java Agent 的 Observations 文档 在 Spring 应用中启用 Micrometer 1.10 工具包。说明Agent 端工具包的名称、依赖坐标与接入方式以 SkyWalking Java Agent 仓库对应版本文档为准本文聚焦 OAP 后端的对接配置。OAP 后端接收器配置后端配置共分三步全部位于 OAP 的application.yml中默认路径为$SKYWALKING_BASE_DIR/config/application.yml仓库内模板见 oap-server/server-starter/src/main/resources/application.yml。第一步启用 meter 接收器在application.yml中确保receiver-meter模块处于启用状态receiver-meter: selector: ${SW_RECEIVER_METER:default} default:receiver-meter负责接收 Java Agent 通过 Meter 协议 上报的指标数据并送入 Meter 系统。selector支持通过环境变量SW_RECEIVER_METER覆盖默认值为default即启用该模块的默认实现。仓库模板中该配置位于 application.yml 第 391-393 行。关于该模块更完整的说明包括 Kafka Fetcher 场景下的启用方式可参考 backend-meter.md。第二步确认 Meter 分析规则文件Meter 接收器本身不做任何指标语义理解真正的规则定义在meter-analyzer-config配置文件里。仓库已经内置了一份开箱即用的 Spring Micrometer 规则文件spring-micrometer.yaml。这份文件的完整内容如下省略 ASF License 头expSuffix: instance([service], [instance], Layer.GENERAL) metricPrefix: meter metricsRules: - name: http_server_requests_count exp: http_server_requests_count.increase(PT1M) - name: http_server_requests_duration exp: http_server_requests_sum.increase(PT1M) - name: jdbc_connections_active exp: jdbc_connections_active - name: jdbc_connections_idle exp: jdbc_connections_idle - name: jdbc_connections_max exp: jdbc_connections_max - name: jvm_classes_loaded exp: jvm_classes_loaded - name: jvm_classes_unloaded exp: jvm_classes_unloaded.increase(PT1M) - name: jvm_gc_pause_count exp: jvm_gc_pause_count.increase(PT1M) - name: jvm_gc_pause_duration exp: jvm_gc_pause_sum.increase(PT1M) - name: jvm_memory_committed exp: jvm_memory_committed - name: jvm_memory_max exp: jvm_memory_max - name: jvm_memory_used exp: jvm_memory_used - name: jvm_threads_daemon exp: jvm_threads_daemon - name: jvm_threads_live exp: jvm_threads_live - name: jvm_threads_peak exp: jvm_threads_peak - name: process_cpu_usage exp: process_cpu_usage.multiply(100) - name: system_cpu_usage exp: system_cpu_usage.multiply(100) - name: system_load_average_1m exp: system_load_average_1m - name: tomcat_sessions_active_current exp: tomcat_sessions_active_current - name: tomcat_sessions_active_max exp: tomcat_sessions_active_max - name: tomcat_sessions_rejected exp: tomcat_sessions_rejected.increase(PT1M) - name: process_files_max exp: process_files_max - name: process_files_open exp: process_files_open对关键字段的说明如下字段作用本文件取值expSuffix追加到文件内所有表达式的后缀instance([service], [instance], Layer.GENERAL)即以service instance为实体维度、Layer.GENERAL为通用层级生成指标metricPrefix插入指标名前缀最终存储名形如metricPrefix_raw_metric_namemeter因此http_server_requests_count规则生成的存储指标名为meter_http_server_requests_countmetricsRules规则列表每条包含name规则名与expMAL 表达式上表所列 24 条规则各表达式使用的 MAL 函数含义.increase(PT1M)计算最近 1 分钟ISO-8601 时长PT1M的增量适用于计数器类指标如http_server_requests_count、jvm_gc_pause_count、tomcat_sessions_rejected.multiply(100)将 0~1 之间的比率换算为百分数如process_cpu_usage、system_cpu_usage直接引用原始指标名无函数原样透传适用于 gauge 类指标如jvm_memory_used、jvm_threads_live。MAL 的完整语法与函数说明可参见 mal.md。如果你在 Agent 侧有自定义的 Micrometer 指标则需要按照 backend-meter.md 的说明新建一个 meter-analyzer-config 文件YAML 格式并在下一步的meterAnalyzerActiveFiles中启用它。关于自定义指标的上报可参考 backend-meter.md 的 Manual Meter API 一节。第三步在 agent-analyzer 中激活规则文件新建的 meter-analyzer-config 文件默认不会被启用必须通过agent-analyzer模块的meterAnalyzerActiveFiles显式声明。内置的spring-micrometer同样遵循此规则agent-analyzer: selector: ${SW_AGENT_ANALYZER:default} default: meterAnalyzerActiveFiles: ${SW_METER_ANALYZER_ACTIVE_FILES:spring-micrometer}配置要点meterAnalyzerActiveFiles填写不带.yaml扩展名的文件名多个文件用英文逗号,分隔支持通过环境变量SW_METER_ANALYZER_ACTIVE_FILES覆盖默认值此处设为spring-micrometer仓库模板 application.yml 第 271 行 的默认值为datasource,threadpool,satellite,go-runtime,python-runtime,continuous-profiling即spring-micrometer 默认并未激活需要按上文显式加入该文件该配置项在模块中对应agent-analyzer的meterAnalyzerActiveFiles属性负责在 OAP 启动时决定加载哪些 Meter 分析规则。注意OAP 只在启动bootstrap阶段加载 meter 配置若配置文件格式不合法OAP 可能启动失败。因此修改spring-micrometer.yaml或新增规则文件后必须重启 OAP 才能生效。Dashboard 配置SkyWalking 在**通用服务实例general service instance**下默认提供了Spring Sleuth Dashboard其中包含了 Spring Sleuth 默认上报的指标即上文spring-micrometer.yaml中定义的各项指标如 HTTP 请求计数/时长、JDBC 连接数、JVM 内存/线程/GC、系统 CPU 等。两种使用场景仅使用默认指标无需额外配置直接打开对应服务实例的 Dashboard 即可看到指标在应用侧新增了自定义指标并在后端配置了对应的 meter 规则文件此时需要按照 自定义 Dashboard 文档 的说明在 Dashboard 中新增对应的 Metrics 图表。UI 中的指标名使用带前缀的完整存储名即metricPrefix_name例如meter_http_server_requests_count这也是 backend-meter.md 中“The name with prefix can also be quoted in UI”的含义。支持的指标类型Micrometer Observation 接入后SkyWalking 支持三大类指标信息1. Application应用层指标对应规则名存储名前缀meter_含义HTTP 请求计数http_server_requests_count每分钟 HTTP 服务端请求次数增量HTTP 请求时长http_server_requests_duration每分钟 HTTP 服务端请求时长sum增量JDBC 连接数jdbc_connections_active/jdbc_connections_idle/jdbc_connections_maxJDBC 活跃 / 空闲 / 最大连接数Tomcat Session 数tomcat_sessions_active_current/tomcat_sessions_active_max/tomcat_sessions_rejectedSession 当前 / 最大活跃数、被拒绝数每分钟增量2. System系统层指标对应规则名含义CPU 使用率system_cpu_usage/process_cpu_usage系统 / 进程 CPU 使用率已乘以 100 转为百分比系统负载system_load_average_1m1 分钟系统平均负载进程文件数process_files_max/process_files_open进程可打开文件数上限 / 当前打开文件数3. JVMJVM 层指标对应规则名含义GC 暂停jvm_gc_pause_count/jvm_gc_pause_durationGC 暂停次数每分钟增量与暂停时长sum每分钟增量内存jvm_memory_max/jvm_memory_used/jvm_memory_committed堆/非堆内存最大值、已用量、已提交量线程jvm_threads_peak/jvm_threads_live/jvm_threads_daemon线程峰值数、存活数、守护线程数类加载jvm_classes_loaded/jvm_classes_unloaded已加载类数、已卸载类数每分钟增量上述三类指标与 spring-micrometer.yaml 中的 24 条metricsRules一一对应验证了文档描述与仓库内置规则的完全一致。底层原理Meter 系统与指标函数理解 Micrometer 接入离不开对 Meter 系统 的认知。与 OAL基于 Scope 定义不同Meter 系统聚焦于数据类型本身每个指标在声明阶段需要确定三个属性Metrics Name全局唯一避免与 OAL 变量名冲突Function Name决定分布式聚合、数值计算或降采样方式同时决定底层数据结构如avg对应 Long 型Scope Type取值包括service、instance、endpoint如spring-micrometer.yaml的expSuffix中使用了instance([service], [instance])实体维度。指标必须在bootstrap 阶段声明运行时不允许变更。Meter 系统支持的内置函数在 meter.md 中列出avg、histogram、percentile等从源码看实际注册的函数注解分布在 oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/meter/function 目录下例如avgAvgFunction、latestLatestFunction、max、min、sumHistogram等每个函数类通过MeterFunction(functionName ...)注解注册。而spring-micrometer.yaml中的increase(PT1M)、multiply(100)属于MALMetrics Analysis Language表达式层面的函数它们在进入 Meter 系统的绑定函数avg/latest/max 等之前完成原始样本的预处理。两者分工MAL 负责把 Agent 上报的原始指标加工成目标指标Meter 绑定函数负责最终的数据聚合与存储结构。注意事项与最佳实践rate/irate/increase尽量在客户端计算尽管 OAP 后端支持这些函数但 backend-meter.md 明确指出两点原因建议优先在客户端完成其一OAP 需要建立缓存来计算这些值增加后端开销其二一旦 Agent 重连到另一台 OAP 实例速率计算的时间窗口会断裂导致结果不准确。spring-micrometer.yaml中仍使用了increase(PT1M)属于后端兜底能力生产环境若有条件应优先在 Agent 侧聚合。配置文件变更需重启Meter 分析规则在 OAP 启动时一次性加载格式错误会导致启动失败修改后务必重启 OAP并检查日志确认规则加载成功。多文件启用用逗号分隔若同时使用spring-micrometer与自定义规则文件meterAnalyzerActiveFiles应写为spring-micrometer,your-custom-file不带扩展名。UI 指标名带前缀在 Dashboard 中引用的指标名必须是带metricPrefix的完整名称如meter_jvm_memory_used否则无法匹配到存储中的指标。【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考