配置uptrace环境

Docker部署 Uptrace

官网文档：https://uptrace.dev/get/hosted/docker

Uptrace 运行必要的前置环境：

• Clickhouse 数据库：存放观测数据，traces、metrics、logs
• Postgres 数据库：存放用户和组织数据
• Redis：提供缓存能力
• 还有 Uptrace 本体

其他是可选的环境：

• Otel Collector
• etc……

Exporter 直接导出到 Uptrace

这种方案无需 Otel Collector。

1. 新建一个 docker compose 文件，避免与主程序的compose混在一起。

   docker
   │   ├── data
   │   ├── env
   │   ├── script
   │   └── uptrace
   │       └── docker-compose.yml         # uptrace的docker（独立隔开）
   │   ├── docker-compose.yml             # 主程序docker

2. 写入最基本的service：ch, postgres, redis, uptrace

3. docker网络和主程序公用一个，确保服务端观测数据能发送到监控后端

   ...
   
   networks:
     fzuhelper:
       external: true  # 引用主compose里的fzuhelper网络

4. uptrace 端口映射：

   • 14318 -> 80：访问Uptrace ui，使用 http://localhost:14318
   • 14317 -> 4317：otlp/grpc监听 4317端口，这样本地exporter endpoint 需要设置成 localhost:14317

5. 启动环境和服务：

   1. Uptrace 及其环境

      cd docker/uptrace && docker compose up -d

   2. 打开 Uptrace ui（http://localhost:14318），获取项目的 dsn（FooProject -> DSN），复制到 config.yaml 下的 uptrace.dsn 项

   3. fzuhelper前置环境

      make clean-all
      make env-up

   4. 启动api、common

      make api
      make common

   5. 测试ping

      curl http://localhost:20001/api/v1/trace/ping

   6. 连接成功且ping成功的话，会在看板上新增一条trace（和log）记录。

      

6. 踩坑：如果按上述步骤但是看板没有记录的话，可能是你客户端使用了错误的TLS设置。

   判断方法：

   • 服务端监听的是明文 OTLP/gRPC，客户端就要 WithInsecure()

     • 服务端监听的是TLS/HTTPS 的 OTLP/gRPC，客户端就不能 WithInsecure()，而要走证书校验或自定义 TLS 配置

7. 限制 Clickhouse 占用资源：Uptrace组件中 ck 的资源占大头，它负责存储观测数据。

   目前福uu线上环境：2C16G，起了mysql, redis, etcd, promethus+grafana+cAdvisor, loki+alloy和各种 expoter，以及拉格朗日bot。

   容器	内存	判断
   fzuhelper-mysql	4.919GiB	最大占用，主要来自 InnoDB buffer pool / 查询缓存类内存
   lagrange	1.14GiB	你已说明正常
   fzuhelper-alloy	455.8MiB	日志采集/处理，CPU 和写盘偏高
   fzuhelper-redis	279.7MiB	不算离谱，但写盘累计很高
   fzuhelper-prometheus	271.5MiB	内存正常，但 Block I/O 写入较高
   fzuhelper-bot	253.1MiB	中等偏上，可观察
   fzuhelper-loki	169.7MiB	正常
   fzuhelper-grafana	158.9MiB	正常，但写盘累计较高
   fzuhelper-cadvisor	151.1MiB	正常偏高一点，网络输出很大

   其中最大内存占用是 mysql ，约5G，我们没有配置 innodb_buffer_pool_size ，它自动估算的。

   其次是 lagrange 的 1.14G，这是必须要起的一个QQbot进程。

   剩下6.8G 和 35G磁盘。

   官方文档上的 Uptrace 配置要求：

   Minimum system requirements:

   • 2+ CPU cores

   • 4GB+ RAM

   • 10GB+ disk space for initial setup

   基于以上分析，部署 Uptrace 需要考虑 ck 的资源占用情况。先给它限制了内存到 2G，后面再看需不需要放宽。

8. 设置定期清理观测数据：

   ck 还需设置观测数据ttl，这里先清理的频繁一点：

   • trace 和 log 每 5 天清理
   • metrics 每 9 天清理

   # uptrace.yml
   
   ch_schema:
     spans:
       ttl_delete: ${UPTRACE_RETENTION_SPANS}  # 5 DAY
       storage_policy: 'default'
   
     metrics:
       ttl_delete: ${UPTRACE_RETENTION_METRICS} # 9 DAY
       storage_policy: 'default'

   Uptrace 的配置文件明确支持环境变量展开，我们的真实值就可以保存在环境变量里（docker/env/uptrace.env）