SkyWalking Status API 使用指南集群节点、告警运行时状态、TTL 配置与查询调试的只读管理接口【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalkingStatus 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默认11800UI 查询走 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 与一个查询服务组成Handler负责路由ClusterStatusQueryHandler/status/cluster/nodesAlarmStatusQueryHandler/status/alarm/rules、/status/alarm/{ruleId}、/status/alarm/{ruleId}/{entityName}TTLConfigQueryHandler/status/config/ttlDebuggingHTTPHandler/debugging/config/dump、/debugging/query/...在 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.ymlstatus段约在 L814-L818admin-server段约在 L741-L771。如需显式禁用status将环境变量SW_STATUS置空即可export SW_STATUS # disable export SW_STATUSdefault # default (enabled)由于status挂在admin-server上整个管理端口的开关也值得一并了解SW_ADMIN_SERVER置空可整体禁用其核心可调参数包括环境变量默认值含义SW_ADMIN_SERVERdefaultadmin-server 模块开关置空禁用SW_ADMIN_SERVER_HOST0.0.0.0管理 HTTP 主机绑定地址SW_ADMIN_SERVER_PORT17128管理 HTTP 端口SW_ADMIN_SERVER_REST_SSL_ENABLEDfalse管理端口 TLS 开关支持证书轮换热加载SW_ADMIN_SERVER_GRPC_PORT17129admin 内部 gRPC 总线端口runtime-rule、dsl-debugging 的节点间 RPC⚠️ 安全提示管理端口内置无任何认证任何能触达该端口的客户端都能调用上面列出的所有端点。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/portOAP 节点的通信地址用于 OAP 节点间互相通信即 gRPC 集群端口默认11800self布尔标志表示该节点是否为当前节点其余为远端节点。实现原理该端点由 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 additionalPeriodrunningEntities已产生指标数据、并被该告警规则实际评估的实体列表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 additionalPeriodsilenceCountdown静默期倒计时-1 表示静默倒计时未在运行recoveryObservationPeriod/recoveryObservationCountdown恢复观察期及其倒计时currentState当前状态机状态示例中的FIRING表示正在触发告警windowValues指标到来时的原始窗口数据index为窗口下标从 0 开始mqeMetricsSnapshot执行检查时生成的、当前以 MQE 格式表达的指标数据将按表达式参与计算lastAlarmTime最近一次触发告警的时间戳毫秒告警恢复后重置为 0lastAlarmMessage最近一次触发告警时的告警消息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。背景知识TTLTime 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. # metadata7 # Cover hot and warm data for BanyanDB. metrics.minute7 metrics.hour15 metrics.day15 # 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.normal3 records.trace10 records.zipkinTrace3 records.log3 records.browserErrorLog3 # Cold data, -1 represents no cold stage data. records.normal.cold-1 records.trace.cold30 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 形状的keyvalue行。该端点还有一个重要的生态作用Inspect API 将它作为 REST-URL 发现原语——客户端在会话启动时解析转储结果中的core.restHost/core.restPort或 sharing-server 的覆盖项从而得知公开 GraphQL / MQE 服务位于何处。这让你可以只记住管理端口就能动态发现整套查询入口。/debugging/query/...以开启调试追踪的方式运行指定的命名查询路径并在返回结果的同时附带捕获到的 DAO / 存储 Span。该系列端点非常适合诊断查询为什么慢或为什么返回异常数据。URI用途/debugging/query/mqe带追踪执行 MQE 表达式/debugging/query/trace/queryBasicTraces追踪摘要查询/debugging/query/trace/queryTrace追踪详情查询/debugging/query/zipkin/api/v2/tracesZipkin 兼容摘要查询/debugging/query/zipkin/api/v2/traceZipkin 兼容详情查询/debugging/query/topology/getGlobalTopology全局拓扑调试/debugging/query/topology/getServicesTopology按服务拓扑调试/debugging/query/topology/getServiceInstanceTopology按实例拓扑调试/debugging/query/topology/getEndpointDependencies端点依赖调试/debugging/query/topology/getProcessTopology进程拓扑调试/debugging/query/log/queryLogs日志查询调试查询参数与对应 GraphQL 输入保持一致可参阅oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol下的 schema 定义。实现要点来自 DebuggingHTTPHandler.java各端点直接复用查询层组件MetricsExpressionQueryMQE、TraceQuery追踪、ZipkinQueryHandlerZipkin 兼容、TopologyQuery拓扑、LogQuery日志并以...Query(..., true)的方式开启调试追踪收集响应通过 Jackson 的YAMLFactory序列化为YAML 文本返回结果中除查询数据外还包含DebuggingTracetraceId、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.javaIllegalArgumentException如非法查询参数返回 HTTP 400其余异常返回 HTTP 500响应体为异常消息文本便于脚本直接读取失败原因。典型排障场景小结结合上述端点可以串起几条实用的排障路径集群健康检查curl http://oap:17128/status/cluster/nodes核对节点数与self标记排查协调器异常导致的成员列表不完整。告警该响没响/乱响排查先查/status/alarm/rules确认规则已加载再查/status/alarm/rules/{ruleId}看runningEntities、expression、additionalPeriod是否符合预期最后用/status/alarm/{ruleId}/{entityName}逐窗口核对windowValues、silenceCountdown、currentState判断是数据未进来、静默期压制还是表达式窗口不足此时可关注additionalPeriod与 increase/rate 函数 的关系。查询慢/结果异常诊断用/debugging/config/dump确认生效配置与core.restHost/core.restPort再用对应/debugging/query/*端点携带调试追踪重放查询从返回的 YAML 中读取 DAO/存储 span 定位瓶颈。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考