Skip to content
OpenTelemetry 接入文档

平台功能使用

Uptrace 平台提供了丰富的功能来帮助您监控和分析应用性能。本文将介绍平台的主要功能和使用方法。

功能概览

Uptrace 平台支持以下主要功能：

  • 追踪数据查看：查看分布式追踪数据，分析调用链路
  • 指标监控：监控系统和应用性能指标
  • 日志查询：搜索和分析应用日志
  • 服务拓扑：可视化服务依赖关系
  • 告警配置：设置告警规则和通知渠道

追踪数据查看

Trace 列表

访问 Trace 列表

  1. 登录平台：https://uptrace.inner.youdao.com/
  2. 选择项目
  3. 点击左侧导航栏的"Traces"或"追踪"

功能说明

  • 搜索 Trace：通过 Trace ID、服务名、操作名等搜索
  • 时间范围选择：选择要查看的时间范围
  • 过滤条件：按服务、环境、状态等过滤
  • 排序：按时间、持续时间等排序

常用过滤条件

  • 服务名称：service.name = "my-service"
  • 操作名称：span.name = "GET /api/users"
  • 状态：status.code = ERROR
  • 持续时间：duration > 1s
  • 环境：deployment.environment = production

Span 详情

查看 Span 详情

  1. 在 Trace 列表中点击要查看的 Trace
  2. 展开 Trace 树查看所有 Span
  3. 点击具体 Span 查看详情

Span 信息

每个 Span 包含以下信息：

  • 基本信息：

    • Span 名称
    • 开始时间和结束时间
    • 持续时间
    • 状态（成功/失败）

  • 属性信息：

    • HTTP 方法、URL、状态码
    • 数据库查询语句
    • 消息队列主题
    • 自定义属性

  • 事件信息：

    • 关键事件的时间点
    • 异常信息
    • 日志消息

  • 关联信息：

    • 父 Span 和子 Span
    • 关联的 Trace
    • 关联的 Logs

调用链路分析

调用链路视图

  • 时间线视图：按时间顺序显示所有 Span
  • 树形视图：按调用关系显示 Span 树
  • 火焰图：可视化性能瓶颈

性能分析

  • 慢查询识别：找出耗时最长的操作
  • 瓶颈分析：分析性能瓶颈所在
  • 依赖分析：了解服务间的调用关系

指标监控

Metrics 查询

访问 Metrics

  1. 登录平台
  2. 选择项目
  3. 点击左侧导航栏的"Metrics"或"指标"

查询 Metrics

  • 指标名称：选择要查询的指标
  • 时间范围：选择查询的时间范围
  • 聚合方式：按服务、环境等维度聚合
  • 过滤条件：添加过滤条件

常用指标

  • 请求量：http.server.requests
  • 响应时间：http.server.duration
  • 错误率：http.server.errors
  • 系统指标：system.cpu.usage、system.memory.usage

图表展示

创建图表

  1. 在 Metrics 页面点击"创建图表"
  2. 选择指标和聚合方式
  3. 设置图表类型（折线图、柱状图等）
  4. 保存图表

图表类型

  • 折线图：显示指标随时间的变化趋势
  • 柱状图：对比不同维度的指标值
  • 饼图：显示指标分布比例
  • 热力图：显示指标的热度分布

自定义指标

发送自定义指标

使用 OpenTelemetry SDK 发送自定义指标：

// Go 示例
meter := global.Meter("my-service")
counter := meter.NewInt64Counter("custom.business.metric")
counter.Add(ctx, 1, attribute.String("type", "order"))
# Python 示例
from opentelemetry import metrics


meter = metrics.get_meter("my-service")
counter = meter.create_counter("custom.business.metric")
counter.add(1, {"type": "order"})

日志查询

日志搜索

访问日志

  1. 登录平台
  2. 选择项目
  3. 点击左侧导航栏的"Logs"或"日志"

搜索功能

  • 全文搜索：搜索日志内容
  • 字段搜索：按特定字段搜索
  • 时间范围：选择日志时间范围
  • 过滤条件：按服务、级别等过滤

搜索语法

  • 精确匹配：message = "error occurred"
  • 模糊匹配：message ~ "error"
  • 范围查询：level >= WARN
  • 组合查询：service.name = "my-service" AND level = ERROR

日志关联 Trace

自动关联

Uptrace 平台会自动将日志与 Trace 关联：

  • 日志中包含 Trace ID 时自动关联
  • 点击日志可以跳转到关联的 Trace
  • 在 Trace 详情中可以查看关联的日志

手动关联

在日志中添加 Trace ID：

// Go 示例
span := trace.SpanFromContext(ctx)
traceID := span.SpanContext().TraceID().String()
log.WithField("trace_id", traceID).Error("error occurred")

服务拓扑

服务拓扑图

访问服务拓扑

  1. 登录平台
  2. 选择项目
  3. 点击左侧导航栏的"Service Graph"或"服务拓扑"

拓扑图功能

  • 服务节点：显示所有服务
  • 调用关系：显示服务间的调用关系
  • 性能指标：显示每个服务的性能指标
  • 健康状态：显示服务的健康状态

性能指标

拓扑图中显示的性能指标：

  • 请求量：服务处理的请求数量
  • 响应时间：平均响应时间
  • 错误率：错误请求的比例
  • 吞吐量：每秒处理的请求数

依赖分析

依赖关系

  • 上游服务：调用当前服务的服务
  • 下游服务：当前服务调用的服务
  • 依赖深度：服务的依赖层级

影响分析

  • 故障影响：分析服务故障的影响范围
  • 性能影响：分析性能问题的影响
  • 变更影响：分析服务变更的影响

告警配置

Uptrace 提供了强大的告警和通知系统，支持基于指标和错误的监控。详细配置方法请参考告警和通知文档。

告警规则

创建告警规则

  1. 登录平台
  2. 选择项目
  3. 点击左侧导航栏的"Alerts"或"告警"
  4. 点击"创建告警规则"

告警条件

  • 指标告警：基于 Metrics 的告警

    • 例如：错误率 > 5%
    • 例如：响应时间 > 1s

  • 日志告警：基于 Logs 的告警

    • 例如：错误日志数量 > 100/分钟

  • Trace 告警：基于 Trace 的告警

    • 例如：失败 Trace 数量 > 10/分钟

告警规则配置

  • 规则名称：告警规则的名称
  • 条件表达式：告警触发条件
  • 评估窗口：评估时间窗口
  • 阈值：告警阈值
  • 持续时间：持续多长时间触发告警

通知渠道

配置通知渠道

  1. 进入告警设置
  2. 点击"通知渠道"
  3. 添加通知渠道

支持的通知渠道

  • 邮件：发送告警邮件
  • Webhook：自定义 Webhook
  • Slack：发送消息到 Slack 频道
  • Telegram：发送消息到 Telegram
  • PagerDuty：集成 PagerDuty 事件管理

详细配置方法请参考告警和通知文档。

告警历史

查看告警历史

  1. 进入告警页面
  2. 点击"告警历史"
  3. 查看历史告警记录

告警信息

  • 告警时间：告警触发时间
  • 告警内容：告警详细信息
  • 告警状态：已解决/未解决
  • 处理记录：告警处理记录

Dashboard

Uptrace 支持创建自定义仪表盘，可视化指标、追踪和日志数据。详细使用方法请参考仪表盘文档。

创建 Dashboard

  1. 登录平台
  2. 选择项目
  3. 点击左侧导航栏的"Dashboards"或"仪表板"
  4. 点击"创建 Dashboard"

Dashboard 类型

  • 表格仪表盘：数据表格，每行可以链接到网格仪表盘
  • 网格仪表盘：图表网格布局，类似 Grafana

Dashboard 组件

  • 图表：添加 Metrics 图表
  • Trace 列表：显示 Trace 列表
  • 日志流：显示实时日志
  • 服务拓扑：显示服务拓扑图

自定义 Dashboard

  • 布局调整：拖拽调整组件位置
  • 时间同步：所有组件使用相同时间范围
  • 共享：分享 Dashboard 给团队成员
  • YAML 配置：支持通过 YAML 配置文件定义仪表盘

详细配置方法和示例请参考仪表盘文档。

图表注释

Uptrace 支持在图表上添加注释，标记部署、发布、故障等关键事件。详细使用方法请参考图表注释文档。

创建注释

可以通过 API 创建注释：

curl -X POST https://api.uptrace.dev/api/v1/annotations \
  -H 'uptrace-dsn: <YOUR_DSN>' \
  -d '{"name": "Deployed to production", "attrs": {"service.version": "v1.2.3"}}'

注释用途

  • 部署标记：标记版本部署时间
  • 事件关联：将时间线事件与指标变化关联
  • 问题排查：标记故障发生时间

详细 API 使用方法和示例请参考图表注释文档。

数据导出

导出 Trace

  1. 在 Trace 列表中选择要导出的 Trace
  2. 点击"导出"按钮
  3. 选择导出格式（JSON、CSV 等）

导出 Metrics

  1. 在 Metrics 页面选择指标
  2. 点击"导出"按钮
  3. 选择导出格式和时间范围

导出日志

  1. 在日志页面设置过滤条件
  2. 点击"导出"按钮
  3. 选择导出格式和数量限制

最佳实践

1. 合理使用过滤条件

  • 使用服务名、环境等过滤条件缩小查询范围
  • 避免查询过大的时间范围
  • 使用索引字段进行过滤

2. 设置合适的采样率

  • 生产环境使用较低的采样率（如 10%）
  • 开发环境可以使用 100% 采样
  • 根据数据量调整采样率

3. 定期检查告警规则

  • 定期审查告警规则的有效性
  • 调整告警阈值避免误报
  • 清理不再使用的告警规则

4. 使用 Dashboard 监控关键指标

  • 创建 Dashboard 监控关键业务指标
  • 定期查看 Dashboard 了解系统状态
  • 与团队成员分享 Dashboard

常见问题

1. 为什么看不到 Trace 数据？

  • 检查应用是否正确配置了 DSN
  • 确认应用正在发送数据
  • 检查时间范围是否正确
  • 确认采样率设置

2. 如何提高查询性能？

  • 缩小时间范围
  • 使用过滤条件
  • 避免查询过多数据
  • 使用索引字段

3. 告警没有触发？

  • 检查告警规则配置是否正确
  • 确认告警条件是否满足
  • 检查通知渠道配置
  • 查看告警历史记录

下一步

参考资源

在Gitlab上编辑本文档