telemetryflow/telemetryflow-agent

TelemetryFlow Agent (OTEL Agent)

基于OpenTelemetry Go SDK v1.39.0构建的企业级遥测收集代理。提供全面的系统监控，包括指标收集、心跳监控和OTLP遥测导出，专为TelemetryFlow平台设计。

该代理作为TelemetryFlow后端代理模块（NestJS）的客户端对应组件，提供以下功能：

• 代理注册与生命周期管理
• 心跳与健康监控
• 系统指标收集
• OTLP遥测导出

TelemetryFlow生态系统

TFO-Agent与TelemetryFlow生态系统完全对齐，共享相同的OpenTelemetry SDK版本：

核心功能与特性

OpenTelemetry核心

• OpenTelemetry SDK v1.39.0：基于标准OTEL Go SDK构建（与TFO-Go-SDK对齐）
• OTLP导出：支持指标、日志和追踪的OpenTelemetry协议
• 多信号支持：指标、日志和追踪收集

代理生命周期（后端集成）

• 代理注册：自动向TelemetryFlow后端注册
• 心跳监控：定期向后端发送健康检查
• 健康状态同步：报告代理健康状况和系统信息
• 激活/停用：通过后端远程控制代理

系统监控

• 系统指标收集：CPU、内存、磁盘和网络指标
• 进程监控：跟踪运行中的进程
• 资源检测：自动检测主机、操作系统和容器信息

可靠性

• 磁盘备份缓冲区：针对离线场景的弹性重试缓冲区
• 自动重连：带指数退避的自动重试机制
• 优雅关闭：信号处理（SIGINT、SIGTERM、SIGHUP）

平台支持

• 跨平台：支持Linux、macOS和Windows
• LEGO构建块：模块化架构，便于扩展

使用场景与适用范围

• 企业级系统监控与遥测数据收集
• 与TelemetryFlow平台集成的客户端遥测采集
• 需要可靠OTLP数据导出的分布式系统
• 跨平台环境的统一监控需求

使用方法与配置说明

快速开始

使用Docker Compose（推荐）

bash
# 复制环境变量模板
cp .env.example .env

# 编辑.env配置
vim .env

# 构建并启动
docker-compose up -d --build

# 查看日志
docker-compose logs -f tfo-agent

# 停止服务
docker-compose down

直接使用Docker

bash
# 构建镜像
docker build \
  --build-arg VERSION=1.1.1 \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  --build-arg GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD) \
  --build-arg BUILD_TIME=$(date -u '+%Y-%m-%dT%H:%M:%SZ') \
  -t telemetryflow/telemetryflow-agent:1.1.1 .

# 运行容器
docker run -d --name tfo-agent \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8888:8888 \
  -p 13133:13133 \
  -v /path/to/config.yaml:/etc/tfo-agent/tfo-agent.yaml:ro \
  -v /var/lib/tfo-agent:/var/lib/tfo-agent \
  telemetryflow/telemetryflow-agent:1.1.1

配置文件

在/etc/tfo-agent/tfo-agent.yaml创建配置文件：

yaml
# TelemetryFlow平台配置 (v1.1.1+)
telemetryflow:
  api_key_id: "${TELEMETRYFLOW_API_KEY_ID}"
  api_key_secret: "${TELEMETRYFLOW_API_KEY_SECRET}"
  endpoint: "${TELEMETRYFLOW_ENDPOINT:-localhost:4317}"
  protocol: grpc  # grpc或http
  tls:
    enabled: true
    skip_verify: false
  retry:
    enabled: true
    max_attempts: 3
    initial_interval: 1s
    max_interval: 30s

agent:
  name: "TelemetryFlow Agent"
  hostname: ""  # 留空则自动检测
  tags:
    environment: production

heartbeat:
  interval: 60s
  timeout: 10s

collector:
  system:
    enabled: true
    interval: 15s
    cpu: true
    memory: true
    disk: true
    network: true

exporter:
  otlp:
    enabled: true
    batch_size: 100
    flush_interval: 10s
    compression: gzip

buffer:
  enabled: true
  path: "/var/lib/tfo-agent/buffer"
  max_size_mb: 100

环境变量

bash
# TelemetryFlow平台 (v1.1.1+)
export TELEMETRYFLOW_ENDPOINT="localhost:4317"
export TELEMETRYFLOW_API_KEY_ID="tfk_your_key_id"
export TELEMETRYFLOW_API_KEY_SECRET="tfs_your_key_secret"
export TELEMETRYFLOW_ENVIRONMENT="production"

# 代理配置
export TELEMETRYFLOW_AGENT_ID="your-agent-id"
export TELEMETRYFLOW_AGENT_NAME="my-agent"

# 日志
export TELEMETRYFLOW_LOG_LEVEL="info"

CLI命令使用

bash
# 启动代理
tfo-agent start

# 使用自定义配置启动
tfo-agent start --config /path/to/config.yaml

# 验证配置
tfo-agent config validate

# 显示版本
tfo-agent version

收集的指标

系统服务配置

ini
# /etc/systemd/system/tfo-agent.service
[Unit]
Description=TelemetryFlow Agent - CEOP
After=network.target

[Service]
Type=simple
User=telemetryflow
ExecStart=/usr/local/bin/tfo-agent start --config /etc/tfo-agent/tfo-agent.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

bash
sudo systemctl daemon-reload
sudo systemctl enable tfo-agent
sudo systemctl start tfo-agent

开发构建命令

bash
# 显示所有命令
make help

# 构建命令
make                # 构建代理（默认）
make build          # 为当前平台构建代理
make build-all      # 为所有平台构建代理
make build-linux    # 为Linux构建（amd64和arm64）
make build-darwin   # 为macOS构建（amd64和arm64）

# 开发命令
make run            # 构建并运行代理
make dev            # 使用go run运行（开发更快速）
make test           # 运行测试
make test-coverage  # 运行测试并生成覆盖率报告
make lint           # 运行代码检查
make fmt            # 格式化代码
make vet            # 运行go vet

# 依赖管理
make deps           # 下载依赖
make deps-update    # 更新依赖
make tidy           # 整理go模块

# 其他命令
make clean          # 清理构建产物
make install        # 安装二进制到/usr/local/bin
make uninstall      # 卸载二进制
make docker-build   # 构建Docker镜像
make docker-push    # 推送Docker镜像
make version        # 显示版本信息

许可证

Apache License 2.0 - 详见 LICENSE

链接

• 网站: [***]
• 文档: [***]
• OpenTelemetry: [***]
• 开发者: DevOpsCorner Indonesia

版权所有 (c) 2024-2026 DevOpsCorner Indonesia。保留所有权利。