Clawdbot汉化版可观测性：OpenTelemetry接入+Grafana仪表盘定制

1. 引言：为什么你的AI助手需要“体检报告”？

想象一下，你有一个24小时在线的AI助手，它帮你处理微信消息、回答各种问题、甚至帮你写代码。但有一天，你发现它回复变慢了，或者干脆不说话了。你该怎么办？是重启服务？还是换个模型？或者，你根本不知道问题出在哪里。

这就是为什么我们需要给Clawdbot这样的AI助手加上“可观测性”。简单来说，就是给它装上一套“体检系统”，让你随时能看到它的心跳、呼吸、血压——也就是它的运行状态、性能指标和错误日志。

今天我要分享的，就是如何为Clawdbot汉化版（特别是增加了企业微信入口的版本）搭建一套完整的可观测性系统。我们会用OpenTelemetry来收集数据，用Grafana来展示仪表盘。学完这篇教程，你就能：

• 实时监控：随时查看AI助手的响应速度、对话量、错误率
• 快速排障：一眼看出是模型问题、网络问题还是代码问题
• 优化性能：找到瓶颈，让AI助手跑得更快更稳
• 数据驱动：用真实数据决定什么时候升级硬件、什么时候换模型

无论你是个人用户还是企业部署，这套系统都能让你的Clawdbot从“黑盒”变成“透明盒”，运维起来得心应手。

2. 准备工作：你需要什么？

在开始之前，我们先确认一下环境。假设你已经按照之前的教程部署好了Clawdbot汉化版，并且它正在正常运行。

2.1 系统要求

• 操作系统：Ubuntu 20.04或更高版本（其他Linux发行版也可以，命令可能略有不同）
• Clawdbot：已部署并运行正常
• Docker：已安装（用于运行Grafana和OpenTelemetry Collector）
• 基础工具：curl、git、vim/nano等常用命令

2.2 检查当前状态

先确认你的Clawdbot正在运行：

# 检查服务状态
ps aux | grep clawdbot

# 应该能看到类似这样的输出
# root     133175  clawdbot-gateway
# root     133176  node dist/index.js

# 测试AI助手是否正常工作
cd /root/clawdbot
node dist/index.js agent --agent main --message "你好，测试一下"

如果一切正常，AI应该会回复你。接下来我们就可以开始搭建监控系统了。

3. OpenTelemetry入门：什么是可观测性的“普通话”？

在讲具体操作之前，我们先花几分钟理解一下OpenTelemetry。你可以把它想象成可观测性领域的“普通话”——一种通用的数据采集标准。

3.1 为什么需要OpenTelemetry？

在没有OpenTelemetry之前，每个监控工具都有自己的数据格式：

• Prometheus用它的格式收指标
• Jaeger用它的格式收链路追踪
• 各种日志系统又有各自的格式

这就好比你去一个城市，每个区都说不同的方言，沟通起来特别费劲。OpenTelemetry的出现，就是为了解决这个问题。它定义了一套标准的数据格式（就像普通话），让不同的工具都能听懂。

3.2 OpenTelemetry的三大支柱

OpenTelemetry主要收集三种数据：

1. 指标（Metrics）：就像汽车的仪表盘，显示当前的速度、转速、油量

   • Clawdbot的响应时间
   • 每分钟处理的对话数量
   • 内存和CPU使用率
   • 错误率

2. 链路追踪（Traces）：就像快递的物流信息，显示包裹经过了哪些环节

   • 用户发出一条消息后，Clawdbot内部的处理流程
   • 每个步骤花了多少时间
   • 哪里出现了瓶颈

3. 日志（Logs）：就像黑匣子的录音，记录详细的事件

   • AI模型调用的详细参数
   • 错误堆栈信息
   • 重要的业务事件

对于Clawdbot来说，我们最关心的是指标和日志，因为链路追踪对AI助手的价值相对较小。

4. 第一步：安装和配置OpenTelemetry Collector

OpenTelemetry Collector是一个数据收集器，它负责从Clawdbot收集数据，然后转发给Grafana（或者其他监控系统）。

4.1 创建配置文件

首先，我们创建一个配置文件，告诉Collector要收集什么数据、怎么处理、发给谁。

# 创建配置目录
mkdir -p /etc/otelcol
cd /etc/otelcol

# 创建配置文件
cat > config.yaml << 'EOF'
receivers:
  # 接收Prometheus格式的指标
  prometheus:
    config:
      scrape_configs:
        - job_name: 'clawdbot'
          scrape_interval: 15s
          static_configs:
            - targets: ['localhost:9464']  # Clawdbot的指标端口
              labels:
                service: 'clawdbot'
                environment: 'production'

  # 接收OTLP格式的数据（Clawdbot会通过这个协议发送数据）
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  # 批量处理，提高效率
  batch:
    timeout: 1s
    send_batch_size: 1024

  # 添加一些有用的属性
  attributes:
    actions:
      - key: deployment.environment
        value: production
        action: upsert

exporters:
  # 发送到Prometheus（Grafana会从Prometheus读取数据）
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: clawdbot
    const_labels:
      service: "clawdbot"

  # 也可以发送到控制台，方便调试
  debug:
    verbosity: detailed

service:
  pipelines:
    metrics:
      receivers: [prometheus, otlp]
      processors: [batch, attributes]
      exporters: [prometheus, debug]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
EOF

这个配置文件做了几件事：

• 从localhost:9464端口收集Clawdbot的Prometheus指标
• 从4317和4318端口接收OTLP格式的数据
• 处理数据（批量、添加标签）
• 把数据发送给Prometheus（端口8889）和控制台

4.2 用Docker运行Collector

最简单的方式是用Docker运行：

# 创建Docker网络（如果还没有）
docker network create monitoring

# 运行OpenTelemetry Collector
docker run -d \
  --name otel-collector \
  --network monitoring \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8889:8889 \
  -v /etc/otelcol/config.yaml:/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:latest

检查是否运行成功：

docker ps | grep otel-collector
# 应该能看到容器正在运行

# 检查日志
docker logs otel-collector --tail 20
# 应该看到类似 "Everything is ready. Begin running and processing data."

4.3 验证Collector工作

我们可以用curl简单测试一下：

# 检查Prometheus端点
curl http://localhost:8889/metrics
# 应该能看到一些OpenTelemetry自己的指标

# 检查健康状态
curl http://localhost:13133/health
# 应该返回 {"status": "Server available"}

好了，数据收集器已经就位。接下来我们要让Clawdbot把数据发送过来。

5. 第二步：改造Clawdbot，让它“开口说话”

默认情况下，Clawdbot不会主动上报监控数据。我们需要对它进行一些改造，让它把运行状态告诉OpenTelemetry Collector。

5.1 安装必要的Node.js包

首先，进入Clawdbot目录，安装OpenTelemetry相关的包：

cd /root/clawdbot

# 安装OpenTelemetry SDK
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/resources @opentelemetry/semantic-conventions

# 或者用pnpm（如果Clawdbot用的是pnpm）
pnpm add @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/resources @opentelemetry/semantic-conventions

5.2 创建OpenTelemetry初始化脚本

我们需要创建一个脚本，在Clawdbot启动时初始化OpenTelemetry：

# 创建初始化脚本
cat > /root/clawdbot/otel-init.js << 'EOF'
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { Resource } = require('@opentelemetry/resources');
const { SEMRESATTRS_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

// 创建资源标识
const resource = new Resource({
  [SEMRESATTRS_SERVICE_NAME]: 'clawdbot',
  'deployment.environment': 'production',
  'version': '1.0.0'
});

// 配置指标导出器
const metricExporter = new OTLPMetricExporter({
  url: 'http://localhost:4317', // OpenTelemetry Collector的地址
});

// 配置链路追踪导出器
const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4317',
});

// 创建SDK实例
const sdk = new NodeSDK({
  resource,
  metricReader: new PeriodicExportingMetricReader({
    exporter: metricExporter,
    exportIntervalMillis: 15000, // 每15秒导出一次
  }),
  traceExporter,
  instrumentations: [
    getNodeAutoInstrumentations({
      // 启用HTTP和gRPC自动埋点
      '@opentelemetry/instrumentation-http': {
        enabled: true,
      },
      '@opentelemetry/instrumentation-grpc': {
        enabled: true,
      },
    }),
  ],
});

// 启动SDK
sdk.start()
  .then(() => console.log('OpenTelemetry SDK started'))
  .catch((error) => console.error('Error starting OpenTelemetry SDK', error));

// 优雅关闭
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('OpenTelemetry SDK shut down'))
    .catch((error) => console.error('Error shutting down OpenTelemetry SDK', error))
    .finally(() => process.exit(0));
});
EOF

5.3 修改Clawdbot启动脚本

现在我们需要修改Clawdbot的启动方式，让它加载我们的OpenTelemetry初始化脚本：

# 备份原来的启动脚本
cp /root/start-clawdbot.sh /root/start-clawdbot.sh.backup

# 编辑启动脚本
cat > /root/start-clawdbot.sh << 'EOF'
#!/bin/bash

# 先启动OpenTelemetry初始化
echo "Starting OpenTelemetry instrumentation..."
node /root/clawdbot/otel-init.js &

# 等待OpenTelemetry初始化完成
sleep 3

# 启动Clawdbot Gateway
echo "Starting Clawdbot Gateway..."
cd /root/clawdbot
node --require ./otel-init.js dist/index.js gateway
EOF

# 给脚本执行权限
chmod +x /root/start-clawdbot.sh

5.4 添加自定义指标

除了自动收集的指标，我们还可以添加一些业务相关的自定义指标。比如，我们想知道AI助手处理了多少条消息、平均响应时间是多少。

创建一个自定义指标文件：

cat > /root/clawdbot/custom-metrics.js << 'EOF'
const { metrics } = require('@opentelemetry/api');

// 获取计量器
const meter = metrics.getMeter('clawdbot-custom');

// 创建自定义指标
const messageCounter = meter.createCounter('clawdbot_messages_total', {
  description: 'Total number of messages processed',
});

const responseTimeHistogram = meter.createHistogram('clawdbot_response_time_seconds', {
  description: 'Response time in seconds',
  unit: 's',
  boundaries: [0.1, 0.5, 1, 2, 5, 10], // 响应时间分段
});

const errorCounter = meter.createCounter('clawdbot_errors_total', {
  description: 'Total number of errors',
});

// 导出这些指标，供其他文件使用
module.exports = {
  messageCounter,
  responseTimeHistogram,
  errorCounter,
  
  // 工具函数：记录消息处理
  recordMessage: (responseTime) => {
    messageCounter.add(1);
    if (responseTime !== undefined) {
      responseTimeHistogram.record(responseTime);
    }
  },
  
  // 工具函数：记录错误
  recordError: () => {
    errorCounter.add(1);
  },
};
EOF

5.5 修改Clawdbot代码注入指标

我们需要找到Clawdbot处理消息的地方，添加上我们的指标记录。这需要修改Clawdbot的源代码：

# 首先找到处理消息的主要文件
# 通常是在dist/index.js或者src目录下
# 这里我们假设主要逻辑在src/agent.js（具体路径可能不同）

# 备份原文件
cp /root/clawdbot/src/agent.js /root/clawdbot/src/agent.js.backup

# 编辑文件，在适当位置添加指标记录
# 这里只是一个示例，实际修改需要根据你的代码结构来
cat >> /root/clawdbot/src/agent.js << 'EOF'

// 在文件开头引入自定义指标
const { recordMessage, recordError } = require('../custom-metrics');

// 然后找到处理消息的函数，比如processMessage
// 在函数开始处添加：
const startTime = Date.now();

// 在成功处理完消息后添加：
const responseTime = (Date.now() - startTime) / 1000; // 转换为秒
recordMessage(responseTime);

// 在出错的地方添加：
recordError();
EOF

注意：上面的代码修改只是示例，实际修改需要根据你的Clawdbot代码结构来。如果你不熟悉Node.js或者不想修改源代码，也可以跳过这一步，OpenTelemetry的自动埋点已经能收集很多有用的指标了。

5.6 重启Clawdbot并测试

现在重启Clawdbot，让修改生效：

# 停止现有服务
pkill -f clawdbot

# 重新启动
bash /root/start-clawdbot.sh

# 检查是否正常运行
ps aux | grep clawdbot

# 测试AI助手
cd /root/clawdbot
node dist/index.js agent --agent main --message "测试监控系统"

如果一切正常，你应该能看到AI的回复，同时OpenTelemetry已经开始收集数据了。

6. 第三步：安装和配置Grafana

数据收集好了，现在我们需要一个漂亮的面板来展示这些数据。Grafana就是干这个的——它能把枯燥的数据变成直观的图表。

6.1 用Docker运行Grafana

# 创建Grafana数据目录
mkdir -p /var/lib/grafana

# 运行Grafana
docker run -d \
  --name grafana \
  --network monitoring \
  -p 3000:3000 \
  -v /var/lib/grafana:/var/lib/grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=admin123" \
  grafana/grafana:latest

这里我们设置了管理员密码为admin123，你可以改成自己的密码。

6.2 安装Prometheus数据源

Grafana本身不存储数据，它需要从数据源读取数据。我们的数据在Prometheus格式的端点上（就是OpenTelemetry Collector的8889端口）。

1. 打开浏览器，访问 http://你的服务器IP:3000
2. 用 admin 和 admin123 登录
3. 点击左侧菜单的 ⚙️ 图标（Configuration）→ Data Sources
4. 点击 "Add data source"
5. 选择 "Prometheus"
6. 配置如下：
   • Name: Clawdbot Metrics
   • URL: http://otel-collector:8889 （注意：这里用的是容器名，因为它们在同一个Docker网络里）
   • 其他保持默认
7. 点击 "Save & Test"，应该看到 "Data source is working" 的提示

6.3 验证数据是否正常

在添加仪表盘之前，我们先确认一下数据是否正常流入：

1. 在Grafana左侧菜单，点击 🔍 图标（Explore）
2. 在数据源选择框，选择 "Clawdbot Metrics"
3. 在指标查询框，输入 clawdbot_ 然后按Tab键
4. 你应该能看到一些以 clawdbot_ 开头的指标，比如：
   • clawdbot_messages_total
   • clawdbot_response_time_seconds
   • 还有OpenTelemetry自动收集的各种指标

如果能看到这些指标，说明数据链路已经通了！

7. 第四步：创建Clawdbot专属仪表盘

现在到了最有趣的部分——创建仪表盘。我们会设计几个关键的面板，让你一眼就能掌握Clawdbot的健康状况。

7.1 创建新的仪表盘

1. 在Grafana左侧菜单，点击 📈 图标（Dashboards）
2. 点击 "New dashboard"
3. 点击 "Add visualization"

7.2 添加第一个面板：消息处理统计

这个面板显示Clawdbot处理了多少消息，以及处理速度。

配置步骤：

1. 面板标题：改为 "消息处理统计"
2. 查询A：

   rate(clawdbot_messages_total[5m])
   

   • 这显示每分钟处理的消息数
3. 可视化类型：选择 "Stat"
4. 字段设置：
   • Unit：选择 "requests/sec"
   • Thresholds：设置阈值（比如绿色<10，黄色10-50，红色>50）
5. 面板选项：
   • Description：添加描述 "每分钟处理的消息数量"
   • 调整面板大小和位置

7.3 添加第二个面板：响应时间分布

这个面板显示AI助手的响应时间，帮你发现性能问题。

配置步骤：

1. 点击仪表盘右上角的 "Add panel"
2. 面板标题：改为 "响应时间分布"
3. 查询A：

   histogram_quantile(0.95, rate(clawdbot_response_time_seconds_bucket[5m]))
   

   • 这显示95%的请求在多少秒内完成
4. 查询B：

   histogram_quantile(0.50, rate(clawdbot_response_time_seconds_bucket[5m]))
   

   • 这显示中位数响应时间
5. 可视化类型：选择 "Time series"
6. 图例设置：
   • 显示为 "{{query}}"
7. 面板选项：
   • Y轴：单位选择 "seconds"
   • Thresholds：添加参考线（比如1秒、3秒、5秒）

7.4 添加第三个面板：错误率监控

错误率是系统健康的重要指标。

配置步骤：

1. 添加新面板
2. 面板标题：改为 "错误率"
3. 查询A：

   rate(clawdbot_errors_total[5m]) / rate(clawdbot_messages_total[5m]) * 100
   

   • 计算错误率百分比
4. 可视化类型：选择 "Gauge"
5. 字段设置：
   • Unit：选择 "percent"
   • Min：0
   • Max：100
6. 阈值设置：
   • 绿色：0-1%
   • 黄色：1-5%
   • 红色：>5%

7.5 添加第四个面板：系统资源监控

除了业务指标，我们还需要监控系统资源。

配置步骤：

1. 添加新面板
2. 面板标题：改为 "CPU和内存使用率"
3. 查询A（CPU）：

   rate(process_cpu_seconds_total[5m]) * 100
   

4. 查询B（内存）：

   process_resident_memory_bytes / 1024 / 1024
   

   • 单位是MB
5. 可视化类型：选择 "Time series"
6. 图例设置：
   • CPU：{{query}} %
   • 内存：{{query}} MB

7.6 添加第五个面板：活跃用户统计

如果你有多个用户在使用Clawdbot，这个面板很有用。

配置步骤：

1. 添加新面板
2. 面板标题：改为 "活跃用户"
3. 查询：

   sum by (user) (rate(clawdbot_messages_total[5m]))
   

4. 可视化类型：选择 "Bar chart"
5. 图例设置：显示每个用户的请求频率

7.7 添加第六个面板：AI模型性能

这个面板显示不同AI模型的性能对比。

配置步骤：

1. 添加新面板
2. 面板标题：改为 "AI模型性能对比"
3. 查询A（响应时间）：

   histogram_quantile(0.95, sum by (model) (rate(clawdbot_response_time_seconds_bucket[5m])))
   

4. 查询B（错误率）：

   sum by (model) (rate(clawdbot_errors_total[5m])) / sum by (model) (rate(clawdbot_messages_total[5m])) * 100
   

5. 可视化类型：选择 "Table"
6. 字段设置：
   • 第一列：模型名称
   • 第二列：95%响应时间（单位秒）
   • 第三列：错误率（单位%）

7.8 整理仪表盘布局

现在我们有6个面板了，需要整理一下布局：

1. 第一行：放最重要的面板

   • 左侧：消息处理统计（大一些）
   • 右侧：错误率（小一些）

2. 第二行：放性能相关面板

   • 响应时间分布（全宽）

3. 第三行：放系统和用户面板

   • 左侧：CPU和内存使用率
   • 右侧：活跃用户统计

4. 第四行：放详细信息

   • AI模型性能对比（全宽）

调整每个面板的大小和位置，让整个仪表盘看起来整洁美观。

7.9 保存仪表盘

1. 点击右上角的 "Save" 按钮
2. Dashboard name：输入 "Clawdbot监控中心"
3. Folder：选择 "General" 或者新建一个文件夹
4. 点击 "Save"

恭喜！你的第一个Clawdbot监控仪表盘就创建完成了。

8. 第五步：高级功能与定制

基础仪表盘有了，现在我们来看看一些高级功能，让监控系统更加强大。

8.1 设置告警规则

监控不仅要看，还要能主动告警。Grafana可以设置告警规则，当指标异常时自动通知你。

示例：响应时间过长告警

1. 在仪表盘编辑页面，点击 "响应时间分布" 面板的标题
2. 选择 "Edit"
3. 点击右上角的 "Alert" 标签
4. 点击 "Create alert rule from this panel"
5. 规则名称：输入 "Clawdbot响应时间过长"
6. 查询：使用现有的查询

   histogram_quantile(0.95, rate(clawdbot_response_time_seconds_bucket[5m]))
   

7. 条件：
   • 当 last() 的 value() 大于 5（秒）
   • 持续 5 分钟
8. 通知渠道：
   • 如果你配置了邮件、Slack、企业微信等通知渠道，可以在这里选择
   • 如果没有，可以先保存，后续再配置

示例：错误率过高告警

同样的方法，可以设置错误率告警：

1. 规则名称："Clawdbot错误率过高"
2. 查询：

   rate(clawdbot_errors_total[5m]) / rate(clawdbot_messages_total[5m]) * 100
   

3. 条件：
   • 当 last() 的 value() 大于 5（%）
   • 持续 2 分钟

8.2 创建企业微信通知

如果你在企业微信中使用Clawdbot，可以配置企业微信告警：

1. 在Grafana中配置企业微信Webhook：

   • 进入 Configuration → Alerting → Contact points
   • 点击 "Add contact point"
   • 类型选择 "DingDing"（企业微信兼容DingDing格式）
   • 填写企业微信机器人的Webhook URL

2. 创建通知策略：

   • 进入 Configuration → Alerting → Notification policies
   • 设置匹配标签和通知渠道

8.3 添加自定义变量

如果你的Clawdbot有多个实例或者多个环境，可以添加变量来动态切换：

1. 在仪表盘设置中，点击 "Variables"
2. 点击 "Add variable"
3. Name：environment
4. Type：Query
5. Query：

   label_values(environment)
   

6. 在面板查询中使用变量：

   rate(clawdbot_messages_total{environment="$environment"}[5m])
   

这样你就可以在仪表盘顶部看到一个下拉框，选择不同的环境来查看对应的数据。

8.4 导出和导入仪表盘

一旦你创建了一个满意的仪表盘，可以导出为JSON文件，方便分享或备份：

# 通过Grafana API导出仪表盘
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/dashboards/uid/YOUR_DASHBOARD_UID \
  | jq '.dashboard' > clawdbot-dashboard.json

# 导入仪表盘
curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d @clawdbot-dashboard.json \
  http://localhost:3000/api/dashboards/db

获取API Key：

1. 在Grafana中，点击左侧菜单的 ⚙️ → API Keys
2. 点击 "Add API key"
3. 输入名称，选择角色为 "Admin"
4. 复制生成的Key

8.5 自动化部署脚本

为了方便其他人部署同样的监控系统，我们可以创建一个自动化脚本：

cat > /root/setup-monitoring.sh << 'EOF'
#!/bin/bash

echo "开始部署Clawdbot监控系统..."

# 1. 创建OpenTelemetry配置
echo "创建OpenTelemetry配置..."
mkdir -p /etc/otelcol
cat > /etc/otelcol/config.yaml << 'CONFIG_EOF'
receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: 'clawdbot'
          scrape_interval: 15s
          static_configs:
            - targets: ['localhost:9464']
              labels:
                service: 'clawdbot'
                environment: 'production'
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  attributes:
    actions:
      - key: deployment.environment
        value: production
        action: upsert

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: clawdbot
    const_labels:
      service: "clawdbot"
  debug:
    verbosity: detailed

service:
  pipelines:
    metrics:
      receivers: [prometheus, otlp]
      processors: [batch, attributes]
      exporters: [prometheus, debug]
CONFIG_EOF

# 2. 启动OpenTelemetry Collector
echo "启动OpenTelemetry Collector..."
docker network create monitoring 2>/dev/null || true
docker run -d \
  --name otel-collector \
  --network monitoring \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8889:8889 \
  -v /etc/otelcol/config.yaml:/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:latest

# 3. 启动Grafana
echo "启动Grafana..."
docker run -d \
  --name grafana \
  --network monitoring \
  -p 3000:3000 \
  -v /var/lib/grafana:/var/lib/grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=admin123" \
  grafana/grafana:latest

# 4. 等待服务启动
echo "等待服务启动..."
sleep 10

# 5. 检查服务状态
echo "检查服务状态..."
docker ps | grep -E "(otel-collector|grafana)"

echo "部署完成！"
echo "Grafana地址: http://$(hostname -I | awk '{print $1}'):3000"
echo "用户名: admin"
echo "密码: admin123"
EOF

chmod +x /root/setup-monitoring.sh

9. 实际应用场景

现在监控系统搭建好了，我们来看看在实际工作中怎么用它。

9.1 场景一：性能瓶颈分析

问题：用户反馈AI助手响应变慢

排查步骤：

1. 打开Grafana仪表盘
2. 查看"响应时间分布"面板
   • 如果95%响应时间从1秒变成了5秒，说明确实变慢了
3. 查看"CPU和内存使用率"面板
   • 如果CPU使用率接近100%，可能是计算资源不足
   • 如果内存使用率很高，可能需要优化内存使用
4. 查看"AI模型性能对比"面板
   • 如果某个模型的响应时间特别长，考虑换一个更快的模型
5. 查看"错误率"面板
   • 如果错误率升高，可能是模型调用失败或网络问题

解决方案：

• 如果是CPU瓶颈：升级服务器配置，或者优化代码
• 如果是内存瓶颈：增加内存，或者优化内存使用
• 如果是模型问题：换一个更快的模型，比如从llama3.2换成qwen2:1.5b

9.2 场景二：容量规划

问题：计划增加用户，需要评估当前配置是否够用

分析步骤：

1. 查看"消息处理统计"面板的历史趋势
   • 了解当前的消息处理量
   • 观察高峰时段的处理能力
2. 查看"活跃用户"面板
   • 了解当前并发用户数
3. 压力测试：

   # 模拟多个用户同时请求
   for i in {1..10}; do
     node dist/index.js agent --agent main --message "测试消息 $i" &
   done
   

4. 观察监控指标的变化
   • 响应时间是否还在可接受范围内
   • 错误率是否升高
   • 系统资源是否吃紧

决策依据：

• 如果当前配置在压力测试下表现良好，可以支持更多用户
• 如果出现瓶颈，需要提前扩容

9.3 场景三：故障排查

问题：AI助手突然不响应了

排查步骤：

1. 首先看"错误率"面板
   • 如果错误率飙升到100%，说明服务完全不可用
2. 查看系统日志：

   tail -f /tmp/clawdbot-gateway.log
   

3. 检查服务状态：

   ps aux | grep clawdbot
   docker ps | grep otel-collector
   

4. 根据错误信息采取相应措施：
   • 如果是模型加载失败：重启服务或重新下载模型
   • 如果是内存溢出：增加内存或优化代码
   • 如果是网络问题：检查网络连接

9.4 场景四：优化AI模型选择

问题：不知道用哪个AI模型性价比最高

分析方法：

1. 同时部署多个AI模型
2. 为每个模型创建单独的agent
3. 在监控系统中区分不同模型的指标
4. 运行同样的测试任务，对比：
   • 响应时间
   • 回答质量（可以人工评估）
   • 资源消耗
   • 错误率

决策：选择在性能、质量和成本之间平衡最好的模型。

10. 总结与最佳实践

10.1 学到了什么？

通过这篇教程，我们完成了一个完整的Clawdbot监控系统搭建：

1. 理解了可观测性的重要性：监控不是可有可无的装饰，而是运维的"眼睛"
2. 掌握了OpenTelemetry：学会了用这个标准工具收集指标、链路和日志
3. 搭建了Grafana仪表盘：创建了6个关键面板，覆盖了业务和系统监控
4. 实现了自动化告警：设置了响应时间和错误率的告警规则
5. 学会了实际应用：掌握了性能分析、容量规划、故障排查的方法

10.2 最佳实践建议

根据我的经验，这里有一些建议：

监控指标的选择：

• 必监控：响应时间、错误率、请求量、系统资源
• 推荐监控：AI模型性能、用户行为、业务指标
• 高级监控：自定义业务指标、用户体验指标

告警策略：

• 不要过度告警：设置合理的阈值，避免告警疲劳
• 分级告警：紧急问题立即通知，一般问题每日汇总
• 告警收敛：相同问题不要重复告警

仪表盘设计：

• 分层设计：概览页看整体，详情页看具体
• 按角色设计：开发看技术指标，业务看业务指标
• 保持简洁：一个面板只讲一个故事

维护建议：

• 定期回顾：每周花10分钟看看监控数据，发现趋势
• 持续优化：根据实际使用调整监控项和告警阈值
• 文档化：记录监控系统的配置和运维流程

10.3 下一步可以做什么？

如果你还想深入，可以考虑：

1. 日志集中管理：把Clawdbot的日志也收集起来，用ELK或Loki分析
2. 分布式追踪：如果Clawdbot调用其他服务，可以加上链路追踪
3. 自动化运维：基于监控数据自动扩缩容、自动重启服务
4. 成本监控：监控AI API调用成本，优化使用策略
5. 用户体验监控：从用户角度监控响应时间和成功率

10.4 最后的提醒

监控系统搭建好了，但记住几个关键点：

• 监控是手段，不是目的：最终目标是保证服务稳定、快速、可靠
• 数据要 actionable：监控到的异常要能指导行动
• 保持简单：复杂的监控系统难以维护，从简单开始，逐步完善
• 定期演练：定期模拟故障，检验监控和告警是否有效

现在你的Clawdbot已经从一个"黑盒"变成了"透明盒"。你可以随时了解它的健康状况，快速定位问题，优化性能。更重要的是，你可以用数据说话，而不是凭感觉猜测。

希望这套监控系统能帮你更好地管理和优化Clawdbot。如果在使用过程中遇到问题，或者有更好的想法，欢迎分享和交流。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。