3分钟上手！SkyWalking API数据一键导出JSON全攻略

你还在为APM数据导出格式混乱而头疼？还在手动解析API响应浪费时间？本文将带你通过3个简单步骤，轻松实现Apache SkyWalking（分布式追踪系统，Application Performance Monitoring System）监控数据的JSON格式化导出，无需复杂编程，普通运营人员也能快速上手。读完本文你将掌握：API端点查询、响应数据提取、JSON格式保存的完整流程，以及自定义导出字段的进阶技巧。

准备工作：确认环境与工具

在开始前，请确保你的SkyWalking环境已正常运行。如果你还未部署，可以参考官方Docker部署文档快速启动：docker/docker-compose.yml。本文使用的SkyWalking API基于v9.5.0版本的Metrics V3接口，相关协议定义详见docs/en/api/query-protocol.md。

核心工具

• curl：用于发送HTTP请求（系统自带或从https://curl.se/下载）
• jq：轻量级JSON处理器（可选，用于格式化输出，安装教程：https://stedolan.github.io/jq/download/）
• 文本编辑器：如VS Code，用于查看和编辑JSON文件

步骤1：定位API端点与获取权限

SkyWalking通过GraphQL协议提供数据查询能力，所有监控数据（如指标、拓扑、日志）均通过统一端点暴露。核心API端点为：

http://{oap-server-ip}:12800/graphql

其中{oap-server-ip}替换为你的SkyWalking后端服务IP（本地部署通常为127.0.0.1）。

获取服务元数据

首先查询目标服务的基本信息，确认服务ID和层级（Layer）。使用以下curl命令获取所有服务列表：

curl -X POST http://127.0.0.1:12800/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query { listServices(layer: \"GENERAL\") { id name } }"}'

响应示例（已格式化）：

{
  "data": {
    "listServices": [
      {
        "id": "service123",
        "name": "user-service"
      },
      {
        "id": "service456",
        "name": "order-service"
      }
    ]
  }
}

记录下目标服务的id（如service123），后续步骤将使用此ID查询具体指标。

步骤2：调用API获取原始数据

以查询服务可用性指标（service_sla）为例，使用execExpression接口执行MQE（Metrics Query Expression）查询。MQE允许通过类PromQL语法计算指标，详细语法参见docs/en/api/metrics-query-expression.md。

基础查询命令

执行以下命令获取过去24小时的服务可用性平均值：

curl -X POST http://127.0.0.1:12800/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query {
      execExpression(
        expression: \"avg(service_sla)\",
        entity: {serviceId: \"service123\", serviceLayer: \"GENERAL\"},
        duration: {start: \"2024-10-03\", end: \"2024-10-04\", step: DAY}
      ) {
        type
        results {
          values {
            doubleValue
          }
        }
      }
    }"
  }'

参数说明：

• expression：指标计算表达式（avg(service_sla)表示求平均值）
• entity：指定查询实体（服务ID和层级）
• duration：时间范围（start/end格式需与step匹配，DAY级别为yyyy-MM-dd）

原始响应解析

默认响应包含数据类型和结果数组，未格式化的原始输出如下：

{"data":{"execExpression":{"type":"SINGLE_VALUE","results":[{"values":[{"doubleValue":99.98}]}]}}}

其中doubleValue:99.98即为我们需要的服务可用性数值（99.98%）。

步骤3：格式化并保存JSON数据

SkyWalking API返回的JSON结构包含嵌套层级，我们需要提取关键数据并保存为简洁格式。以下是两种常用方法：

方法1：手动提取（无工具）

直接使用文本编辑器处理原始响应，保留results字段内容。以上述响应为例，提取后得到：

{
  "service_id": "service123",
  "metric_name": "service_sla",
  "value": 99.98,
  "unit": "%",
  "time_range": {
    "start": "2024-10-03",
    "end": "2024-10-04",
    "step": "DAY"
  }
}

保存为service_sla_20241004.json即可。

方法2：使用jq自动格式化（推荐）

通过jq工具可一键提取并美化JSON。安装jq后执行：

curl -X POST http://127.0.0.1:12800/graphql \
  -H "Content-Type: application/json" \
  -d '{...}' | jq '.data.execExpression.results[0].values[0]' > result.json

命令解释：

• jq '.data.execExpression.results[0].values[0]'：提取嵌套JSON中的数值部分
• > result.json：将结果保存到文件

执行后result.json内容为：

{
  "doubleValue": 99.98
}

进阶：自定义导出字段

对于需要包含更多上下文信息（如服务名称、时间戳）的场景，可以通过修改GraphQL查询语句扩展返回字段。例如，同时获取服务名称和指标值：

curl -X POST http://127.0.0.1:12800/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query {
      service: getService(serviceId: \"service123\") { name }
      metric: execExpression(
        expression: \"avg(service_sla)\",
        entity: {serviceId: \"service123\", serviceLayer: \"GENERAL\"},
        duration: {start: \"2024-10-03\", end: \"2024-10-04\", step: DAY}
      ) {
        results { values { doubleValue } }
      }
    }"
  }' | jq '.data | {service_name: .service.name, sla: .metric.results[0].values[0].doubleValue, timestamp: now}'

输出结果：

{
  "service_name": "user-service",
  "sla": 99.98,
  "timestamp": 1696406400
}

技巧：使用jq的now函数可添加当前时间戳，便于数据归档。

常见问题与解决方案

Q1：API响应格式异常或数据为空？

A：检查时间范围参数是否正确。SkyWalking对时间格式有严格要求，不同step对应的时间格式如下（详见docs/en/api/query-protocol.md#duration）：

step	start/end格式示例
DAY	2024-10-03
HOUR	2024-10-03 14
MINUTE	2024-10-03 1430

Q2：如何批量导出多个指标？

A：使用批量查询语法在一个请求中获取多个指标，例如同时查询服务可用性和响应时间：

query {
  sla: execExpression(expression: "avg(service_sla)", ...) { results { values { doubleValue } } }
  rt: execExpression(expression: "avg(service_response_time)", ...) { results { values { doubleValue } } }
}

Q3：能否自动定时导出数据？

A：可以通过Linux cron任务或Windows任务计划程序实现。例如创建Shell脚本export_sla.sh：

#!/bin/bash
curl -X POST http://127.0.0.1:12800/graphql ... | jq ... > /data/skywalking/$(date +%Y%m%d)_sla.json

添加每日执行计划：

crontab -e
# 添加：0 0 * * * /path/to/export_sla.sh

进阶功能：自定义导出配置

对于需要长期使用的导出需求，可以通过配置文件定义固定格式。SkyWalking提供日志导出插件，支持将数据发送到Kafka等目的地，相关实现代码见oap-server/exporter/src/main/java/org/apache/skywalking/oap/server/exporter/provider/kafka/log/KafkaLogExporter.java。

配置示例

修改日志导出格式为JSON（配置文件路径：dist-material/config-examples/alarm-settings.yml）：

exporter:
  selector: ${SW_EXPORTER:KAFKA}
  kafka:
    topic: skywalking-logs
    producer:
      bootstrapServers: localhost:9092
    formatter:
      type: JSON
      json:
        includeFields: service,instance,endpoint,content

注意：此功能需要在OAP服务器启动时启用对应插件，具体配置方法参见官方文档。

总结与下一步行动

通过本文介绍的方法，你已掌握SkyWalking数据导出到JSON的核心技能：从API端点查询到响应格式化，再到自定义字段提取。建议你立即动手实践以下任务：

1. 导出所在项目的服务响应时间指标
2. 使用jq工具生成包含服务名称、指标值、时间戳的JSON报告
3. 尝试配置定时导出任务，实现数据自动归档

如果你需要更复杂的导出场景（如对接BI工具），可以进一步研究SkyWalking的Metric Exporter插件，或参考test/e2e-v2/cases/exporter/中的集成测试用例获取更多示例。

最后，欢迎在SkyWalking社区分享你的使用经验，或在docs/en/FAQ/中查找更多常见问题解答。让数据导出变得简单高效，从此告别繁琐的手动处理！

点赞+收藏本文，下次导出数据直接照着做！有任何问题，欢迎在评论区留言讨论。