一、概述

二、配置结构详解

1. 根级配置项

[{
  "group": "我的",
  "chart": "line",
  "title": "JVM缓冲区数量",
  "query_range": "jvm_buffer_count_buffers{namespace='manager-test'}",
  "unit": "",
  "config": { ... }
}]

各字段说明：

字段 类型 必填 默认值 说明
group 字符串 是 无 图表分组名称：用于在仪表盘中组织和分类图表。值设为”我的”表示此图表将归类在”我的”分组下，便于查找和管理相关图表。
chart 字符串 是 无 图表类型标识：指定使用的图表类型。值"line"表示这是一个折线图。系统支持多种图表类型，如"bar"（柱状图）、"pie"（饼图）、"area"（面积图）等。
title 字符串 是 无 图表标题：显示在图表上方的描述性标题。此处为”JVM缓冲区数量”，明确指示图表展示的内容。
query_range 字符串 是 无 数据查询语句：用于从监控系统（此处为Prometheus）获取数据的查询表达式。jvm_buffer_count_buffers{namespace='manager-test'} 表示查询命名空间为manager-test的所有JVM缓冲区数量指标。花括号{}内为标签过滤器，可添加多个条件，如{namespace='manager-test', instance='xxx'}。
unit 字符串 否 空字符串 数据单位：用于在图表坐标轴和图例中显示数据的度量单位。例如"次"、"%"、"MB"等。此处为空，表示该指标为纯数量，无特定单位。
config 对象 否 {} 图表详细配置：包含图表样式、提示框、描述等进阶设置的对象。

2. config 配置对象

"config": {
  "description": "监控JVM中各个缓冲区的数量。这个指标反映了JVM内部缓冲区的使用情况，可以帮助分析内存分配和性能问题。",
  "tooltip": {
    "formatter": "${namespace} > [缓冲区类型] ${id}"
  }
}

config对象字段说明：

字段 类型 必填 默认值 说明
description 字符串 否 空字符串 图表描述：提供图表的详细解释和业务含义。此处描述了JVM缓冲区数量指标的作用和价值，有助于用户理解图表目的。此描述通常在图表详情或帮助信息中显示。
tooltip 对象 否 null 提示框配置：定义当鼠标悬停在图表数据点上时显示的提示框内容和格式。

tooltip对象字段说明：

字段 类型 必填 默认值 说明
formatter 字符串 否 系统默认 提示框格式化字符串：使用模板语法定义提示框的显示内容。变量${xxx}会被替换为实际数据点的对应字段值。此处"${namespace} > [缓冲区类型] ${id}"会生成类似"manager-test > [缓冲区类型] direct"的提示信息。

配置示例与扩展

基础配置示例

{
  "group": "性能监控",
  "chart": "line",
  "title": "API请求QPS",
  "query_range": "http_requests_total{service='api-gateway'}",
  "unit": "次/秒",
  "config": {
    "description": "监控API网关的每秒请求数，反映系统负载情况。",
    "tooltip": {
      "formatter": "服务: ${service}\n实例: ${instance}\nQPS: ${value} 次/秒"
    }
  }
}

高级配置扩展

除了上述基础配置，您还可以添加更多配置项来增强图表功能：

{
  "group": "我的",
  "chart": "line",
  "title": "JVM缓冲区数量",
  "query_range": "jvm_buffer_count_buffers{namespace='manager-test'}",
  "unit": "个",
  "config": {
    "description": "监控JVM中各个缓冲区的数量。这个指标反映了JVM内部缓冲区的使用情况，可以帮助分析内存分配和性能问题。",
    "tooltip": {
      "formatter": "${namespace} > [缓冲区类型] ${id}\n当前值: ${value}个\n时间: ${time}"
    },
    "colors": ["#1890ff", "#52c41a", "#f5222d"],
    "yAxis": {
      "min": 0,
      "max": 1000,
      "label": "缓冲区数量(个)"
    },
    "xAxis": {
      "label": "时间",
      "timeFormat": "HH:mm"
    },
    "legend": {
      "position": "top",
      "visible": true
    },
    "animation": true,
    "threshold": {
      "warning": 500,
      "critical": 800
    }
  }
}

高级配置字段说明

字段 类型 说明
colors 数组 自定义图表颜色序列，用于区分不同数据系列
yAxis 对象 Y轴配置：可设置最小值、最大值、标签等
xAxis 对象 X轴配置：可设置标签、时间格式等
legend 对象 图例配置：控制位置、可见性等
animation 布尔值 是否启用图表动画效果
threshold 对象 阈值配置：定义警告和严重级别的数值阈值

使用建议

  1. 逐步配置：建议先从基础配置开始，逐步添加高级配置项
  2. 查询优化：确保query_range中的查询语句在Prometheus中有效，可使用Prometheus UI进行测试
  3. 模板变量：在tooltip.formatter中，可使用${fieldName}引用查询返回的所有标签和值字段
  4. 分组管理：合理使用group字段对相关图表进行逻辑分组
  5. 单位规范：为指标设置合适的unit，提高图表的可读性

故障排查

如果图表无法正常显示，请检查：

  1. 查询语法：确认query_range中的Prometheus查询语句正确无误
  2. 数据存在：确保查询的时间范围内有对应指标数据
  3. JSON格式：验证JSON配置格式正确，无语法错误
  4. 标签匹配：检查过滤器中的标签值与实际数据标签是否一致

通过灵活调整这些配置项，您可以创建出既符合业务需求又具有良好可视化效果的监控图表。

作者：叶奕珺  创建时间：2025-12-18 14:13
最后编辑：叶奕珺  更新时间：2025-12-19 10:11