SkyWalking Status API 使用指南：集群节点、告警运行时状态、TTL 配置与查询调试的只读管理接口

SkyWalking Status API 使用指南：集群节点、告警运行时状态、TTL 配置与查询调试的只读管理接口

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

Status API 是 Apache SkyWalking OAP 提供的一组只读 HTTP 端点，用于在不重启、不触碰 GraphQL 的前提下，直接检查集群成员关系、告警规则运行态、生效的 TTL（数据过期）配置，以及单次查询的 DAO/存储调试追踪。它由status特性模块托管在 admin-server REST 主机（默认端口17128）上，与/ui-management/*、/inspect/*、/dsl-debugging/*、/runtime/rule/*共用同一管理端口；其中/status/config/ttl还额外绑定在公开 REST 主机（默认端口12800）上。读完本文，你将掌握每个端点的用途、请求方式、返回字段含义，以及对应的源码实现路径，可直接用于集群排障、告警调优与查询性能诊断。

Status API 总览：管理面只读诊断接口

在 SkyWalking 的后端架构中，OAP 对外暴露多类接口：Agent 上报走 gRPC（默认11800），UI 查询走 GraphQL（默认12800）。而 admin-server（默认17128）则是面向运维人员的 HTTP 管理面，承载各类管理/诊断路由。status特性模块负责把"只读诊断"类端点挂到该管理面：

• 集群成员列表（cluster membership）
• 告警运行时状态（alarm runtime state）
• 生效的配置 / TTL 设置（effective configuration / TTL settings）
• 按查询粒度的调试追踪（per-query debug traces）

从源码结构看，该模块位于 oap-server/server-admin/status/src/main/java/org/apache/skywalking/oap/server/admin/status/，由四个 Handler 与一个查询服务组成：

在 StatusModuleProvider.java 的start()方法中可以看到完整的注册逻辑：所有 Handler 通过adminRestRegister()（即AdminServerModule提供的HTTPHandlerRegister）挂到管理端口；唯独TTLConfigQueryHandler同时通过publicRestRegister()（即CoreModule的注册器）挂到公开 REST 端口，注释明确说明这是"从 10.x 保留的行为，供在发起/graphql之前通过 REST 发现 TTL 的生态工具使用"：

@Override public void start() throws ServiceNotProvidedException, ModuleStartException { registerHandlers(adminRestRegister()); // /status/config/ttl stays on the public port too — kept from 10.x // for ecosystem tools that discover TTL via REST before /graphql. publicRestRegister().addHandler( new TTLConfigQueryHandler(getManager()), Collections.singletonList(HttpMethod.GET) ); }

也就是说：除了/status/config/ttl双端口可达外，其余所有/status/*与/debugging/*端点都是 admin-only。

托管方式与启停控制

status模块把全部 Handler 注册在 admin-server REST 主机上（默认端口17128）。status与admin-server两个模块默认都是启用的，因此该接口面开箱即用。对应的配置段位于 oap-server/server-starter/src/main/resources/application.yml（status段约在 L814-L818，admin-server段约在 L741-L771）。

如需显式禁用status，将环境变量SW_STATUS置空即可：

export SW_STATUS= # disable export SW_STATUS=default # default (enabled)

由于status挂在admin-server上，整个管理端口的开关也值得一并了解（SW_ADMIN_SERVER置空可整体禁用），其核心可调参数包括：

⚠️ 安全提示：管理端口内置无任何认证，任何能触达该端口的客户端都能调用上面列出的所有端点。SkyWalking 官方在 admin-server 安全须知 中要求运维人员务必做到：通过 IP 白名单 + 认证反向代理（sidecar、网关、mTLS 终结）保护管理端口；将SW_ADMIN_SERVER_HOST绑定到私有地址（如127.0.0.1），绝不对公网暴露；并在前置代理上做访问审计。OAP 自身不记录逐请求的鉴权决策。

配置与敏感信息脱敏

status模块的配置在 application.yml 中形如：

status: selector: ${SW_STATUS:default} default: keywords4MaskingSecretsOfConfig: ${SW_DEBUGGING_QUERY_KEYWORDS_FOR_MASKING_SECRETS:user,password,trustStorePass,keyStorePass,token,accessKey,secretKey,authentication}

核心配置项keywords4MaskingSecretsOfConfig是一个逗号分隔的关键字列表，由/debugging/config/dump消费：凡是配置键（key）包含列表中任意子串的配置值，都会在转储结果中被脱敏（redact）。默认关键字覆盖了user、password、trustStorePass、keyStorePass、token、accessKey、secretKey、authentication等常见敏感字段。

在 StatusModuleConfig.java 中可以看到该配置项的默认值与注解说明（自 9.7.0 起引入）：

/** * Include the list of keywords to filter configurations including secrets. Separate keywords by a comma. * * @since 9.7.0 */ private String keywords4MaskingSecretsOfConfig = "user,password,trustStorePass,keyStorePass,token,accessKey,secretKey,authentication";

实际脱敏动作发生在 DebuggingHTTPHandler.java 的dumpConfigurations()方法中，它把该关键字列表传给ServerStatusService.dumpBootingConfigurations(...)完成转储与过滤。运维实践中，如果某个自定义配置项含密钥但未命中默认关键字（例如jdbcUrl携带了数据库口令），可以在 application.yml 的注释指引下把它追加进keywords4MaskingSecretsOfConfig。

集群节点状态：/status/cluster/nodes

用途：返回集群模块视角下的 OAP 集群对等节点列表，用于确认每个节点都已加入集群并正常回报心跳。

OAP 集群由一组协同工作的 OAP 服务器组成，以提供可扩展、可靠的服务。OAP 集群支持通过多种集群协调器（如 Nacos、ZooKeeper、Kubernetes、Consul、Etcd 等）管理成员关系与通信。本接口允许你从每个 OAP 节点的视角查询节点列表；如果集群协调器工作异常，节点列表可能不完整或不正确，因此在搭建集群时建议用本接口做一致性核验。

• HTTP GET 方法。

curl http://oap:17128/status/cluster/nodes

{ "nodes": [ { "host": "10.0.12.23", "port": 11800, "self": true }, { "host": "10.0.12.25", "port": 11800, "self": false }, { "host": "10.0.12.37", "port": 11800, "self": false } ] }

字段说明：

• nodes：集群中所有节点列表，列表大小应与你的集群配置完全一致；
• host/port：OAP 节点的通信地址，用于 OAP 节点间互相通信（即 gRPC 集群端口，默认11800）；
• self：布尔标志，表示该节点是否为当前节点，其余为远端节点。

实现原理：该端点由 ClusterStatusQueryHandler.java 提供。它通过CoreModule获取RemoteClientManager服务，遍历其getRemoteClient()列表，把每个RemoteClient的地址（host/port）与是否为本机（self）序列化为 JSON 返回。这解释了为什么它反映的是"本节点视角下看到的集群成员"——数据直接来源于 OAP 自身的远端客户端注册表，而该注册表正是由所选集群协调器维护的。

告警运行时状态

OAP 基于告警规则与指标数据，在内存中计算告警条件。如果 OAP 集群有多个实例，每个实例都会独立计算告警条件。你可以从任意一个 OAP 实例发起查询，获取所有实例的告警运行状态——这正是下面三个端点存在的意义：让告警运行内核（alerting running kernel）变得可见。

从实现上看，跨实例的聚合由 AlarmStatusQueryService.java 完成：对SelfRemoteClient（本节点）直接从AlarmStatusWatcherService读取；对集群中的其他节点则通过RemoteServiceGrpc的syncStatusRPC 同步拉取，每个实例的结果（或errorMsg）被封装进InstanceAlarmStatus，再汇总进ClusterAlarmStatus的oapInstances列表返回。对应的数据结构定义在 server-alarm-plugin 下（AlarmRuleList、AlarmRuleDetail、AlarmRunningContext、ClusterAlarmStatus、InstanceAlarmStatus）。

/status/alarm/rules

返回当前运行的告警规则列表（规则 ID 集合）。

• HTTP GET 方法。

{ "oapInstances": [ { "address": "127.0.0.1_11800", "status": { "ruleList": [ { "id": "service_percentile_rule" }, { "id": "service_resp_time_rule" } ] } }, { "address": "127.0.0.1_11801", "status": { "ruleList": [ { "id": "service_percentile_rule" }, { "id": "service_resp_time_rule" } ] } } ] }

/status/alarm/rules/{ruleId}

返回指定告警规则的详细运行信息。

• HTTP GET 方法。

{ "oapInstances": [ { "address": "127.0.0.1_11800", "status": { "ruleId": "service_resp_time_rule", "expression": "sum(service_resp_time > 1000) >= 1", "period": 10, "silencePeriod": 10, "recoveryObservationPeriod": 2, "additionalPeriod": 0, "includeEntityNames": [], "excludeEntityNames": [], "includeEntityNamesRegex": "", "excludeEntityNamesRegex": "", "runningEntities": [ { "scope": "SERVICE", "name": "mock_b_service", "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes" } ], "tags": [ { "key": "level", "value": "WARNING" } ], "hooks": [ "webhook.default", "wechat.default" ], "includeMetrics": [ "service_resp_time" ] } }, { "address": "127.0.0.1_11801", "status": { "ruleId": "service_resp_time_rule", "expression": "sum(service_resp_time > 1000) >= 1", "period": 10, "silencePeriod": 10, "recoveryObservationPeriod": 2, "additionalPeriod": 0, "includeEntityNames": [], "excludeEntityNames": [], "includeEntityNamesRegex": "", "excludeEntityNamesRegex": "", "runningEntities": [ { "scope": "SERVICE", "name": "mock_a_service", "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes." }, { "scope": "SERVICE", "name": "mock_c_service", "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes." } ], "tags": [ { "key": "level", "value": "WARNING" } ], "hooks": [ "webhook.default", "wechat.default" ], "includeMetrics": [ "service_resp_time" ] } } ] }

关键字段说明：

• additionalPeriod：当表达式包含 increase/rate 函数 时的附加周期。该附加周期用于扩大计算趋势值所需的窗口大小（即窗口 =period + additionalPeriod）；
• runningEntities：已产生指标数据、并被该告警规则实际评估的实体列表；
• formattedMessage：针对每个受影响运行实体，按规则的 message 模板渲染出的告警消息正文；
• includeMetrics：该规则实际依赖的指标名集合，便于核对规则是否消费了预期的指标。

这些字段与 AlarmRuleDetail.java 数据类一一对应。

/status/alarm/{ruleId}/{entityName}

返回指定告警规则针对指定实体的运行上下文（窗口数据、状态机、最近告警记录等）。

• HTTP GET 方法。

{ "oapInstances": [ { "address": "127.0.0.1_11800", "status": { "ruleId": "service_resp_time_rule", "expression": "sum(service_resp_time > 1000) >= 1", "endTime": "2025-11-19T15:20:00.000", "additionalPeriod": 0, "size": 10, "silencePeriod": 10, "recoveryObservationPeriod": 0, "silenceCountdown": 10, "recoveryObservationCountdown": 0, "currentState": "FIRING", "entityName": "mock_b_service", "windowValues": [ { "index": 0, "metrics": [] }, { "index": 1, "metrics": [] }, { "index": 2, "metrics": [] }, { "index": 3, "metrics": [] }, { "index": 4, "metrics": [] }, { "index": 5, "metrics": [] }, { "index": 6, "metrics": [] }, { "index": 7, "metrics": [] }, { "index": 8, "metrics": [ { "name": "service_resp_time", "timeBucket": 202511191519, "value": "6000" } ] }, { "index": 9, "metrics": [] } ], "mqeMetricsSnapshot": { "service_resp_time": "[{\"metric\":{\"labels\":[]},\"values\":[{\"id\":\"202511191511\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191512\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191513\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191514\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191515\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191516\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191517\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191518\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191519\",\"doubleValue\":6000.0,\"isEmptyValue\":false},{\"id\":\"202511191520\",\"doubleValue\":0.0,\"isEmptyValue\":true}]}]" }, "lastAlarmTime": 1763536823628, "lastAlarmMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes.", "lastAlarmMqeMetricsSnapshot": { "service_resp_time": "[{\"metric\":{\"labels\":[]},\"values\":[{\"id\":\"202511191511\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191512\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191513\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191514\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191515\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191516\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191517\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191518\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191519\",\"doubleValue\":6000.0,\"isEmptyValue\":false},{\"id\":\"202511191520\",\"doubleValue\":0.0,\"isEmptyValue\":true}]}]" } } }, { "address": "127.0.0.1_11801", "status": { "ruleId": "service_resp_time_rule", "expression": "sum(service_resp_time > 1000) >= 1", "additionalPeriod": 0, "size": 0, "silenceCountdown": 0, "recoveryObservationCountdown": 0, "windowValues": [], "lastAlarmTime": 0 } } ] }

字段含义（与 AlarmRunningContext.java 数据类一致）：

• size：滑动窗口大小，等于period + additionalPeriod；
• silenceCountdown：静默期倒计时，-1 表示静默倒计时未在运行；
• recoveryObservationPeriod/recoveryObservationCountdown：恢复观察期及其倒计时；
• currentState：当前状态机状态（示例中的FIRING表示正在触发告警）；
• windowValues：指标到来时的原始窗口数据，index为窗口下标（从 0 开始）；
• mqeMetricsSnapshot：执行检查时生成的、当前以 MQE 格式表达的指标数据，将按表达式参与计算；
• lastAlarmTime：最近一次触发告警的时间戳（毫秒），告警恢复后重置为 0；
• lastAlarmMessage：最近一次触发告警时的告警消息；
• lastAlarmMqeMetricsSnapshot：最近一次触发告警时 MQE 格式的指标数据快照。

上例清晰展示了告警判定过程：mock_b_service的service_resp_time在第 8 个窗口（timeBucket202511191519）出现 6000ms 的采样值，满足表达式sum(service_resp_time > 1000) >= 1，于是状态机进入FIRING、静默倒计时启动（silenceCountdown: 10）；另一实例127.0.0.1_11801上该实体尚无窗口数据（windowValues: []、lastAlarmTime: 0），说明不同实例的告警计算相互独立。

从 OAP 实例查询状态时出错的处理

当从部分 OAP 实例查询状态发生错误时，错误信息会随响应一并返回，而不会导致整个请求失败：

{ "oapInstances": [ { "address": "127.0.0.1_11800", "status": { "ruleList": [ { "id": "service_percentile_rule" }, { "id": "service_resp_time_rule" } ] } }, { "address": "127.0.0.1_11801", "errorMsg": "UNAVAILABLE: io exception" } ] }

这与 AlarmStatusQueryService.java 的实现相吻合：对每个远端节点调用syncStatus时捕获异常，把e.getMessage()写入InstanceAlarmStatus.setErrorMsg(...)，同时保留address，从而让运维人员一眼定位到"哪台节点失联或异常"。

生效 TTL 配置：/status/config/ttl

返回 OAP 启动时加载的生效 TTL 配置。该端点在两个端口均可访问——:17128（管理端口）与:12800（公开端口）——因此生态工具无需感知管理端口即可获取 TTL。其余所有/status/*Handler 均为 admin-only。

背景知识：TTL（Time To Live，数据存活时间）机制在不同存储实现下行为不同。默认情况下，core 模块提供两个 TTL 配置：recordDataTTL与metricsDataTTL。但某些存储实现可以覆盖这些设置并提供自己的 TTL 配置，例如 BanyanDB 提供原生 TTL 机制，支持渐进式 TTL 与数据生命周期阶段（Hot/Warm/Cold） 特性。本 API 的目的就是获取统一且生效的TTL 配置。

• HTTP GET 方法。

curl -X GET "http://oap:17128/status/config/ttl"

# Metrics TTL includes the definition of the TTL of the metrics-ish data in the storage, # e.g. # 1. The metadata of the service, instance, endpoint, topology map, etc. # 2. Generated metrics data from OAL and MAL engines. # 3. Banyandb storage provides Data Lifecycle Stages(Hot/Warm/Cold). # # TTLs for each granularity metrics are listed separately. # metadata=7 # Cover hot and warm data for BanyanDB. metrics.minute=7 metrics.hour=15 metrics.day=15 # Cold data, '-1' represents no cold stage data. metrics.minute.cold=-1 metrics.hour.cold=-1 metrics.day.cold=-1 # Records TTL includes the definition of the TTL of the records data in the storage, # Records include traces, logs, sampled slow SQL statements, HTTP requests(by Rover), alarms, etc. # Super dataset of records are traces and logs, which volume should be much larger. # # Cover hot and warm data for BanyanDB. records.normal=3 records.trace=10 records.zipkinTrace=3 records.log=3 records.browserErrorLog=3 # Cold data, '-1' represents no cold stage data. records.normal.cold=-1 records.trace.cold=30 records.zipkinTrace.cold=-1 records.log.cold=-1 records.browserErrorLog.cold=-1

该 API 同时支持 JSON 格式响应，更适合程序化消费：

curl -X GET "http://oap:17128/status/config/ttl" \ -H "Accept: application/json"

{ "metrics": { "minute": 7, "hour": 15, "day": 15, "coldMinute": -1, "coldHour": -1, "coldDay": -1 }, "records": { "normal": 3, "trace": 10, "zipkinTrace": 3, "log": 3, "browserErrorLog": 3, "coldNormal": -1, "coldTrace": 30, "coldZipkinTrace": -1, "coldLog": -1, "coldBrowserErrorLog": -1 } }

实现原理：由 TTLConfigQueryHandler.java 提供。Handler 通过CoreModule获取TTLStatusQuery服务并调用其getTTL()，返回TTLDefinition对象；方法同时标注了@ProducesText与@ProducesJson，因此服务端会根据请求的Accept头自动返回上面两种格式。TTLStatusQuery.getTTL()位于 oap-server/server-core，它会委托给当前存储插件暴露的 TTL 状态查询实现——这正解释了为什么返回的是"统一且生效"的配置（存储插件可覆盖默认值，如 BanyanDB 的冷热分层）。

配置转储与查询调试端点

/debugging/config/dump

转储 OAP 启动时应用的生效配置。凡是配置键包含keywords4MaskingSecretsOfConfig中任意子串的值都会被脱敏。输出为 YAML 形状的key=value行。

该端点还有一个重要的生态作用：Inspect API 将它作为 REST-URL 发现原语——客户端在会话启动时解析转储结果中的core.restHost/core.restPort（或 sharing-server 的覆盖项），从而得知公开 GraphQL / MQE 服务位于何处。这让你可以只记住管理端口，就能动态发现整套查询入口。

/debugging/query/...

以开启调试追踪的方式运行指定的命名查询路径，并在返回结果的同时附带捕获到的 DAO / 存储 Span。该系列端点非常适合诊断"查询为什么慢"或"为什么返回异常数据"。

查询参数与对应 GraphQL 输入保持一致（可参阅oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol下的 schema 定义）。

实现要点（来自 DebuggingHTTPHandler.java）：

• 各端点直接复用查询层组件：MetricsExpressionQuery（MQE）、TraceQuery（追踪）、ZipkinQueryHandler（Zipkin 兼容）、TopologyQuery（拓扑）、LogQuery（日志），并以...Query(..., true)的方式开启调试追踪收集；
• 响应通过 Jackson 的YAMLFactory序列化为YAML 文本返回，结果中除查询数据外还包含DebuggingTrace（traceId、condition、起止时间、耗时及带父子关系的 span 树）；
• 多个端点支持coldStage参数（如/debugging/query/trace/queryTrace、/debugging/query/zipkin/...、各 topology 端点、/debugging/query/mqe），注释明确"只有 BanyanDB 能查询冷阶段（cold stage）的数据"，用于配合前面介绍的渐进式 TTL / 数据生命周期阶段排查冷数据查询问题；
• /debugging/query/log/queryLogs在未提供traceId时要求必须传startTime、endTime、step，否则返回"startTime, endTime and step are required"。

错误处理约定：所有 Status/调试端点统一挂载 StatusQueryExceptionHandler.java：IllegalArgumentException（如非法查询参数）返回 HTTP 400，其余异常返回 HTTP 500，响应体为异常消息文本，便于脚本直接读取失败原因。

典型排障场景小结

结合上述端点，可以串起几条实用的排障路径：

1. 集群健康检查：curl http://oap:17128/status/cluster/nodes核对节点数与self标记，排查协调器异常导致的成员列表不完整。
2. 告警"该响没响/乱响"排查：先查/status/alarm/rules确认规则已加载，再查/status/alarm/rules/{ruleId}看runningEntities、expression、additionalPeriod是否符合预期，最后用/status/alarm/{ruleId}/{entityName}逐窗口核对windowValues、silenceCountdown、currentState，判断是数据未进来、静默期压制还是表达式窗口不足（此时可关注additionalPeriod与 increase/rate 函数 的关系）。
3. 查询慢/结果异常诊断：用/debugging/config/dump确认生效配置与core.restHost/core.restPort，再用对应/debugging/query/*端点携带调试追踪重放查询，从返回的 YAML 中读取 DAO/存储 span 定位瓶颈。
4. TTL 生效值确认：curl -X GET "http://oap:17128/status/config/ttl" -H "Accept: application/json"验证存储层实际生效的各类 TTL（含 BanyanDB 冷阶段值-1表示无冷数据阶段），避免出现"配置了但没生效"的误判。

以上所有端点均为只读 GET 接口，不会修改任何运行时状态，可以放心接入巡检脚本、告警自检与故障复盘流程。

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