集成 OpenTelemetry 进行日志管理

与基于文件的日志一样，OpenTelemetry 日志同样用于记录关键事件、状态信息和错误消息，帮助开发人员和运维团队理解应用程序的行为和故障排查。不同的是，OpenTelemetry 日志使用了规范化的日志记录格式，使得日志更易于解析、分析和处理。除此之外， OpenTelemetry 日志还支持在记录中添加丰富的上下文信息，如 Trace ID、标签、属性等。

本页面提供了一个全面的指南，介绍了如何将 OpenTelemetry 与 EMQX 集成，以实现高级日志管理。内容涵盖了设置 OpenTelemetry Collector、在 EMQX 中启用 OpenTelemetry 日志处理进程导出日志，以及管理潜在的日志过载。与 OpenTelemetry 的集成允许您根据 OpenTelemetry 日志数据模型 格式化 EMQX 日志事件，并将它们导出到配置的 OpenTelemetry Collector 或后端系统，提高了对 EMQX 的监控和调试能力。

配置 OpenTelemetry Collector

在启用 EMQX OpenTelemetry 日志处理进程之前，你需要部署和配置 OpenTelemetry Collector 以及一些兼容的日志收集系统。以下步骤将引导您部署 OpenTelemetry Collector 并将其设置使用调试导出器将日志重定向到 stdout。

1. 创建名为 otel-logs-collector-config.yaml 的 OpenTelemetry Collector 配置文件：

   receivers:
     otlp:
       protocols:
         grpc:
   
   exporters:
     logging:
       verbosity: detailed
   
   processors:
     batch:
   
   extensions:
     health_check:
   
   service:
     extensions: [health_check]
     pipelines:
       logs:
         receivers: [otlp]
         processors: [batch]
         exporters: [logging]

2. 在同一目录下创建一个 Docker Compose 文件 docker-compose-otel-logs.yaml：

   version: '3.9'
   
   services:
     # Collector
     otel-collector:
       image: otel/opentelemetry-collector:0.90.0
       restart: always
       command: ["--config=/etc/otel-collector-config.yaml", "${OTELCOL_ARGS}"]
       volumes:
         - ./otel-logs-collector-config.yaml:/etc/otel-collector-config.yaml
       ports:
         - "13133:13133" # 健康检查扩展
         - "4317:4317"   # OTLP gRPC 接收器

3. 使用 Docker Compose 启动 Collector：

   docker compose -f docker-compose-otel-logs.yaml up

4. 一旦运行，OpenTelemetry Collector 应该在 http://localhost:4317 上可访问。

在 EMQX 中启用 OpenTelemetry 日志处理进程

1. 将以下配置添加到 EMQX cluster.hocon 文件中（假设 EMQX 在本地机器上运行）：

   opentelemetry {
     exporter {endpoint = "http://localhost:4317"}
     logs {enable = true, level = warning}
   }

   您也可以在 Dashboard 管理 -> 监控 页面下的 监控集成 选项卡中配置 OpenTelemetry 日志集成。

   提示

   opentelemetry.logs.level 设置将被默认配置在 EMQX 日志处理进程 中的日志级别覆盖。例如，如果 OpenTelemetry 日志级别为 info 但 EMQX 控制台日志级别为 error，则只有 error 级别或更高级别的事件才会被导出。

2. 启动 EMQX 节点。

3. 生成 EMQX 日志事件，例如通过 Dashboard 创建一个无法访问的 HTTP 服务动作：

   

4. 短时间后（默认约 1 秒），Otel Collector 应该显示接收到的 EMQX 日志事件，例如指示 HTTP 动作连接失败的事件：

   

管理日志过载

EMQX 会定期批量累积并导出日志事件。这种导出的频率由 opentelemetry.logs.scheduled_delay 参数控制，默认为 1 秒。 批处理日志处理进程包含一种过载保护机制，只允许累积事件直到特定限制，默认为 2048。你可以使用以下配置来设置这个限制：

opentelemetry {
  logs { max_queue_size = 2048 }
}

一旦达到 max_queue_size 限制，新的日志事件将被丢弃，直到当前队列被导出。

提示

OpenTelemetry 日志过载保护独立于默认的 EMQX 日志处理进程 过载保护。 因此，根据配置，相同的日志事件可能会被 OpenTelemetry 处理进程丢弃，但被默认的 EMQX 日志处理进程记录，反之亦然。