仪表盘

Uptrace 允许您使用类似 Prometheus 的查询语言，从 Spans、Events、Logs 和 Metrics 构建自定义仪表盘。仪表盘是可视化监控数据的重要工具，帮助您快速了解系统和应用的运行状态。

概述

仪表盘的主要作用：

• 数据可视化：将指标、追踪和日志数据以图表形式展示
• 实时监控：实时查看系统和应用的性能指标
• 问题定位：通过可视化快速定位性能问题和异常
• 团队协作：与团队成员共享监控视图，统一监控视角

创建方式

Uptrace 支持两种方式创建仪表盘：

• UI 方式：通过图形界面创建和编辑仪表盘
• YAML 方式：通过 YAML 配置文件定义仪表盘

两种方式各有优缺点，但都能实现相同的效果。建议根据团队习惯和需求选择合适的方式。

访问仪表盘

创建和访问仪表盘的步骤：

1. 登录 Uptrace 平台：https://uptrace.inner.youdao.com/
2. 选择项目
3. 导航到 "Metrics" → "Dashboards"
4. 点击 "New dashboard" 创建新仪表盘

仪表盘类型

Uptrace 使用两种类型的仪表盘来可视化数据：

1. 表格仪表盘（Table Dashboards）：经典的数据表格，每行可以链接到网格仪表盘
2. 网格仪表盘（Grid Dashboards）：经典的图表网格布局，类似 Grafana

两种类型可以配合使用，也可以单独使用。

表格仪表盘（Table Dashboards）

表格仪表盘是一个数据表格，其中每行可以链接到同一个网格仪表盘，但会根据表格行的 group by 属性进行过滤。例如，一个主机名表格，每行链接到按 host_name = ${host_value} 过滤的网格仪表盘。

换句话说，表格仪表盘允许您使用表格中的属性来参数化网格仪表盘。您可以将表格用作 Grafana 变量的替代品。

推荐使用方式

建议从表格仪表盘开始，然后添加网格仪表盘。表格仪表盘应该包含：

• 几个 group by 属性（如 host_name、service_name）
• 3-5 个最重要的指标

如果您不需要表格仪表盘，可以将其留空。网格仪表盘可以独立使用，不需要表格仪表盘。

表格仪表盘示例

创建一个包含多个指标的表格：

table:
  # 指标列表及其别名
  metrics:
    - system_cpu_utilization as $cpu_util
    - system_cpu_load_average_1m as $load_avg_1m
    - system_memory_utilization as $mem_util
    - system_memory_usage as $mem_usage

  # 包含多个表达式的查询
  # 时间序列通过 `host_name` 自动关联
  query:
    - group by host_name
    - avg($cpu_util) as cpu_util
    - avg($load_avg_1m)
    - avg($mem_util) as mem_util
    - sum($mem_usage{state="used"}) as mem_used

  # 列用于自定义表格格式
  columns:
    cpu_util: { unit: utilization }
    mem_util: { unit: utilization }

配置说明：

• metrics：定义要查询的指标，使用别名便于后续引用
• query：查询表达式
  • group by host_name：按主机名分组，每台主机一行
  • avg($cpu_util)：计算平均 CPU 使用率
  • sum($mem_usage{state="used"})：计算已使用内存总和
• columns：自定义列的显示格式
  • unit: utilization：指定单位为利用率（0-1 范围）

表格仪表盘的优势

• 参数化网格仪表盘：表格行可以链接到按行属性过滤的网格仪表盘
• 多指标对比：在一个表格中显示多个指标，便于对比
• 自动关联：相同属性的时间序列会自动关联
• 灵活过滤：可以轻松过滤和排序数据

网格仪表盘（Grid Dashboards）

网格仪表盘是经典的图表网格布局，类似 Grafana。网格元素可以组织在可折叠的行中。

网格仪表盘示例

创建一个包含多个图表的网格仪表盘：

grid_rows:
  - title: General
    items:
      - title: CPU utilization
        metrics:
          - system_cpu_utilization as $cpu_util
        query:
          - avg($cpu_util)

      - title: CPU time
        metrics:
          - system_cpu_time as $cpu_time
        query:
          - perMin(sum($cpu_time)) as cpu_time group by state
        chart: stacked-area

配置说明：

• grid_rows：定义网格行，每行可以包含多个图表项
• title：行标题，可以折叠/展开
• items：图表项列表
  • title：图表标题
  • metrics：要查询的指标
  • query：查询表达式
  • chart：图表类型（可选，默认为折线图）

图表类型

网格仪表盘支持多种图表类型：

• 折线图（line）：默认类型，显示指标随时间的变化趋势
• 堆叠面积图（stacked-area）：显示多个系列的堆叠面积
• 柱状图（bar）：对比不同维度的指标值
• 饼图（pie）：显示指标分布比例
• 热力图（heatmap）：显示指标的热度分布

网格仪表盘的优势

• 灵活布局：可以自由组织图表位置
• 可折叠行：使用可折叠行组织相关图表
• 多种图表类型：支持多种图表类型，满足不同可视化需求
• 时间同步：所有图表使用相同的时间范围

查询语言

Uptrace 使用类似 PromQL 的查询语言来查询指标。查询语言支持以下功能：

基本语法

指标别名

使用 as 关键字为指标创建别名：

metrics:
  - system_cpu_utilization as $cpu_util
  - system_memory_usage as $mem_usage

数学运算

支持基本的数学运算：

query:
  - $cpu_util * 100 as cpu_percent
  - $mem_used / $mem_total as mem_util

聚合函数

支持多种聚合函数：

• avg()：平均值
• sum()：总和
• min()：最小值
• max()：最大值
• count()：计数
• p50(), p95(), p99()：百分位数
• uniq()：唯一值计数

示例：

query:
  - avg($cpu_util) as avg_cpu
  - max($cpu_util) as max_cpu
  - p95($duration) as p95_latency
  - count($requests) as request_count

过滤条件

使用 where 子句添加过滤条件：

query:
  - avg($cpu_util)
  - where host_name = "web-server-01"
  - where deployment_environment = "production"

支持的操作符：

• =：等于
• !=：不等于
• >、>=、<、<=：比较运算符
• in：包含在列表中
• !~：不匹配正则表达式
• contains：包含字符串

分组

使用 group by 子句按属性分组：

query:
  - avg($cpu_util)
  - group by host_name
  - group by host_name, deployment_environment

时间函数

支持时间聚合函数：

• perMin()：每分钟
• perHour()：每小时
• perDay()：每天

示例：

query:
  - perMin(sum($requests)) as requests_per_minute
  - perHour(avg($cpu_util)) as hourly_cpu_avg

查询示例

计算错误率

metrics:
  - uptrace_tracing_spans as $spans

query:
  - sum($spans{_status_code="error"}) / sum($spans) * 100 as error_rate
  - where _type = "httpserver"
  - group by service_name

计算 P95 延迟

metrics:
  - uptrace_tracing_spans as $spans

query:
  - p95($spans) as p95_latency
  - where _type = "httpserver"
  - where service_name = "api-service"
  - group by span_name

计算请求量

metrics:
  - uptrace_tracing_spans as $spans

query:
  - perMin(count($spans)) as requests_per_minute
  - where _type = "httpserver"
  - group by service_name, deployment_environment

仪表盘模板

Uptrace 提供了预构建的 YAML 仪表盘模板，用于流行的 OpenTelemetry 工具。例如：

• 主机指标（Host Metrics）
• PostgreSQL
• MySQL
• Redis
• 以及更多

模板自动创建

当 Uptrace 接收到新指标时，它会检查可用的仪表盘模板，如果存在匹配的指标，会自动创建仪表盘。

模板位置

您可以在 GitHub 上找到所有可用的仪表盘模板： https://github.com/uptrace/uptrace/tree/master/config/dashboard-templates

模板导入和导出

您可以使用 Uptrace UI 导入和导出仪表盘模板：

1. 导出模板：

   • 打开仪表盘
   • 点击 "Export" 按钮
   • 复制 YAML 配置

2. 导入模板：

   • 创建新仪表盘
   • 选择 "From YAML"
   • 粘贴 YAML 配置

模板贡献

要与他人分享您的仪表盘，可以在 GitHub 上提交 PR，包含 YAML 定义。

模板示例

仪表盘模板可以包含表格、网格和指标监控器：

# 表格仪表盘
table:
  metrics:
    - system_cpu_utilization as $cpu_util
  query:
    - group by host_name
    - avg($cpu_util) as cpu_util
  columns:
    cpu_util: { unit: utilization }

# 网格仪表盘
grid_rows:
  - title: CPU
    items:
      - title: CPU utilization
        metrics:
          - system_cpu_utilization as $cpu_util
        query:
          - avg($cpu_util)
          - group by host_name

# 指标监控器
monitors:
  - name: CPU usage
    metrics:
      - system_cpu_load_average_15m as $load_avg_15m
      - system_cpu_time as $cpu_time
    query:
      - avg($load_avg_15m) / uniq($cpu_time, cpu) as cpu_util
      - group by host_name
    column: cpu_util
    column_unit: utilization
    max_allowed_value: 3
    check_num_point: 10

系统指标

Uptrace 提供了一些特殊的指标，使用 uptrace_ 前缀来访问系统数据，如 Spans、Logs、服务图和计费信息。

可用的系统指标

以下指标应该可用：

追踪指标

• uptrace_tracing_spans：Span 数量和持续时间（不包括 events 和 logs）
• uptrace_tracing_events：事件数量（不包括 spans 和 logs）
• uptrace_tracing_logs：日志数量（不包括 spans 和 events）

使用示例：

metrics:
  - uptrace_tracing_spans as $spans

query:
  - perMin(count($spans)) as spans_per_minute
  - group by service_name

服务图指标

• uptrace_service_graph_client_duration：从客户端视角看到的两个节点之间的请求持续时间
• uptrace_service_graph_server_duration：从服务器视角看到的两个节点之间的请求持续时间
• uptrace_service_graph_failed_requests：两个节点之间失败请求的总数

使用示例：

metrics:
  - uptrace_service_graph_client_duration as $client_duration

query:
  - p95($client_duration) as p95_client_latency
  - group by service_name, deployment_environment

计费指标

• uptrace_billing_sampled_bytes：每个项目的采样字节数
• uptrace_billing_sampled_spans：每个项目的采样 Span/Log 数
• uptrace_billing_dropped_spans：每个项目丢弃的 Span/Log 数
• uptrace_billing_timeseries：每个项目的时间序列数

使用示例：

metrics:
  - uptrace_billing_sampled_spans as $sampled_spans

query:
  - sum($sampled_spans) as total_sampled_spans
  - group by project_id

系统指标的使用场景

监控追踪数据量

监控每个服务的 Span 数量：

metrics:
  - uptrace_tracing_spans as $spans

query:
  - perMin(count($spans)) as spans_per_minute
  - group by service_name
  - where deployment_environment = "production"

监控错误率

监控每个服务的错误率：

metrics:
  - uptrace_tracing_spans as $spans

query:
  - count($spans{_status_code="error"}) / count($spans) * 100 as error_rate
  - group by service_name

监控服务图性能

监控服务间的调用延迟：

metrics:
  - uptrace_service_graph_client_duration as $client_duration

query:
  - p95($client_duration) as p95_latency
  - group by service_name, target_service_name

实战示例

示例 1：系统监控仪表盘

创建一个完整的系统监控仪表盘，监控 CPU、内存、磁盘和网络：

table:
  metrics:
    - system_cpu_utilization as $cpu_util
    - system_memory_utilization as $mem_util
    - system_filesystem_usage as $fs_usage
    - system_network_errors as $net_errors

  query:
    - group by host_name
    - avg($cpu_util) as cpu_util
    - avg($mem_util) as mem_util
    - avg($fs_usage{state="used"} / $fs_usage) as fs_util
    - sum($net_errors) as net_errors

  columns:
    cpu_util: { unit: utilization }
    mem_util: { unit: utilization }
    fs_util: { unit: utilization }

grid_rows:
  - title: CPU
    items:
      - title: CPU Utilization
        metrics:
          - system_cpu_utilization as $cpu_util
        query:
          - avg($cpu_util)
          - group by host_name

      - title: CPU Load Average
        metrics:
          - system_cpu_load_average_1m as $load_1m
          - system_cpu_load_average_5m as $load_5m
          - system_cpu_load_average_15m as $load_15m
        query:
          - avg($load_1m) as load_1m
          - avg($load_5m) as load_5m
          - avg($load_15m) as load_15m
          - group by host_name

  - title: Memory
    items:
      - title: Memory Utilization
        metrics:
          - system_memory_utilization as $mem_util
        query:
          - avg($mem_util)
          - group by host_name

      - title: Memory Usage
        metrics:
          - system_memory_usage as $mem_usage
        query:
          - sum($mem_usage{state="used"}) as mem_used
          - sum($mem_usage{state="free"}) as mem_free
          - group by host_name
        chart: stacked-area

  - title: Disk
    items:
      - title: Filesystem Usage
        metrics:
          - system_filesystem_usage as $fs_usage
        query:
          - avg($fs_usage{state="used"} / $fs_usage) as fs_util
          - group by host_name, mountpoint
          - where mountpoint !~ "/snap"

      - title: Disk I/O
        metrics:
          - system_disk_io_time as $disk_io
        query:
          - perMin(sum($disk_io)) as disk_io_per_min
          - group by host_name, device

  - title: Network
    items:
      - title: Network Errors
        metrics:
          - system_network_errors as $net_errors
        query:
          - sum($net_errors)
          - group by host_name

      - title: Network I/O
        metrics:
          - system_network_io as $net_io
        query:
          - perMin(sum($net_io)) as net_io_per_min
          - group by host_name

示例 2：应用性能仪表盘

创建一个应用性能监控仪表盘：

table:
  metrics:
    - uptrace_tracing_spans as $spans

  query:
    - group by service_name
    - perMin(count($spans)) as requests_per_min
    - count($spans{_status_code="error"}) / count($spans) * 100 as error_rate
    - p95($spans) as p95_latency
    - where _type = "httpserver"

  columns:
    error_rate: { unit: utilization }

grid_rows:
  - title: Request Metrics
    items:
      - title: Requests per Minute
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - perMin(count($spans)) as requests_per_min
          - where _type = "httpserver"
          - group by service_name

      - title: Error Rate
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - count($spans{_status_code="error"}) / count($spans) * 100 as error_rate
          - where _type = "httpserver"
          - group by service_name

  - title: Latency
    items:
      - title: P50 Latency
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - p50($spans) as p50_latency
          - where _type = "httpserver"
          - group by service_name

      - title: P95 Latency
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - p95($spans) as p95_latency
          - where _type = "httpserver"
          - group by service_name

      - title: P99 Latency
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - p99($spans) as p99_latency
          - where _type = "httpserver"
          - group by service_name

  - title: Database
    items:
      - title: Database Query Duration
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - p95($spans) as p95_duration
          - where _type = "db"
          - group by db_system, db_operation

      - title: Database Errors
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - perMin(count($spans{_status_code="error"})) as errors_per_min
          - where _type = "db"
          - group by db_system

示例 3：服务拓扑仪表盘

创建一个服务拓扑监控仪表盘：

grid_rows:
  - title: Service Graph
    items:
      - title: Client Duration (P95)
        metrics:
          - uptrace_service_graph_client_duration as $client_duration
        query:
          - p95($client_duration) as p95_latency
          - group by service_name, target_service_name

      - title: Server Duration (P95)
        metrics:
          - uptrace_service_graph_server_duration as $server_duration
        query:
          - p95($server_duration) as p95_latency
          - group by service_name, target_service_name

      - title: Failed Requests
        metrics:
          - uptrace_service_graph_failed_requests as $failed_requests
        query:
          - perMin(sum($failed_requests)) as failed_per_min
          - group by service_name, target_service_name

  - title: Service Metrics
    items:
      - title: Requests per Service
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - perMin(count($spans)) as requests_per_min
          - where _type = "httpserver"
          - group by service_name

      - title: Error Rate per Service
        metrics:
          - uptrace_tracing_spans as $spans
        query:
          - count($spans{_status_code="error"}) / count($spans) * 100 as error_rate
          - where _type = "httpserver"
          - group by service_name

示例 4：业务指标仪表盘

创建一个业务指标监控仪表盘：

table:
  metrics:
    - custom_business_orders as $orders
    - custom_business_payments as $payments

  query:
    - group by service_name, deployment_environment
    - perMin(sum($orders)) as orders_per_min
    - perMin(sum($payments)) as payments_per_min
    - sum($payments) / sum($orders) * 100 as conversion_rate

  columns:
    conversion_rate: { unit: utilization }

grid_rows:
  - title: Business Metrics
    items:
      - title: Orders per Minute
        metrics:
          - custom_business_orders as $orders
        query:
          - perMin(sum($orders)) as orders_per_min
          - group by service_name

      - title: Payments per Minute
        metrics:
          - custom_business_payments as $payments
        query:
          - perMin(sum($payments)) as payments_per_min
          - group by service_name

      - title: Conversion Rate
        metrics:
          - custom_business_orders as $orders
          - custom_business_payments as $payments
        query:
          - sum($payments) / sum($orders) * 100 as conversion_rate
          - group by service_name

最佳实践

仪表盘设计原则

1. 明确目标：每个仪表盘应该有明确的监控目标
2. 合理组织：使用可折叠行组织相关图表
3. 避免过度：不要在一个仪表盘中放置过多图表
4. 突出重点：将最重要的指标放在显眼位置

性能优化建议

1. 合理使用时间范围：避免查询过大的时间范围
2. 使用过滤条件：使用 where 子句缩小查询范围
3. 合理分组：避免过多的 group by 属性
4. 使用采样：对于高频指标，考虑使用采样

共享和协作

1. 命名规范：使用统一的命名规范
2. 添加描述：为仪表盘添加描述，说明用途
3. 定期审查：定期审查仪表盘，删除不再需要的
4. 文档化：为复杂仪表盘编写文档

模板使用建议

1. 从模板开始：使用预置模板作为起点
2. 自定义调整：根据需求调整模板
3. 贡献模板：将有用的仪表盘贡献为模板
4. 保持更新：定期更新模板以匹配最新功能

常见问题

1. 如何创建新的仪表盘？

创建步骤：

1. 登录 Uptrace 平台
2. 导航到 "Metrics" → "Dashboards"
3. 点击 "New dashboard"
4. 选择创建方式（UI 或 YAML）
5. 配置仪表盘
6. 保存

2. 如何编辑现有仪表盘？

编辑步骤：

1. 打开仪表盘
2. 点击 "Edit" 按钮
3. 修改配置
4. 保存

3. 如何删除仪表盘？

删除步骤：

1. 打开仪表盘
2. 点击 "Delete" 按钮
3. 确认删除

4. 如何共享仪表盘？

共享方法：

1. 导出仪表盘 YAML
2. 将 YAML 分享给团队成员
3. 团队成员导入 YAML 创建自己的仪表盘副本

5. 如何为不同环境创建不同的仪表盘？

方法：

1. 在查询中使用 where deployment_environment = "production" 过滤
2. 为每个环境创建独立的仪表盘
3. 使用环境名称作为仪表盘名称的一部分

6. 如何查询自定义指标？

查询自定义指标的方法：

1. 确保指标已通过 OpenTelemetry SDK 发送
2. 在仪表盘中使用指标名称
3. 使用别名便于引用

7. 仪表盘查询性能慢怎么办？

优化方法：

1. 缩小时间范围
2. 使用过滤条件减少数据量
3. 减少 group by 属性
4. 使用采样降低数据精度

8. 如何将 Grafana 仪表盘迁移到 Uptrace？

迁移步骤：

1. 导出 Grafana 仪表盘的查询
2. 将 PromQL 查询转换为 Uptrace 查询语法
3. 在 Uptrace 中重新创建仪表盘
4. 验证数据一致性

下一步

• 告警和通知 - 了解如何配置告警和通知
• 图表注释 - 学习如何在图表中添加注释
• 平台功能使用 - 查看其他平台功能
• 官方文档参考 - 查看 Uptrace 官方文档

参考资源

• Uptrace 仪表盘官方文档
• Uptrace 平台概览
• 项目创建与管理
• 仪表盘模板仓库