# prom-agent

**Repository Path**: hongbin1/prom-agent

## Basic Information

- **Project Name**: prom-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Artistic-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Agent, promtheus, ClaudeCode

## README

# AI Observability Agent

> 高性能、可扩展的 AI 监控代理，专为大模型时代设计

## 项目简介

AI Observability Agent 是一个基于 Rust 开发的高性能监控代理，专为大模型时代的 AI 服务监控设计。它提供了全面的监控能力，包括系统指标采集、AI 服务监控、成本追踪、质量评估等功能，帮助企业和开发者更好地管理和优化 AI 资源的使用。

## 主要特性

### 1. 多维度监控

- **系统监控**：CPU、内存、磁盘、网络等系统指标
- **AI 监控**：OpenAI、LiteLLM、Claude Code 等 AI 服务
- **服务监控**：HTTP 端点抓取
- **自定义监控**：插件系统支持

### 2. 高级功能

- **OTLP 协议支持**：原生支持 OpenTelemetry 协议
- **成本追踪**：实时计算 AI API 成本，支持预算管理
- **质量监控**：AI 服务质量评估，支持多维度评分
- **插件系统**：HTTP、Exec、Script 三种插件类型
- **本地持久化**：网络故障时数据保护
- **多端点故障转移**：高可用性保障

### 3. 性能优势

- **低资源占用**：CPU < 1%，内存 < 30MB
- **高并发**：支持高并发请求处理
- **低延迟**：API 响应时间 < 1ms
- **高吞吐量**：每秒可处理近 6000 个样本
- **跨平台**：支持 Linux、macOS、Windows

## 系统要求

| 平台 | 最低配置 | 推荐配置 |
|------|----------|----------|
| **Linux** | 1 CPU, 512MB RAM | 2 CPU, 1GB RAM |
| **macOS** | 1 CPU, 512MB RAM | 2 CPU, 1GB RAM |
| **Windows** | 1 CPU, 1GB RAM | 2 CPU, 2GB RAM |

### 软件要求

- **Rust** 1.70+（仅用于从源码构建）
- **Prometheus** 2.33+（用于接收 Remote Write 数据）
- **Grafana** 9.0+（用于可视化，可选）

## 安装部署

### 1. 二进制部署

从 Gitee Releases 页面下载对应平台的二进制文件：

```bash
# Linux (x86_64)
wget https://gitee.com/hongbin1/prom-agent/releases/download/v0.1.0/prom-agent-linux-amd64

# Linux (ARM64)
wget https://gitee.com/hongbin1/prom-agent/releases/download/v0.1.0/prom-agent-linux-arm64

# macOS (x86_64)
wget https://gitee.com/hongbin1/prom-agent/releases/download/v0.1.0/prom-agent-darwin-amd64

# macOS (ARM64)
wget https://gitee.com/hongbin1/prom-agent/releases/download/v0.1.0/prom-agent-darwin-arm64

# Windows
download https://gitee.com/hongbin1/prom-agent/releases/download/v0.1.0/prom-agent-windows-amd64.exe
```

赋予执行权限并运行：

```bash
# Linux/macOS
chmod +x prom-agent-*
./prom-agent-linux-amd64 config/agent_config.yaml

# Windows
prom-agent-windows-amd64.exe config/agent_config.yaml
```

### 2. Docker 部署

```bash
git clone https://gitee.com/hongbin1/prom-agent.git
cd prom-agent
docker build -t prom-agent:latest .

# 使用 docker-compose
docker-compose up -d

# 或手动运行
docker run -d \
  --name prom-agent \
  --restart=always \
  -p 9090:9090 \
  -p 4317:4317 \
  -p 4318:4318 \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v ./config:/etc/prom-agent \
  prom-agent:latest \
  /etc/prom-agent/agent_config.yaml
```

### 3. Kubernetes 部署

使用 Helm chart 部署（推荐）：

```bash
git clone https://gitee.com/hongbin1/prom-agent.git
cd prom-agent
helm install prom-agent ./helm/prom-agent --namespace monitoring --create-namespace
```

或使用手动配置：

```yaml
# prom-agent-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: prom-agent-config
  namespace: monitoring
data:
  agent_config.yaml: |
    agent:
      log_level: info
      listen_address: 0.0.0.0:9090
    system_collector:
      enabled: true
    otlp:
      enabled: true
    remote_write:
      endpoint: http://prometheus.monitoring:9090/api/v1/write
---
# prom-agent-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: prom-agent
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: prom-agent
  template:
    metadata:
      labels:
        app: prom-agent
    spec:
      hostPID: true
      hostNetwork: true
      containers:
        - name: prom-agent
          image: prom-agent:latest
          args:
            - /etc/prom-agent/agent_config.yaml
          ports:
            - containerPort: 9090
              name: http
            - containerPort: 4317
              name: otlp-grpc
            - containerPort: 4318
              name: otlp-http
          volumeMounts:
            - name: proc
              mountPath: /host/proc
              readOnly: true
            - name: sys
              mountPath: /host/sys
              readOnly: true
            - name: config
              mountPath: /etc/prom-agent
            - name: data
              mountPath: /var/lib/prom-agent
      volumes:
        - name: proc
          hostPath:
            path: /proc
        - name: sys
          hostPath:
            path: /sys
        - name: config
          configMap:
            name: prom-agent-config
        - name: data
          emptyDir: {}
```

### 4. 包管理器部署

#### DEB 包（Debian/Ubuntu）

```bash
# 构建 DEB 包
./build_deb.sh

# 安装
sudo dpkg -i prom-agent_0.1.0_amd64.deb
```

#### RPM 包（CentOS/RHEL）

```bash
# 构建 RPM 包
./build_rpm.sh

# 安装
sudo rpm -ivh prom-agent-0.1.0-1.x86_64.rpm
```

### 5. 自动化部署脚本

使用提供的部署脚本进行自动化安装：

```bash
# 安装
./deploy.sh install

# 启动服务
./deploy.sh start

# 检查状态
./deploy.sh status

# 停止服务
./deploy.sh stop

# 卸载
./deploy.sh uninstall
```

## 配置说明

### 最小配置

```yaml
# config/agent_config.yaml
agent:
  log_level: info
  listen_address: 0.0.0.0:9090

system_collector:
  enabled: true

remote_write:
  endpoint: http://your-prometheus:9090/api/v1/write
```

### 完整配置示例

```yaml
# config/agent_config.yaml
agent:
  log_level: info
  listen_address: 0.0.0.0:9090
  metrics_path: /metrics

system_collector:
  enabled: true
  collectors:
    cpu: true
    memory: true
    disk: true
    filesystem: true
    network: true
    load: true
  container_mode: auto

service_scrapers:
  - id: webapp
    url: http://localhost:8080/metrics
    interval_secs: 30
    timeout_secs: 5
    labels:
      service: webapp
      environment: production

otlp:
  enabled: true
  grpc_endpoint: 0.0.0.0:4317
  http_endpoint: 0.0.0.0:4318
  prefix: ai
  labels:
    source: otlp_receiver

ai_collectors:
  enabled: true
  
  openai:
    - name: openai_usage
      enabled: true
      api_key: ${OPENAI_API_KEY}
      scrape_interval_secs: 3600
      labels:
        source: openai
  
  litellm:
    - name: litellm_proxy
      enabled: true
      endpoint: http://localhost:4000
      scrape_interval_secs: 60
      labels:
        source: litellm

cost_tracking:
  enabled: true
  
  budget:
    enabled: true
    daily_limit_usd: 100
    monthly_limit_usd: 2000
    alert_threshold_percent: 80

quality_monitoring:
  enabled: true
  
  rules:
    - name: high_latency
      type: response_time
      threshold: 5000
      severity: warning
      weight: 1.0

plugins:
  - name: http_metrics
    type: http
    enabled: true
    interval_secs: 30
    config:
      url: http://localhost:8080/metrics
    labels:
      source: http_plugin

remote_write:
  endpoints:
    - name: primary
      endpoint: http://prometheus-1:9090/api/v1/write
      priority: 1
    - name: backup
      endpoint: http://prometheus-2:9090/api/v1/write
      priority: 2
  failover:
    enabled: true
  queue_config:
    capacity: 10000
    max_shards: 5
    max_samples_per_send: 1000
    batch_send_deadline_secs: 5
    max_retries: 3
  persistence:
    enabled: true
    data_dir: ./data/persistence
    max_file_size_mb: 100
    retention_hours: 24
```

## 快速开始

### 1. 启动 Prometheus

```bash
# 确保启用 Remote Write 接收器
prometheus --config.file=prometheus.yml --web.enable-remote-write-receiver
```

### 2. 启动 Agent

```bash
./prom-agent config/agent_config.yaml
```

### 3. 验证安装

```bash
# 检查健康状态
curl http://localhost:9090/health

# 查看指标
curl http://localhost:9090/metrics

# 查看配置
curl http://localhost:9090/api/v1/config
```

### 4. 集成 AI 工具

**Claude Code**：
```bash
export CLAUDE_CODE_ENABLE_OTEL=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude-code
```

**OpenAI**：
```yaml
ai_collectors:
  openai:
    - name: openai_usage
      api_key: ${OPENAI_API_KEY}
```

**LiteLLM**：
```yaml
ai_collectors:
  litellm:
    - name: litellm_proxy
      endpoint: http://localhost:4000
```

## API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/readyz` | GET | 就绪检查 |
| `/metrics` | GET | 指标端点 |
| `/api/v1/config` | GET | 获取配置 |
| `/api/v1/control` | GET | 获取控制状态 |
| `/api/v1/endpoints` | GET | 端点列表 |
| `/api/v1/endpoints` | POST | 添加端点 |
| `/api/v1/endpoints/{name}` | DELETE | 删除端点 |
| `/api/v1/collectors` | GET | 采集器列表 |
| `/api/v1/collectors/{name}/enable` | POST | 启用采集器 |
| `/api/v1/collectors/{name}/disable` | POST | 禁用采集器 |
| `/api/v1/costs` | GET | 成本报告 |
| `/api/v1/budget` | GET | 预算状态 |
| `/api/v1/quality/score` | GET | 质量评分 |
| `/api/v1/quality/rules` | GET | 质量规则 |
| `/api/v1/plugins` | GET | 插件列表 |
| `/api/v1/persistence` | GET | 持久化状态 |

## 监控面板

项目提供了预置的 Grafana Dashboard：

1. **AI Observability Dashboard**：全面监控 AI 服务的成本、Token 使用、请求延迟等
2. **Claude Code Dashboard**：专门监控 Claude Code 的开发效率和使用情况

### 导入方法

1. 打开 Grafana UI
2. 导航到 Dashboards → Import
3. 点击 "Upload JSON file"
4. 选择 `dashboards/` 目录下的 JSON 文件
5. 选择 Prometheus 数据源
6. 点击 Import

## 性能测试

### 资源占用

| 指标 | 数值 |
|------|------|
| **平均 CPU 使用率** | < 1% |
| **平均内存使用** | < 30MB |
| **API 响应时间** | < 1ms |
| **样本采集速率** | ~6000 样本/秒 |

### 并发性能

| 并发数 | RPS（请求/秒） | 成功率 |
|--------|----------------|--------|
| 10 | 1525 | 100% |
| 20 | 1623 | 100% |

## 贡献指南

### 开发环境设置

1. **克隆仓库**：
   ```bash
   git clone https://gitee.com/hongbin1/prom-agent.git
   cd prom-agent
   ```

2. **安装依赖**：
   ```bash
   cargo build
   ```

3. **运行测试**：
   ```bash
   cargo test
   ```

4. **运行 Agent**：
   ```bash
   cargo run -- config/agent_config.yaml
   ```

### 代码规范

- 使用 `cargo fmt` 格式化代码
- 使用 `cargo clippy` 检查代码质量
- 提交前运行测试确保代码质量

### 提交 PR

1. 创建分支
2. 实现功能或修复 bug
3. 运行测试
4. 提交 PR

## 故障排查

### 常见问题

1. **Agent 启动失败**
   - 检查配置文件格式
   - 查看日志中的错误信息
   - 验证端口是否被占用

2. **数据推送失败**
   - 检查 Remote Write 配置
   - 验证 Prometheus 是否启用了 Remote Write 接收器
   - 检查网络连接

3. **AI 采集器不工作**
   - 检查 API Key 配置
   - 验证网络连接
   - 查看日志中的错误信息

4. **性能问题**
   - 调整批处理配置
   - 优化网络设置
   - 检查系统资源

### 日志查看

```bash
# 查看 Agent 日志
./prom-agent config/agent_config.yaml --log-level=debug

# 查看 Prometheus 日志
prometheus --log.level=info
```

## 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 联系方式

- **项目地址**：[https://gitee.com/hongbin1/prom-agent](https://gitee.com/hongbin1/prom-agent)
- **问题反馈**：[Issues](https://gitee.com/hongbin1/prom-agent/issues)
- **讨论**：[Discussions](https://gitee.com/hongbin1/prom-agent/discussions)

## 致谢

- [Prometheus](https://prometheus.io/) - 监控系统
- [OpenTelemetry](https://opentelemetry.io/) - 可观测性框架
- [Rust](https://www.rust-lang.org/) - 系统编程语言
- [Tokio](https://tokio.rs/) - 异步运行时

---

**AI Observability Agent** - 为大模型时代打造的专业监控解决方案