18、OpenTelemetry Collector 入门与实践

OpenTelemetry Collector 入门与实践

1. OpenTelemetry Collector 基础组件

OpenTelemetry Collector 的导出器支持多种格式，以下是可用的导出器及其支持的信号：
| 导出器 | 支持的信号 |
| — | — |
| … | … |

除了将不同信号的数据导出到可通过网络访问的目标外，还可以通过日志导出器将遥测数据本地导出到控制台，或通过文件导出器以 JSON 格式导出到文件。收集器的管道包含接收器、处理器和导出器这些组件，此外还有扩展功能。目前可用的扩展如下：
- ballast ：允许用户为收集器配置内存压舱物，以提高收集器的整体稳定性和性能。
- health_check ：提供一个端点用于检查收集器的健康状况，对服务发现或收集器编排很有用。
- pprof ：启用 Go 性能分析器，用于识别收集器内的性能问题。
- zpages ：在收集器中启用一个端点，提供有关收集器组件的调试信息。

2. 额外组件与 OTLP 协议

核心收集器发行版包含的组件是我们后续示例中二进制文件的一部分，但还有很多其他可用组件。为降低收集器核心功能的复杂性，主收集器仓库包含符合 OpenTelemetry 规范定义的组件。同时，许多个人和组织在 opentelemetry-collector-contrib 仓库（https://github.com/open-telemetry/opentelemetry-collector-contrib）贡献了额外的接收器、处理器和导出器。

在学习如何使用收集器并配置应用程序向其发送数据之前，需要了解用于接收和导出数据的首选协议 OTLP。OpenTelemetry 定义 OTLP 是为了确保遥测数据能尽可能高效可靠地传输，该协议通过协议缓冲区（https://developers.google.com/protocol-buffers）定义文件来定义。任何想发送或接收 OTLP 的客户端或服务器只需实现这些定义即可支持该协议。OTLP 是 OpenTelemetry 推荐的传输遥测数据的协议，也是收集器的核心组件。

OTLP 的定义（https://github.com/open-telemetry/opentelemetry-proto）分为多个部分以涵盖不同信号，每个组件通过其成熟度级别保证向后兼容性。例如，alpha 级别不保证无重大变更，而稳定级别保证每 12 个月最多引入一次向后不兼容的变更。各组件的成熟度级别可在项目的 README.md 文件中查看。

3. OTLP 的编码与协议

OTLP 规范定义了支持的编码和协议，最初支持以下三种组合：
- protobufs over gRPC
- protobufs over HTTP
- JSON over HTTP

选择编码或协议时，需考虑应用程序或部署代码的基础设施的要求。例如，某些环境可能不支持 gRPC，像一些云提供商的无服务器 Python 环境长期不支持 gRPC，浏览器也不支持 gRPC，这使得 JavaScript 的 OpenTelemetry 用户在为浏览器应用程序进行检测时无法使用 gRPC。此外，使用 JSON 序列化和反序列化数据可能会对某些语言的性能产生严重影响，与使用 protobufs 相比存在性能差异。这些不同的编码和协议组合为用户提供了更多灵活性，以适应不同的环境要求。

任何 OpenTelemetry 语言实现的要求之一是在将信号标记为通用可用之前支持至少一种这些格式，以确保用户可以使用 OTLP 在整个系统中从应用程序检测到后端导出数据。OTLP 协议还考虑了背压问题，定义了客户端在接收系统过载时应如何处理服务器响应以管理背压，并且该协议设计为对负载均衡器友好，以便可以水平扩展处理遥测数据的各个组件。

4. 使用 OpenTelemetry Collector

在熟悉了 OpenTelemetry Collector 和 OTLP 的核心组件后，我们可以开始在杂货店场景中使用收集器。首先，通过 opentelemetry-exporter-otlp 包为 Python 安装 OTLP 导出器，该包会安装每个协议和编码可用的包：
- opentelemetry-exporter-otlp-proto-grpc
- opentelemetry-exporter-otlp-proto-http
- opentelemetry-exporter-otlp-json-http

4.1 配置导出器

以下示例使用 otlp-proto-grpc 包，其中包含用于导出遥测数据的导出器类： OTLPSpanExporter 、 OTLPMetricExporter 和 OTLPLogExporter 。通过更新 common.py 模块来使用这些 OTLP 导出器，示例代码如下：

# common.py
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc._metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter

def configure_tracer(name, version):
    ...
    exporter = OTLPSpanExporter()
    ...

def configure_meter(name, version):
    ...
    exporter = OTLPMetricExporter()
    ...

def configure_logger(name, version):
    ...
    exporter = OTLPLogExporter()
    ...

默认情况下，根据规范，导出器将配置为将数据发送到运行在 localhost:4317 的收集器。

4.2 配置收集器

以下收集器配置设置了 otlp 接收器以接收应用程序的遥测数据，并配置了日志导出器将有用信息输出到控制台：

# config/collector/config.yml
receivers:
  otlp:
    protocols:
      grpc:
exporters:
  logging:
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [logging]
    metrics:
      receivers: [otlp]
      exporters: [logging]
    logs:
      receivers: [otlp]
      exporters: [logging]

每次更新 config.yml 后，需要重启收集器以使更改生效。使用以下命令从终端启动收集器：

./otelcol --config ./config/collector/config.yml

如果一切正常，收集器进程将启动并列出已加载的组件，输出中应包含类似以下的消息：

2021-05-30T16:19:03.088-0700 info service/application.go:197 Everything is ready. Begin running and processing data.

在另一个终端中运行应用程序代码，依次启动 legacy_inventory.py 、 grocery_store.py 和 shopper.py ：

python legacy_inventory.py
python grocery_store.py
python shopper.py

关注运行收集器的终端输出，应能看到描述收集器处理的跟踪、指标和日志的信息，示例输出如下：

2022-02-13T14:35:47.101-0800    INFO    loggingexporter/logging_exporter.go:69  LogsExporter      {"#logs": 1}
2022-02-13T14:35:47.110-0800    INFO    loggingexporter/logging_exporter.go:40  TracesExporter    {"#spans": 4}
2022-02-13T14:35:49.858-0800    INFO    loggingexporter/logging_exporter.go:40  TracesExporter    {"#spans": 1}
2022-02-13T14:35:50.533-0800    INFO    loggingexporter/logging_exporter.go:40  TracesExporter    {"#spans": 3}
2022-02-13T14:35:50.535-0800    INFO    loggingexporter/logging_exporter.go:69  LogsExporter      {"#logs": 2}

5. 添加处理器优化收集器

观察上述输出，会发现 TracesExporter 多次被调用。可以使用批处理器来提高效率，它会等待一段时间，然后一次性发送包含所有遥测数据的单个批次。以下代码配置了一个超时时间为 10 秒的批处理器，并将其添加到每个管道中：

# config/collector/config.yml
processors:
  batch:
    timeout: 10s
...
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

再次运行 shopper.py ，收集器的输出应显示包含之前所有跨度总和的单行信息：

2022-02-13T14:40:07.360-0800    INFO    loggingexporter/logging_exporter.go:69  LogsExporter    {"#logs": 2}
2022-02-13T14:40:07.360-0800    INFO    loggingexporter/logging_exporter.go:40  TracesExporter  {"#spans": 8}

多次运行 shopper.py 会发现收集器输出遥测数据信息有 10 秒的延迟，这就是批处理器在起作用。为了使日志输出更有用，可以更新日志导出器配置：

# config/collector/config.yml
exporters:
  logging:
    loglevel: debug

重启收集器并再次运行 shopper.py ，将输出接收到的完整遥测数据，可关注名为 add item to cart 的跨度，后续会对其进行修改。示例输出如下：

Span #0
    Trace ID       : 1592a37b7513b73eaefabde700f4ae9b
    Parent ID      : 2411c263df768eb5
    ID             : 8e6f5cdb56d6448d
    Name           : HTTP GET
    Kind           : SPAN_KIND_SERVER
    Start time     : 2022-02-13 22:41:42.673298 +0000 UTC
    End time       : 2022-02-13 22:41:42.677336 +0000 UTC
    Status code    : STATUS_CODE_UNSET
    Status message :
Attributes:
     -> http.method: STRING(GET)
     -> http.server_name: STRING(127.0.0.1)
     -> http.scheme: STRING(http)
     -> net.host.port: INT(5000)
     -> http.host: STRING(localhost:5000)
     -> http.target: STRING(/products)
     -> net.peer.ip: STRING(127.0.0.1)

6. 修改跨度与过滤指标

收集器的一个强大功能是能够从中央位置处理遥测数据。以下示例使用两个不同的处理器来增强之前提到的跨度。首先， attributes 处理器会添加一个 location 属性，然后 span 处理器会使用跨度的属性重命名跨度，使其包含 location 、 item 和 quantity 属性。新处理器必须添加到跟踪管道的处理器数组中：

# config/collector/config.yml
processors:
  attributes/add-location:
    actions:
      - key: location
        action: insert
        value: europe
  span/rename:
    name:
      from_attributes: [location, item, quantity]
      separator: ":"
...
  pipelines:
    traces:
      processors: [batch, attributes/add-location, span/rename]

注意处理器的顺序很重要，在这个例子中，顺序颠倒将无法正常工作，因为 location 属性将不会被填充。运行 shopper.py 并查看收集器的输出，新导出的跨度将包含配置的 europe 值的 location 属性，其名称也会更新为 location:item:quantity ：

Span #1
    Trace ID       : 47dac26efa8de0ca1e202b6d64fd319c
    Parent ID      : ee10984575037d4a
    ID             : a4f42124645c4d3b
    Name           : europe:orange:5
    Kind           : SPAN_KIND_INTERNAL
    Start time     : 2022-02-13 22:44:57.072143 +0000 UTC
    End time       : 2022-02-13 22:44:57.07751 +0000 UTC
    Status code    : STATUS_CODE_UNSET
    Status message :
Attributes:
     -> item: STRING(orange)
     -> quantity: INT(5)
     -> location: STRING(europe)

接下来，我们看看如何处理指标。 hostmetrics 接收器可以捕获本地主机的指标。以下示例配置 hostmetrics 接收器每 10 秒收集一次内存和网络信息：

# config/collector/config.yml
receivers:
  hostmetrics:
    collection_intervals: 10s
    scrapers:
      memory:
      network:
...
service:
  pipelines:
    metrics:
      receivers: [otlp, hostmetrics]

配置此接收器后，重启收集器，无需运行 shopper.py 即可在收集器输出中看到指标，输出将包括内存和网络指标，示例如下：

InstrumentationLibraryMetrics #0
InstrumentationLibrary
Metric #0
Descriptor:
     -> Name: system.memory.usage
     -> Description: Bytes of memory in use.
     -> Unit: By
     -> DataType: IntSum
     -> IsMonotonic: false
     -> AggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE
IntDataPoints #0
Data point labels:
     -> state: used
StartTimestamp: 1970-01-01 00:00:00 +0000 UTC
Timestamp: 2022-02-13 22:48:16.999087 +0000 UTC
Value: 10880851968
Metric #1
Descriptor:
     -> Name: system.network.packets
     -> Description: The number of packets transferred.
     -> Unit: {packets}
     -> DataType: IntSum
     -> IsMonotonic: true
     -> AggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE
IntDataPoints #0
Data point labels:
     -> device: lo0
     -> direction: transmit
StartTimestamp: 1970-01-01 00:00:00 +0000 UTC
Timestamp: 2022-02-13 22:48:16.999087 +0000 UTC
Value: 120456

根据运行收集器的系统类型，可能有多个网络接口会生成大量指标。为减少噪声，可以更新配置以仅收集单个接口的指标，例如使用 lo0 接口：

# config/collector/config.yml
receivers:
  hostmetrics:
    collection_intervals: 10s
    scrapers:
      memory:
      network:
        include:
          match_type: strict
          interfaces: [lo0]

注意网络接口名称因操作系统而异，常见的接口名称有 lo0 、 eth0 、 en0 和 wlan0 。如果不确定，可以查看之前输出中的 device 标签以了解系统上可用的接口。

尽管输出会显著减少，但仍有许多网络指标需要筛选。 system.network.connections 指标会为每个 TCP 状态收集数据点，比较嘈杂。可以使用 filter 处理器排除该指标：

# config/collector/config.yml
processors:
  filter/network-connections:
    metrics:
      exclude:
        match_type: strict
        metric_names:
          - system.network.connections
...
  pipelines:
    metrics:
      receivers: [hostmetrics]
      processors: [batch, filter/network-connections]

最后一次重启收集器，输出将更易于阅读。通过这些操作，我们对 OpenTelemetry Collector 有了更深入的了解，可以通过尝试不同的配置和处理器来进一步熟悉它。

综上所述，我们学习了 OpenTelemetry Collector 的基础知识和组件，了解了接收器、处理器、导出器和扩展的作用，掌握了 OTLP 协议的定义、优点和设计决策。通过配置收集器并使用各种处理器处理收集到的数据，我们能够更好地利用收集器的强大功能。后续可以进一步探索如何在各种场景中部署收集器，使其成为基础设施的核心组件。

OpenTelemetry Collector 入门与实践

7. 总结与展望

通过前面的学习和实践，我们已经对 OpenTelemetry Collector 有了较为全面的认识。下面对所学内容进行总结：
- 组件功能 ：了解了接收器、处理器、导出器和扩展在收集器中的作用。接收器负责接收遥测数据，处理器对数据进行处理和转换，导出器将处理后的数据发送到目标位置，扩展则提供了额外的功能，如内存压舱物配置、健康检查、性能分析和调试信息提供等。
- OTLP 协议 ：掌握了 OTLP 协议的定义、编码和协议组合，以及其在数据传输中的优势和设计考虑。OTLP 协议通过不同的编码和协议组合为用户提供了灵活性，同时考虑了背压管理和负载均衡器友好性。
- 配置与操作 ：学会了如何配置导出器和收集器，以及如何使用处理器优化数据处理和输出。通过具体的配置示例，我们展示了如何添加批处理器、修改跨度和过滤指标，从而更好地管理和利用遥测数据。

为了更清晰地展示整个流程，下面是一个 mermaid 格式的流程图：

graph LR
    classDef startend fill:#F5EBFF,stroke:#BE8FED,stroke-width:2px;
    classDef process fill:#E5F6FF,stroke:#73A6FF,stroke-width:2px;
    classDef decision fill:#FFF6CC,stroke:#FFBC52,stroke-width:2px;

    A([开始]):::startend --> B(安装 OTLP 导出器):::process
    B --> C(配置导出器):::process
    C --> D(配置收集器):::process
    D --> E(启动收集器):::process
    E --> F(运行应用程序):::process
    F --> G{数据处理与优化}:::decision
    G -->|添加批处理器| H(配置批处理器):::process
    G -->|修改跨度| I(配置跨度处理器):::process
    G -->|过滤指标| J(配置过滤处理器):::process
    H --> K(查看优化后输出):::process
    I --> K
    J --> K
    K --> L([结束]):::startend

未来，我们可以进一步探索如何将 OpenTelemetry Collector 从开发环境中的组件转变为基础设施的核心组件。以下是一些可以深入研究的方向：
- 多环境部署 ：探索如何在不同的环境中部署收集器，如容器化环境（如 Docker 和 Kubernetes）、云环境等，以充分发挥收集器的优势。
- 与其他工具集成 ：研究如何将 OpenTelemetry Collector 与其他监控和分析工具集成，如 Prometheus、Grafana 等，以实现更全面的监控和分析功能。
- 自定义处理器开发 ：尝试开发自定义的处理器，以满足特定的业务需求，如数据加密、数据脱敏等。

8. 常见问题解答

在使用 OpenTelemetry Collector 的过程中，可能会遇到一些常见问题，下面为大家解答：
- 问题 1：更新配置文件后，收集器没有生效怎么办？
- 解答 ：每次更新 config.yml 文件后，必须重启收集器，使用命令 ./otelcol --config ./config/collector/config.yml 重新启动收集器，使更改生效。
- 问题 2：如何确定系统上可用的网络接口名称？
- 解答 ：可以查看收集器输出中的 device 标签，它会显示系统上可用的一些接口。常见的接口名称有 lo0 、 eth0 、 en0 和 wlan0 ，但具体名称因操作系统而异。
- 问题 3：处理器的顺序对结果有影响吗？
- 解答 ：处理器的顺序非常重要。例如，在修改跨度的示例中，如果 attributes/add-location 和 span/rename 处理器的顺序颠倒， span/rename 处理器将无法获取到 location 属性，导致无法正确重命名跨度。

9. 最佳实践建议

为了更好地使用 OpenTelemetry Collector，以下是一些最佳实践建议：
- 合理选择编码和协议 ：根据应用程序和部署环境的要求，选择合适的编码和协议组合。如果环境支持 gRPC，优先考虑 protobufs over gRPC ，因为它通常具有更好的性能；如果环境不支持 gRPC，可以选择 protobufs over HTTP 或 JSON over HTTP 。
- 使用批处理器 ：在处理大量遥测数据时，使用批处理器可以提高效率，减少网络开销。合理设置批处理器的超时时间，以平衡数据处理的实时性和效率。
- 定期检查和优化配置 ：随着业务的发展和环境的变化，定期检查和优化收集器的配置，确保其能够高效地处理和传输遥测数据。例如，根据实际情况调整接收器、处理器和导出器的配置，以满足不同的需求。

10. 总结

OpenTelemetry Collector 是一个强大的工具，它为我们提供了一种有效的方式来收集、处理和传输遥测数据。通过本文的学习，我们了解了收集器的核心组件、OTLP 协议的特点和优势，以及如何配置和使用收集器来处理遥测数据。同时，我们还通过具体的示例展示了如何使用处理器优化数据处理和输出，以及如何解决常见问题和遵循最佳实践。

希望大家能够通过不断的实践和探索，更好地掌握 OpenTelemetry Collector 的使用，将其应用到实际项目中，为系统的监控和分析提供有力支持。未来，随着技术的不断发展，OpenTelemetry Collector 也将不断完善和扩展，为我们带来更多的便利和价值。