SkyWalking OAP 与 Satellite 自可观测性（SO11Y）仪表盘实战指南

SkyWalking OAP 与 Satellite 自可观测性（SO11Y）仪表盘实战指南

【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalking

SkyWalking OAP 后端本身是一个分布式流式处理系统，其运行状态（JVM、GC、线程、Trace/Mesh 分析、持久化等）同样需要被观测。SkyWalking 为此提供了自可观测性（Self Observability，简称 so11y）能力：OAP 内部以 Prometheus 格式收集并导出自身指标，再经由 OpenTelemetry Collector（或 OAP 自身）回流到 OAP Server，最终通过内置仪表盘或 GraphQL API 呈现。本文以docs/en/setup/backend/dashboards-so11y.md为主线，完整讲解 OAP 与 Satellite 两类自可观测仪表盘的数据链路、部署配置、指标含义与仪表盘定制方法，读完即可在生产环境落地一套可用的自监控方案。

一、自可观测性（so11y）是什么

SkyWalking 的"自可观测性"指的是OAP 后端对自己的观测：它收集自身运行时的指标数据，供运维团队了解 OAP 集群的健康状况与资源使用情况。这套机制有两个直接产出：

1. Prometheus 格式的指标端点：OAP 在内部收集指标并通过 HTTP 端点暴露，供 Prometheus、Grafana 或 OpenTelemetry Collector 消费；
2. 内置监控仪表盘：SkyWalking UI 中预置了so11y_oap、so11y_satellite两套仪表盘模板，直接可视化这些自观测指标。

从实现层面看，SO11Y_OAP与SO11Y_SATELLITE在 Layer.java 中被定义为两个独立的 Layer 枚举（分别为11与12），这意味着 OAP 与 Satellite 的自观测数据会作为独立的服务（Service）进入 SkyWalking 的指标体系，拥有独立的服务层级（见 hierarchy-definition.yml）。

二、OAP 自观测仪表盘的数据链路（Data Flow）

原文档给出了 OAP 自观测数据的完整流转过程，共 4 步：

1. OAP 内部采集并暴露指标：SkyWalking OAP 内部收集自身运行指标，并暴露一个 Prometheus HTTP 端点供外部抓取；
2. 抓取指标：SkyWalking OAP 自身（或 OpenTelemetry Collector，在 Kubernetes 场景下更推荐后者）从步骤 (1) 的 Prometheus 端点抓取指标；
3. 推送指标：OAP（或 OpenTelemetry Collector）通过OpenTelemetry gRPC exporter将指标推送到 SkyWalking OAP Server；
4. 解析存储：SkyWalking OAP Server 使用 MAL（Metric Analysis Language）（对应仓库文档为 docs/en/concepts-and-designs/mal.md）解析表达式，对指标进行过滤、计算、聚合，并将结果入库。

其中第 4 步的具体解析规则由 otel-rules/oap.yaml 定义。该文件以filter开头：

filter: "{ tags -> tags.job_name == 'skywalking-so11y' }" # The OpenTelemetry job name expSuffix: instance(['service'], ['host_name'], Layer.SO11Y_OAP) metricPrefix: meter_oap

• filter确保只处理来自skywalking-so11y这个 OpenTelemetry job 的指标（与下文抓取配置中的job_name一一对应）；
• expSuffix将数据按service与host_name两个标签归并为instance 维度，Layer 固定为SO11Y_OAP；
• metricPrefix为所有生成的指标名统一添加meter_oap前缀，例如jvm_threads_current经规则转换后成为meter_oap_jvm_thread_live_count。

三、环境搭建：让自观测数据跑起来

OAP 自观测默认是关闭的（selector: ${SW_TELEMETRY:none}），需要按 backend-telemetry.md 的指引分别启用 Prometheus 遥测与 OpenTelemetry 接收器。搭建方式分为静态地址与 Kubernetes 服务发现两种场景。

3.1 静态 IP 或主机名场景

在application.yml中做两步配置：

第 1 步：启用 Prometheus 遥测（telemetry）

telemetry: selector: ${SW_TELEMETRY:prometheus} prometheus: host: 127.0.0.1 port: 1543

完整可配置项如下（均支持环境变量覆盖）：

telemetry: selector: ${SW_TELEMETRY:none} none: prometheus: host: ${SW_TELEMETRY_PROMETHEUS_HOST:0.0.0.0} port: ${SW_TELEMETRY_PROMETHEUS_PORT:1234} sslEnabled: ${SW_TELEMETRY_PROMETHEUS_SSL_ENABLED:false} sslKeyPath: ${SW_TELEMETRY_PROMETHEUS_SSL_KEY_PATH:""} sslCertChainPath: ${SW_TELEMETRY_PROMETHEUS_SSL_CERT_CHAIN_PATH:""}

端点开启后位于http://0.0.0.0:1234/与http://0.0.0.0:1234/metrics。如需 HTTPS 暴露，可设置sslEnabled: true并指定私钥与证书链路径（sslKeyPath/sslCertChainPath），证书文件更新后 OAP 会自动重新加载。

第 2 步：配置 OpenTelemetry Collector 抓取

官方提供了一个可直接参考的 E2E 测试配置：test/e2e-v2/cases/so11y/otel-collector-config.yaml，其中包含了 prometheus receiver 抓取 OAP 指标、再由 otlp exporter 推回 OAP 的完整 Collector 配置，可作为最小可运行模板。

3.2 Kubernetes 服务发现场景

在 Kubernetes 上部署 OAP 集群时，Pod 没有静态 IP 或主机名，此时推荐利用 OpenTelemetry Collector 的 Kubernetes 服务发现能力自动发现 oap-server 实例并抓取、转发指标（接收端为 OAP 的 OpenTelemetry receiver）。

1) 配置 oap-server：

• 设置指标端口：

  prometheus-port: 1234

• 设置环境变量：

  SW_TELEMETRY=prometheus SW_OTEL_RECEIVER=default SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES=oap

以 Apache SkyWalking Kubernetes Helm Chart 安装为例：

helm -n istio-system install skywalking skywalking \ --set elasticsearch.replicas=1 \ --set elasticsearch.minimumMasterNodes=1 \ --set elasticsearch.imageTag=7.5.1 \ --set oap.replicas=2 \ --set ui.image.repository=$HUB/skywalking-ui \ --set ui.image.tag=$TAG \ --set oap.image.tag=$TAG \ --set oap.image.repository=$HUB/skywalking-oap \ --set oap.storageType=elasticsearch \ --set oap.ports.prometheus-port=1234 \ # <<< Expose self observability metrics port --set oap.env.SW_TELEMETRY=prometheus \ --set oap.env.SW_OTEL_RECEIVER=default \ # <<< Enable Otel receiver --set oap.env.SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES=oap # <<< Add oap analyzer for Otel metrics

其中SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES=oap是关键：它让 OAP 的 OpenTelemetry receiver 加载 otel-rules/oap.yaml 这份 MAL 规则来处理自观测指标。

2) 配置 OpenTelemetry Collector 的抓取任务：

- job_name: 'skywalking-so11y' # make sure to use this in the so11y.yaml to filter only so11y metrics metrics_path: '/metrics' kubernetes_sd_configs: - role: pod relabel_configs: - source_labels: [__meta_kubernetes_pod_container_name, __meta_kubernetes_pod_container_port_name] action: keep regex: oap;prometheus-port - source_labels: [] target_label: service replacement: oap-server - source_labels: [__meta_kubernetes_pod_name] target_label: host_name regex: (.+) replacement: $$1

这段配置的要点：

• job_name必须保持为skywalking-so11y，因为 otel-rules/oap.yaml 中的filter正是按该 job 名过滤，从而只处理自观测指标；
• relabel_configs通过容器名oap与端口名prometheus-port精确匹配目标 Pod，避免误抓其他容器；
• 为指标打上service=oap-server与host_name=<pod 名>两个标签，与 MAL 规则的expSuffix维度（service、host_name）对齐，保证每个 OAP 实例都能在仪表盘中单独成行。

3.3 数据回流后发生了什么

指标从 OTel gRPC exporter 推送到 OAP 的 OpenTelemetry receiver 后，OAP 依据 otel-rules/oap.yaml 中的metricsRules逐条解析。以 CPU 指标为例：

- name: instance_cpu_percentage exp: (process_cpu_seconds_total * 100).sum(['service', 'host_name']).rate('PT1M')

原始 Prometheus 计数器process_cpu_seconds_total经乘以 100、按service+host_name求和、再做PT1M（1 分钟）速率计算，最终生成meter_oap_instance_cpu_percentage（CPU 百分比）。所有规则生成的都是带meter_oap前缀的指标，与下方指标表中的名称一一对应。

四、OAP 自观测监控：指标全景

自可观测监控用于监控 OAP 服务器自身的状态与资源。在 SkyWalking 中，oap-server是一个Service，归属于Layer: SO11Y_OAP。其指标数据源均为oap self observability，完整指标表如下：

这些指标可按用途归纳为几组，便于日常运维排查：

• JVM 资源：内存meter_oap_instance_jvm_memory_bytes_used（MB）、CPUmeter_oap_instance_cpu_percentage（%）、类加载meter_oap_jvm_class_*、线程状态meter_oap_jvm_thread_*（live / peak / daemon 及 runnable / blocked / waiting / timed_waiting 细分）。
• GC 表现：meter_oap_instance_jvm_gc_count、meter_oap_instance_jvm_young_gc_time、meter_oap_instance_jvm_old_gc_time。其 MAL 规则通过tagMatch('gc', ...)匹配常见 GC 收集器名称，再分别映射为 young / old 两个维度，例如将PS Scavenge、G1 Young Generation归为 young，将PS MarkSweep、G1 Old Generation归为 old。
• 分析性能：Trace 分析相关的meter_oap_instance_trace_count、meter_oap_instance_trace_latency_percentile（P50/P70/P90/P99）、meter_oap_instance_trace_analysis_error_count；Mesh 分析相关的meter_oap_instance_mesh_count、meter_oap_instance_mesh_latency_percentile、meter_oap_instance_mesh_analysis_error_count。百分位指标均来自 Prometheus histogram 的histogram_percentile([50,70,90,99])计算。
• 持久化能力：meter_oap_instance_persistence_prepare_count、meter_oap_instance_persistence_execute_count（每 5 分钟统计），以及对应的耗时百分位meter_oap_instance_persistence_prepare_percentile、meter_oap_instance_persistence_execute_percentile，是判断 OAP 落库是否成为瓶颈的关键指标。
• 内部机制：meter_oap_instance_metrics_aggregation展示 L1/L2 两级聚合速率（规则中按level标签映射为L1 aggregation/L2 aggregation）；meter_oap_instance_metrics_persistent_cache展示指标缓存命中与未命中计数。

五、Satellite 自可观测监控

SkyWalking Satellite 是 SkyWalking 生态中的轻量级数据转发代理（可作为 Agent 与 OAP 之间的缓冲层）。Satellite 同样以Prometheus 格式与 SkyWalking 指标服务 protobuf 格式收集并导出自身指标，并提供仪表盘可视化。

5.1 数据链路

Satellite 的自观测数据链路更短：

1. SkyWalking Satellite 内部收集指标数据，并将指标直接推送到 SkyWalking OAP；
2. SkyWalking OAP Server 使用 MAL 解析表达式，对指标进行过滤、计算、聚合并存储。

与之对应的 MAL 规则位于 meter-analyzer-config/satellite.yaml：

expSuffix: service(['service'], Layer.SO11Y_SATELLITE) metricPrefix: satellite

与 OAP 的instance(...)维度不同，Satellite 的规则使用service(['service'])，Layer 为SO11Y_SATELLITE，生成的指标统一带satellite前缀。

5.2 环境搭建

1. 配置 SkyWalking Satellite 的 Telemetry Exporter（将指标以 SkyWalking 格式导出到 OAP）；
2. 在 OAP 侧启用 OpenTelemetry receiver（SW_OTEL_RECEIVER=default），并确认 OAP 已加载卫星指标的解析规则。

5.3 Satellite 指标全景

同样地，oap-server作为 OAP 中的Service，落于Layer: SO11Y_OAP（此处文档沿用 OAP 的自观测说明，实际 Satellite 数据归属SO11Y_SATELLITE，见上文 Layer 枚举）。Satellite 指标表如下：

从 satellite.yaml 的规则实现可以看到各指标的原始来源：

• satellite_service_receive_event_count←sw_stl_gatherer_receive_count（下游事件接收数）；
• satellite_service_fetch_event_count←sw_stl_gatherer_fetch_count（下游事件拉取数）；
• satellite_service_queue_input_count←sw_stl_queue_output_count（入队事件数）；
• satellite_service_send_event_count←sw_stl_sender_output_count（向上游推送事件数）；
• satellite_service_queue_used_count←sw_stl_pipeline_queue_partition_size（pipeline 队列已用容量）；
• satellite_service_server_cpu_utilization←sw_stl_grpc_server_cpu_gauge（CPU 利用率）；
• satellite_service_grpc_connect_count←sw_stl_grpc_server_connection_count（gRPC 连接数）。

前三类事件计数均带pipe、status标签并按PT1M求增量（.increase("PT1M")），可以按 pipeline 维度观察数据吞吐与丢弃情况。

六、仪表盘定制（Customizations）

自可观测仪表盘并非固定不可变，SkyWalking 允许用户自定义自己的指标、表达式与仪表盘面板。

6.1 指标定义与表达式规则

• Prometheus 抓取规则：位于打包后配置目录的config/fetcher-prom-rules/self.yaml，用于 OAP 直接抓取自身 Prometheus 端点时的指标过滤与预计算。该目录由发布装配文件 binary.xml 中的fetcher-prom-rules/*.yaml条目打包进发行包；
• MAL 解析规则：位于config/otel-rules/oap.yaml，即仓库中的 oap-server/server-starter/src/main/resources/otel-rules/oap.yaml。新增一个自观测指标的标准做法是：
  1. 在 Prometheus 端确认原始指标已暴露；
  2. 在metricsRules下新增一条name（指标名）+exp（MAL 表达式）规则；
  3. 重启或热加载后，新指标即以meter_oap前缀出现在查询接口中。

6.2 仪表盘面板配置

OAP 的仪表盘面板配置位于打包后目录的config/ui-initialized-templates/so11y_oap，对应仓库源码位置：

• so11y_oap/so11y-service.json：服务级（Service）自观测仪表盘，展示整个 OAP 服务维度的聚合视图；
• so11y_oap/so11y-instance.json：实例级（Instance）自观测仪表盘，按单个 OAP 实例展示细分指标；
• so11y_satellite/so11y-root.json：Satellite 自观测仪表盘。

从 so11y-instance.json 可以看到面板结构：采用Tab组织多个监控页签（如Status），页签内以Widget栅格布局，每个 Widget 通过expressions字段绑定一个或多个查询表达式。例如 CPU 面板：

{ "widget": { "title": "CPU (%)" }, "graph": { "type": "Line", "step": false }, "expressions": ["meter_oap_instance_cpu_percentage"] }

而内存面板则直接在表达式里做单位换算：

"expressions": ["meter_oap_instance_jvm_memory_bytes_used/1024/1024"]

（原始字节数除以 1024² 转为 MB，与指标表MB单位一致。）

由于打包装配 binary.xml 会将ui-initialized-templates/*/*.json与menu.yaml一并放入发行包的config/目录，用户在发行包中修改这些 JSON 即可定制面板布局、图表类型与查询表达式；OAP 启动时会由 UITemplateInitializer.java 加载并注册这些模板。

七、可选方案：Prometheus + Grafana 集成

除了回流 OAP 自监控外，用户也可以直接用 Prometheus 抓取 OAP 的遥测端点，接入自己的 Prometheus + Grafana 体系。Prometheus 作为 telemetry 实现者被官方支持：

telemetry: selector: ${SW_TELEMETRY:prometheus} prometheus:

Grafana 侧官方提供了两套仪表盘配置：

• grafana-cluster.json：SkyWalking OAP 集群监控仪表盘；
• grafana-instance.json：SkyWalking OAP 实例监控仪表盘。

需要特别说明：自 2021 年 4 月 21 日起，Grafana 项目已改用AGPL-v3许可证，不再兼容 Apache 2.0，因此官方将该方案标注为"可选而非推荐"，在引入 Grafana 前请自行核对许可证要求。

八、常见问题与排查要点

• 仪表盘无数据：优先确认SW_TELEMETRY=prometheus是否生效，curl http://<oap-host>:1234/metrics是否返回指标；再确认 OTel Collector 的job_name是否为skywalking-so11y，因为 MALfilter严格按该名称过滤。
• K8s 场景抓不到指标：检查relabel_configs中容器名与端口名是否与 OAP 实际暴露一致（oap/prometheus-port），service与host_name标签是否成功注入。
• 指标名对不上：所有入库指标都带meter_oap前缀（OAP）或satellite前缀（Satellite），在 UI/GraphQL 查询时务必使用前缀后的完整名称。
• 需要查看最新动态：官方发布说明中会记录自观测相关变更，可参考 docs/en/changes 下的版本变更文档。

九、小结

SkyWalking 的自可观测性（so11y）机制让"监控系统自身"变得简单：OAP 通过 Prometheus 端点暴露运行指标，经 OpenTelemetry Collector 回流后由 MAL 规则（otel-rules/oap.yaml）解析入库，最终在预置的so11y_oap/so11y_satellite仪表盘（ui-initialized-templates）中可视化；用户既可以定制指标与面板，也可以整体切换到 Prometheus + Grafana 方案。这套闭环能力使 OAP 自身的 JVM、GC、Trace/Mesh 分析、持久化等核心指标始终处于可观测状态，是保障 SkyWalking 生产集群稳定运行的基石。

【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalking