SkyWalking Satellite 自观测仪表盘（SO11Y_SATELLITE）配置与定制实战指南-平芜编程栈

SkyWalking Satellite 自观测仪表盘（SO11Y_SATELLITE）配置与定制实战指南

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

导读

本文围绕 SkyWalking 后端（OAP Server）内置的Satellite 自观测（Self Observability）仪表盘展开，讲解 SkyWalking Satellite 遥测数据如何经由 OpenTelemetry Receiver 进入 OAP，如何通过 MAL 表达式完成指标的计算、聚合与落库，以及如何理解、校验和定制SO11Y_SATELLITE层的监控面板。读完本文，你将掌握从数据链路、指标口径到面板 JSON 定制与端到端验证的完整方法，可直接用于在生产环境监控 Satellite 自身的连接数、CPU、队列水位与事件吞吐。

背景：什么是 Satellite 自观测仪表盘

SkyWalking Satellite 是一个面向云原生基础设施的遥测数据采集与转发组件，它自身会以两种格式产出运行状态指标：Prometheus 格式与SkyWalking 指标服务 protobuffer 格式。这些指标用于描述 Satellite 自身的连接、CPU、管道队列与事件收发状态。

OAP Server 为此内置了名为Self-Observability-Satellite-Root的仪表盘（Dashboard），用于将上述指标可视化。从源码可见，Satellite 自观测在 OAP 中被建模为一个独立的 Layer：

// oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/Layer.java /** * Self Observability of OAP */ SO11Y_OAP(11, true), /** * Self Observability of Satellite */ SO11Y_SATELLITE(12, true),

SO11Y_SATELLITE与SO11Y_OAP同属自观测体系，位于 UI 左侧导航栏的Self Observability菜单分组下（见 menu.yaml 中self_observability_satellite菜单项，其layer即SO11Y_SATELLITE）。当 OAP 收到属于该 Layer 的指标数据后，仪表盘菜单会自动激活。

数据流：从 Satellite 到仪表盘的完整链路

原文档给出的数据流分为两步，结合仓库配置可以细化为如下完整链路：

采集与推送：SkyWalking Satellite 在内部采集自身指标（gRPC 连接数、CPU、队列状态、事件收发计数等），并将指标推送给 SkyWalking OAP Server。
接收与解析：OAP Server 通过OpenTelemetry Receiver（receiver-otel）接收这些指标，随后按照 MAL（Metrics Analysis Language）表达式进行过滤、计算、聚合，最终写入存储。
展示：UI 仪表盘以SO11Y_SATELLITE为 Layer、Service为实体类型，读取聚合后的指标进行可视化。

MAL 规则文件位于 meter-analyzer-config/satellite.yaml，其开头的两个关键声明定义了指标的归属与命名：

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

expSuffix：所有指标表达式统一按service标签聚合，并归属到Layer.SO11Y_SATELLITE层；
metricPrefix：生成的指标名统一以satellite为前缀（例如satellite_service_grpc_connect_count）。

环境搭建：两处配置缺一不可

1. 配置 Satellite 遥测导出器（Telemetry Exporter）

首先需要在 SkyWalking Satellite 侧启用遥测导出器（Telemetry Exporter），使 Satellite 能以 SkyWalking 指标服务 protobuffer 格式（或 Prometheus 格式）将自身指标对外推送。具体配置方法参考 Satellite 项目文档中telemetry-exporter的 feature 示例（README），核心是让 Satellite 与 OAP 建立 gRPC 连接并周期上报指标。

2. 启用 OAP 的 OpenTelemetry Receiver

然后在 OAP 侧激活receiver-otel，使 OAP 具备接收与解析该类指标的能力。原文档所指的配置详见 opentelemetry-receiver.md，要点如下：

该 Receiver 通过OTLP gRPC 服务处理器（otlphandler）接收指标；
必须显式激活，否则不生效：

receiver-otel: selector: ${SW_OTEL_RECEIVER:default} default: enabledHandlers: ${SW_OTEL_RECEIVER_ENABLED_HANDLERS:"otlp-metrics"} enabledOtelMetricsRules: ${SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES:"satellite"}

对应的环境变量等价形式：

export SW_OTEL_RECEIVER=default export SW_OTEL_RECEIVER_ENABLED_HANDLERS=otlp-metrics export SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES=satellite

需要注意：receiver-otel因其推模式（push mode）特性，只支持 MAL 规则文件中的group、defaultMetricLevel与metricsRules三个节点，satellite.yaml恰好只用到了这三者中的核心部分。规则文件位于$CLASSPATH/otel-rules或meter-analyzer-config目录下，OAP 在启动时加载；若配置格式非法，OAP 可能启动失败，请务必在改动后做语法校验。

自观测指标全景：面板、单位与口径

原文档将 Satellite 自观测建模为 OAP 中的一个Service，落在Layer: SO11Y_OAP（注：原文此处标注为 SO11Y_OAP，仓库中 satellite.yaml 的expSuffix实际归属为Layer.SO11Y_SATELLITE，Layer.java 中也定义了独立的SO11Y_SATELLITE(12, true)，故实际应以SO11Y_SATELLITE为准）。默认仪表盘共展示以下 7 项核心指标：

监控面板	单位	指标名	说明	数据来源
Connection Count	Count	`satellite_service_grpc_connect_count`	gRPC 连接数	SkyWalking Satellite
CPU (%)	Percentage	`satellite_service_server_cpu_utilization`	CPU 使用率（%）	SkyWalking Satellite
Queue Used Count	Count	`satellite_service_queue_used_count`	管道队列已使用数量	SkyWalking Satellite
Receive Event Count	Count	`satellite_service_receive_event_count`	从下游接收的事件数	SkyWalking Satellite
Fetch Event Count	Count	`satellite_service_fetch_event_count`	从下游抓取的事件数	SkyWalking Satellite
Queue Input Count	Count	`satellite_service_queue_input_count`	推入队列的事件数	SkyWalking Satellite
Queue Output Count	Count	`satellite_service_send_event_count`	推送到上游的事件数	SkyWalking Satellite

指标背后的 MAL 表达式

上述 7 个面板指标并非凭空而来，而是由 satellite.yaml 中metricsRules逐条定义。原始指标名以sw_stl_开头，来自 Satellite 暴露的底层计数/度量，MAL 负责做标签聚合与语义转换：

metricsRules: - name: service_receive_event_count exp: sw_stl_gatherer_receive_count.sum(["pipe", "status", "service"]).increase("PT1M") - name: service_fetch_event_count exp: sw_stl_gatherer_fetch_count.sum(["pipe", "status", "service"]).increase("PT1M") - name: service_queue_input_count exp: sw_stl_queue_output_count.sum(["pipe", "status", "service"]).increase("PT1M") - name: service_send_event_count exp: sw_stl_sender_output_count.sum(["pipe", "status", "service"]).increase("PT1M") - name: service_queue_total_capacity exp: sw_stl_pipeline_queue_total_capacity.sum(["pipeline", "service"]) - name: service_queue_used_count exp: sw_stl_pipeline_queue_partition_size.sum(["pipeline", "service"]) - name: service_server_cpu_utilization exp: sw_stl_grpc_server_cpu_gauge - name: service_grpc_connect_count exp: sw_stl_grpc_server_connection_count

对口径的理解要点：

事件吞吐类（receive / fetch / queue input / send）使用.sum(["pipe", "status", "service"])先按管道、状态、服务维度求和，再通过.increase("PT1M")计算每分钟增量，因此面板展示的是事件速率而非累计值；
队列水位类（queue_total_capacity与queue_used_count）按["pipeline", "service"]聚合求和，反映当前队列的占用情况，可直接用于评估背压与容量规划；
CPU 与连接数为 gRPC 服务端的即时度量（gauge），直接透传展示。

值得注意的是，MAL 规则中已定义了service_queue_total_capacity（队列总容量）指标，虽然默认仪表盘未直接展示，但你可以将其与service_queue_used_count配合，在定制面板中计算出队列使用率。

仪表盘定制：so11y-root.json 结构与扩展方法

原文档指出，Satellite 自观测仪表盘面板配置位于/config/ui-initialized-templates/so11y_satellite/so11y-root.json，仓库中的实际路径为 so11y-root.json。该文件是 OAP 启动时自动加载到 UI 的官方仪表盘模板之一，整体结构如下：

[ { "id": "Self-Observability-Satellite-Root", "configuration": { "children": [ ... ], "id": "Self-Observability-Satellite-Root", "layer": "SO11Y_SATELLITE", "entity": "Service", "name": "Self-Observability-Satellite-Root", "isRoot": true } } ]

关键字段说明：

layer：SO11Y_SATELLITE，声明该仪表盘属于 Satellite 自观测层；
entity：Service，仪表盘以服务为实体粒度展示指标（对应satellite-service）；
isRoot：true，表示这是该 Layer 的根仪表盘，即进入该层时的默认入口；
children：面板的子组件列表，包含Widget（图表）与Text（说明文本）两类。

以首个图表 Widget 为例，它通过expressions数组直接引用 MAL 生成的指标名：

{ "x": 8, "y": 2, "w": 8, "h": 14, "i": "1", "type": "Widget", "widget": { "title": "Connection Count" }, "graph": { "type": "Line", "step": false, "smooth": false, "showSymbol": false, "showXAxis": true, "showYAxis": true }, "expressions": ["satellite_service_grpc_connect_count"] }

7 个指标 Widget 的布局（x/y/w/h）与表达式对应关系如下：

Widget	标题	表达式
CPU (%)	`satellite_service_server_cpu_utilization`	(0,2) 8x14
Connection Count	`satellite_service_grpc_connect_count`	(8,2) 8x14
Queue Used Count	`satellite_service_queue_used_count`	(16,2) 8x14
Receive Event Count	`satellite_service_receive_event_count`	(0,16) 12x14
Fetch Event Count	`satellite_service_fetch_event_count`	(12,16) 12x14
Queue Input Count	`satellite_service_queue_input_count`	(0,30) 12x15
Queue Output Count	`satellite_service_send_event_count`	(12,30) 12x15

另有 id 为8的Text组件作为面板顶部说明，描述 Satellite 是“面向云原生基础设施的开源 Agent，是遥测采集的推荐负载均衡器”（见 backend-load-balancer.md）。

定制方式

根据原文档，你可以自定义自己的指标、表达式与仪表盘面板。实操上有两条路径：

修改官方模板：直接编辑so11y-root.json（或在 UI 的 Dashboard 编辑模式中调整），但注意发行版默认禁用了仪表盘编辑，需要设置环境变量SW_ENABLE_UPDATE_UI_TEMPLATE=true才能激活编辑并保存到 OAP；
新增自定义仪表盘：仿照模板结构新建 JSON 文件放入ui-initialized-templates目录，或通过 UI 的Dashboards菜单新建。自定义 Widget 时可引用任何已由 MAL 生成的satellite_*指标，也可先在satellite.yaml中扩展metricsRules定义新表达式。

无论哪种方式，都建议遵循 ui/README.md 中关于 Layer、Entity Type 与根仪表盘的约定：只有Service/All实体类型的仪表盘可设为根，同一 Layer 若存在多个根仪表盘，UI 会随机选择其一，因此不推荐设置多个根。

验证与调试：用 e2e 用例和 swctl 实测

仓库的 e2e 测试为我们提供了验证 Satellite 自观测指标是否正常上报的标准姿势（见 satellite-cases.yaml）：

# 1. 校验 SO11Y_SATELLITE 层下存在服务列表 swctl --display yaml --base-url=http://${oap_host}:${oap_12800}/graphql service layer SO11Y_SATELLITE # 2. 校验 CPU 指标有值 swctl --display yaml --base-url=http://${oap_host}:${oap_12800}/graphql metrics exec \ --expression=satellite_service_server_cpu_utilization --service-name=satellite-service # 3. 校验 gRPC 连接数指标有值 swctl --display yaml --base-url=http://${oap_host}:${oap_12800}/graphql metrics exec \ --expression=satellite_service_grpc_connect_count --service-name=satellite-service

预期的服务注册结果（satellite-service.yml）表明：当 Satellite 指标成功上报后，OAP 中会出现一个名为satellite-service、layers为[SO11Y_SATELLITE]的普通服务实体。也就是说，只要在 UI 的Self Observability → Satellite菜单下能看到satellite-service及其图表数据，即说明整条链路（Satellite → OTLP → receiver-otel → MAL → 存储 → 仪表盘）已打通。

常见的排障方向：

若service layer SO11Y_SATELLITE查询不到服务，优先检查 Satellite 的 Telemetry Exporter 是否已连接 OAP 的 gRPC 端口、receiver-otel是否已激活；
若服务存在但指标无值，检查enabledOtelMetricsRules是否包含satellite规则、satellite.yaml中expSuffix是否与上报数据的service标签匹配；
修改 MAL 规则或仪表盘模板后，需重启 OAP（或按 OAP 的配置热加载机制重新加载），并确认模板 JSON 合法，否则可能导致 OAP 启动失败。

总结

SkyWalking 为 Satellite 提供了开箱即用的自观测能力：数据经 OTLP 进入 OAP，由 MAL 规则完成聚合计算，最终呈现在 so11y-root.json 定义的SO11Y_SATELLITE层仪表盘上。理解这 7 个核心指标的口径、掌握模板 JSON 的字段语义，并复用仓库中现成的 swctl 验证命令，你就能快速诊断 Satellite 的接入状态，并据此定制适合自身场景的监控面板。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考