Apache SkyWalking自定义指标仪表盘：JSON配置详解-优快云博客

Apache SkyWalking自定义指标仪表盘：JSON配置详解

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

1. 仪表盘配置基础架构

SkyWalking仪表盘系统采用分层架构设计，通过JSON/YAML配置文件实现前端可视化与后端指标数据的解耦。自定义仪表盘需遵循特定的JSON Schema规范，主要包含元数据定义、布局结构和指标查询三大部分。

mermaid

1.1 配置文件结构

标准仪表盘配置文件包含以下顶级字段：

字段名	类型	描述	必填
`name`	string	仪表盘唯一标识，用于URL路由	是
`title`	string	显示名称，支持i18n键值	是
`icon`	string	侧边栏图标，使用FontAwesome类名	否
`priority`	number	显示优先级，数值越小越靠前	否
`type`	string	类型标识，固定为`custom`	是
`components`	array	可视化组件数组	是
`requiredPermissions`	array	访问权限列表	否

2. 核心配置字段详解

2.1 组件定义规范

每个组件需指定基础布局信息和数据查询配置，典型组件结构如下：

{
  "id": "service_throughput",
  "type": "CHART",
  "title": "服务吞吐量",
  "width": 12,
  "height": 250,
  "background": false,
  "config": {
    "chartType": "LINE",
    "metrics": [
      {
        "name": "service_throughput",
        "aggregation": "SUM",
        "metricType": "METER",
        "unit": "tps",
        "decimal": 0,
        "label": "总吞吐量"
      }
    ],
    "period": {
      "timeUnit": "MINUTE",
      "value": 15,
      "step": 1
    },
    "query": {
      "expression": "service_throughput.tagEqual('service', '$service').rate('PT5M')"
    }
  }
}

2.1.1 布局参数

参数	取值范围	说明
`width`	1-24	网格宽度，基于24列布局
`height`	100-800	组件高度(px)
`background`	boolean	是否显示背景面板

2.1.2 图表类型配置

CHART类型组件支持多种可视化形式，通过chartType字段指定：

类型	适用场景	配置特性
`LINE`	趋势分析	支持多指标对比、面积填充
`BAR`	分类对比	支持堆叠模式、水平/垂直切换
`PIE`	占比分析	支持环形图、百分比显示
`METRIC`	核心指标	大字体显示、趋势指示
`HEATMAP`	热度分布	时间维度聚合、颜色梯度

2.2 指标查询表达式(MQE)

仪表盘数据查询基于SkyWalking的Metrics Query Expression(MQE)，支持复杂的指标计算逻辑。常用操作包括：

# 基础指标查询
query: "service_response_time_avg.tagEqual('service', '$service')"

# 带时间窗口的速率计算
query: "service_throughput.rate('PT5M').tagIn('service', ['order-service', 'user-service'])"

# 多维度聚合
query: "instance_jvm_memory_used.sum(by=['service']).downsampling(SUM)"

MQE核心操作符

操作符	功能	示例
`tagEqual`	标签精确匹配	`tagEqual('region', 'cn-north')`
`tagMatch`	标签正则匹配	`tagMatch('service', '.*-api')`
`rate`	计算增长率	`rate('PT10M')`
`sum(by=[])`	按标签聚合求和	`sum(by=['service'])`
`histogram_percentile`	百分位计算	`histogram_percentile(95)`

3. 高级配置功能

3.1 动态参数与模板变量

通过variables字段定义可交互参数，实现仪表盘复用。常见应用场景包括服务选择、时间范围控制等：

{
  "variables": [
    {
      "name": "service",
      "type": "SERVICE",
      "label": "服务名称",
      "defaultValue": "all",
      "multiple": false,
      "includeNames": ["order-.*", "payment-.*"]
    },
    {
      "name": "period",
      "type": "DATETIME",
      "label": "时间范围",
      "defaultValue": {
        "timeUnit": "HOUR",
        "value": 6
      }
    }
  ]
}

变量类型支持：

SERVICE: 服务列表选择
INSTANCE: 实例列表选择
ENDPOINT: 端点列表选择
DATETIME: 时间范围选择
CUSTOM: 自定义枚举值

3.2 条件渲染与权限控制

通过conditions字段实现组件的动态显示控制，结合权限系统实现数据隔离：

{
  "components": [
    {
      "id": "sensitive_metrics",
      "type": "CHART",
      "title": "敏感操作监控",
      "conditions": {
        "permissions": ["ADMIN", "SECURITY"],
        "expression": "variables.env == 'production'"
      }
    }
  ]
}

4. 完整配置示例

以下是微服务性能监控仪表盘的完整配置示例，包含服务吞吐量、响应时间、错误率等核心指标：

{
  "name": "microservice-performance",
  "title": "微服务性能监控",
  "icon": "fa-tachometer",
  "priority": 10,
  "type": "custom",
  "variables": [
    {
      "name": "service",
      "type": "SERVICE",
      "label": "服务",
      "defaultValue": "all"
    },
    {
      "name": "timeRange",
      "type": "DATETIME",
      "label": "时间范围",
      "defaultValue": {
        "timeUnit": "HOUR",
        "value": 12
      }
    }
  ],
  "components": [
    {
      "id": "throughput",
      "type": "CHART",
      "title": "服务吞吐量",
      "width": 12,
      "height": 250,
      "config": {
        "chartType": "LINE",
        "metrics": [
          {
            "name": "throughput",
            "exp": "service_throughput.tagEqual('service', '$service').rate('PT5M')",
            "unit": "tps",
            "label": "吞吐量",
            "color": "#4CAF50"
          }
        ],
        "period": {
          "variable": "timeRange"
        }
      }
    },
    {
      "id": "response-time",
      "type": "CHART",
      "title": "响应时间分布",
      "width": 12,
      "height": 250,
      "config": {
        "chartType": "BAR",
        "metrics": [
          {
            "name": "p50",
            "exp": "service_response_time_percentile.tagEqual('service', '$service').histogram_percentile(50)",
            "unit": "ms",
            "label": "P50"
          },
          {
            "name": "p95",
            "exp": "service_response_time_percentile.tagEqual('service', '$service').histogram_percentile(95)",
            "unit": "ms",
            "label": "P95"
          }
        ]
      }
    }
  ]
}

5. 最佳实践与常见问题

5.1 性能优化建议

指标聚合策略
- 高频查询使用预聚合指标(minute级别)
- 避免在前端进行大量数据点渲染(建议≤1000点)
布局设计原则
- 核心指标放置在首屏(1920×1080范围内)
- 相关指标组合成组件组，减少认知负担
- 使用一致的颜色编码(成功:绿色/警告:黄色/错误:红色)

5.2 常见错误排查

错误现象	可能原因	解决方案
图表无数据	MQE表达式错误	使用API测试工具验证表达式
加载缓慢	数据量过大	增加聚合粒度或缩短时间范围
变量不生效	参数引用错误	检查`$variable`格式是否正确
权限拒绝	权限配置不当	检查`requiredPermissions`字段