跳到主要内容

本产品及文档完善中，如果有什么问题请联系我们：18721583683(同微信)或chaho@qq.com

OpenTelemetry 集成

XAgent 内嵌 OpenTelemetry（OTel）SDK，将主机侧遥测以标准 OTLP 协议导出到可观测后端（OTel Collector、Jaeger、Tempo、Prometheus Remote Write 等）。集成覆盖三大信号中的指标（Metrics）与追踪（Traces），并以资产感知资源属性作为差异化的数据资产标签。

集成定位​

序号维度说明
1三信号指标（主机运行指标）+ 追踪（HTTP 请求 / 采集管道），日志关联为后续扩展
2数据源复用既有的主机性能采集（CPU / 内存 / 磁盘 IO / 网络 / 负载），不重复造采集
3与 Prometheus 关系两者并存：/metrics 保留 Prometheus 抓取，OTLP 作为推送出口，互不冲突
4差异化资源属性携带资产信息（主机名 / IP / 序列号 / 架构 / 操作系统），每条遥测都带资产标签

配置方式​

OTel 出口默认关闭，仅在显式配置端点后启用。未配置时静默降级为 no-op，不影响代理正常运行。

序号环境变量说明示例
1OTEL_EXPORTER_OTLP_ENDPOINTOTLP 后端地址（标准变量）http://127.0.0.1:4318
2XAGENT_OTEL_ENDPOINT同上，自定义别名；两者都设时优先 OTEL_EXPORTER_OTLP_ENDPOINThttp://127.0.0.1:4318
3OTEL_EXPORTER_OTLP_INSECUREhttp:// 明文端点需为 true（XAgent 自动按端点 scheme 判定并设置）true
# 本地测试：OTel Collector 默认 OTLP/HTTP 端口 4318
XAGENT_OTEL_ENDPOINT=http://127.0.0.1:4318 xagent run

# 未设置端点：OTel 不启用，功能不受影响
xagent run

端点自动判定：以 http:// 开头的端点自动启用 insecure（明文），https:// 走 TLS，无需手工处理。

资源属性（资产感知）​

XAgent 将主机资产数据映射为 OTel Resource，随所有 span 与 metric 一起上报。后端收到的每条遥测都自带资产标签，实现"资产感知的可观测性"。

序号资源属性来源示例值
1service.name固定值xagent
2host.name主机名chaho-web-01
3host.id主机 UUID4c4c4544-0059-3510-8044-cac04f385132
4host.ip私网 IP（优先）192.168.28.176
5host.archCPU 架构x86_64
6os.type操作系统类型windows / linux
7os.name操作系统名称ubuntu / windows
8os.version系统版本22.04
9telemetry.sdk.languageSDK 语言go

指标 OTLP 出口​

主机指标经 OTLP 以 semconv（语义约定）标准命名推送，兼容主流可观测后端。采集沿用既有 gopsutil 数据源，PeriodicReader 每 30 秒导出。

序号指标名类型属性说明
1system.cpu.utilizationgaugecpu（编号 / total）每核与总计利用率（0~1）
2system.cpu.load_average.1mgauge—1 分钟负载均值
3system.cpu.load_average.5mgauge—5 分钟负载均值
4system.cpu.load_average.15mgauge—15 分钟负载均值
5system.memory.usagegauge—内存总字节数
6system.memory.usedgauge—已用内存字节数
7system.memory.utilizationgauge—内存利用率（0~1）
8system.disk.iocounterdevice、direction磁盘累计读写字节
9system.network.iocounterdevice、direction网卡累计收发字节
10system.uptimegauge—开机时长（秒）

追踪​

HTTP 请求追踪​

XAgent 为每个 HTTP 请求生成 span，记录方法、路径、状态码与耗时：

序号span 属性说明
1http.request.methodGET / POST 等
2url.path请求路径（如 /inventory、/performance）
3http.response.status_code响应状态码
4http.request.duration_ms请求耗时（毫秒）

采集管道追踪​

性能页（/performance）的每组采集各生成一个子 span，可直接定位采集环节耗时：

HTTP GET /performance
└── performance.collect.accounts
└── performance.collect.cpu
└── performance.collect.process
└── performance.collect.memory
└── performance.collect.service
└── performance.collect.disk
└── performance.collect.logicaldisk
└── performance.collect.network
└── performance.collect.route

排查价值：当页面响应缓慢时，通过火焰图或 span 耗时即可精确看到卡在哪个采集环节（如进程采集、路由表采集），避免盲查。

与 Prometheus 并存​

序号出口用途形态
1/metrics（Prometheus）被 Prometheus Server 拉取，接入 Grafana拉取（scrape）
2OTLP（/v1/metrics、/v1/traces）推送至 OTel Collector / 托管后端推送（push）

两套独立并存、数据源相同。需要接入既有 Prometheus / Grafana 时用 /metrics；需要统一遥测平台、链路追踪或跨系统关联时用 OTLP。

接入 OTel Collector​

# collector.yaml 片段
receivers:
  otlp:
    protocols:
      http:      # 4318
        endpoint: 0.0.0.0:4318
exporters:
  otlp:            # 或 prometheusremotewrite / jaeger / tempo
    endpoint: your-backend:4317
service:
  pipelines:
    traces:   { receivers: [otlp], exporters: [otlp] }
    metrics:  { receivers: [otlp], exporters: [otlp] }

启动 XAgent 时指定端点：

XAGENT_OTEL_ENDPOINT=http://<collector-ip>:4318 xagent run

验证方法​

# 1. 确认端点配置生效（日志出现 exporter 初始化成功，或观察后端收到数据）
XAGENT_OTEL_ENDPOINT=http://127.0.0.1:4318 xagent run

# 2. 请求页面触发 span，等待 batch 导出（约 5 秒）
curl http://127.0.0.1:9090/
curl http://127.0.0.1:9090/performance

# 3. 指标按 30 秒周期导出，观察后端 /v1/metrics 是否出现 system.* 指标
  • 后端应看到：/v1/traces（HTTP 与采集 span）、/v1/metrics（system.cpu.utilization 等）。
  • 每条遥测的资源属性应含 host.name、host.ip、os.type 等资产信息。

注意事项​

序号事项说明
1采样率追踪默认按 10% 采样（TraceIDRatioBased 0.1），控制代理自身开销
2指标间隔指标按 30 秒批量导出，非实时
3端点不可达导出失败不会影响代理正常运行，OTel 后台自动重试
4版本OTel SDK 依赖 Go 模块 xagent 已作为直接依赖引入（v1.24.0）