内部遥测

您可以通过检查任何 OpenTelemetry Collector 实例的内部遥测来检查其运行状况。继续阅读以了解此遥测以及如何配置它来帮助您 监控 和 排查 Collector 的问题。

在 Collector 中激活内部遥测

默认情况下，Collector 以两种方式公开其自身的遥测

• 内部 指标 使用 Prometheus 接口公开，默认端口为 8888。
• 默认情况下，日志 会发送到 stderr。

配置资源属性

Collector 会自动将 service.name、service.version 和 service.instance.id（随机生成）资源属性附加到其内部遥测信号。可以通过将属性值设置为 null 来禁用这些属性（例如 service.name: null）。

如果您想向 Collector 的内部遥测信号（追踪、指标和日志）添加其他资源属性，可以在 service::telemetry::resource 下设置它们。

service:
  telemetry:
    resource:
      attribute_key: 'attribute_value'

配置内部指标

内部指标的 OTLP Exporter

您可以配置 Collector 如何生成和公开内部指标。默认情况下，Collector 会生成关于自身的基本指标，并使用 OpenTelemetry Go 的 Prometheus exporter 进行公开，以便在 http://127.0.0.1:8888/metrics 进行抓取。

Collector 可以通过以下配置将其内部指标推送到 OTLP 后端

service:
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

内部指标的 Prometheus 端点

或者，您也可以根据需要将 Prometheus 端点公开到特定或所有网络接口。对于容器化环境，您可能希望将此端口公开到公共接口。

在 service::telemetry::metrics 下设置 Prometheus 配置

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: '0.0.0.0'
                port: 8888

如果您想为 Prometheus 指标添加额外的标签，可以使用 prometheus::with_resource_constant_labels 添加它们。

prometheus:
  host: '0.0.0.0'
  port: 8888
  with_resource_constant_labels:
    included:
      - label_key

然后在 service::telemetry::resource 中引用这些标签。

resource:
  label_key: label_value

服务地址

service:
  telemetry:
    metrics:
      address: 0.0.0.0:8888

指标详细程度

您可以通过将 level 字段设置为以下值之一来调整 Collector 指标输出的详细程度。

• none：不收集遥测。
• basic：基本服务遥测。
• normal：默认级别，在 basic 的基础上添加标准指示器。
• detailed：最详细的级别，包括维度和视图。

每个详细程度级别代表一个发出特定指标的阈值。有关指标的完整列表，并按级别细分，请参阅 内部指标列表。

指标输出的默认级别是 normal。要使用其他级别，请设置 service::telemetry::metrics::level。

service:
  telemetry:
    metrics:
      level: detailed

指标视图

您可以使用 views 进一步配置 Collector 指标的导出方式。例如，以下配置将名为 otelcol_process_uptime 的指标更新为发出新的名称 process_uptime 和描述。

service:
  telemetry:
    metrics:
      views:
        - selector:
            instrument_name: otelcol_process_uptime
            instrument_type:
          stream:
            name: process_uptime
            description: The amount of time the Collector has been up

您还可以使用 views 更新生成的聚合、属性和基数限制。有关选项的完整列表，请参阅 OpenTelemetry 配置模式 repository 中的示例。

配置内部日志

日志输出位于 stderr。您可以在配置 service::telemetry::logs 中配置日志。 配置选项如下：

您还可以使用 journalctl 在 Linux systemd 系统上查看 Collector 的日志。

• 所有日志
• 仅错误

journalctl | grep otelcol

journalctl | grep otelcol | grep Error

可以使用以下配置将 Collector 的内部日志发送到 OTLP/HTTP 后端。

service:
  telemetry:
    logs:
      processors:
        - batch:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

配置内部追踪

Collector 默认不公开追踪，但可以进行配置。

可以使用以下配置将 Collector 的内部追踪发送到 OTLP 后端。

service:
  telemetry:
    traces:
      processors:
        - batch:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

有关其他选项，请参阅 示例配置。请注意，其中的 tracer_provider 部分对应于这里的 traces。

内部遥测的类型

OpenTelemetry Collector 旨在成为一个可观察的服务的模型，清晰地公开其自身的运行指标。此外，它还收集主机资源指标，这些指标可以帮助您了解问题是否由同一主机上的其他进程引起。Collector 的特定组件也可以发出自己的自定义遥测。在本节中，您将了解 Collector 本身发出的不同类型的可观察性。

通过内部指标可观察值的摘要

Collector 发出内部指标以至少包含以下值

• 进程的正常运行时间和启动以来的 CPU 时间。
• 进程内存和堆使用情况。
• 对于接收器：按数据类型接受和拒绝的项目。
• 对于处理器：传入和传出的项目。
• 对于 Exporter：Exporter 发送、排队失败和发送失败的项目，按数据类型。
• 对于 Exporter：队列大小和容量。
• HTTP/gRPC 请求和响应的计数、持续时间和大小。

更详细的列表可在以下各节中找到。

指标名称

本节解释了应用于某些内部指标的特殊命名约定。

otelcol_ 前缀

自 Collector v0.106.1 起，内部指标名称的处理方式根据其来源有所不同。

• 从 Collector 组件生成的指标以 otelcol_ 作为前缀。
• 从仪器库生成的指标默认不使用 otelcol_ 前缀，除非其指标名称明确添加了前缀。

对于 Collector v0.106.1 之前的版本，所有使用 Prometheus exporter 公开的内部指标，无论其来源如何，都以 otelcol_ 作为前缀。这包括来自 Collector 组件和仪器库的指标。

_total 后缀

默认情况下，并且仅限于 Prometheus，Prometheus exporter 会在求和指标后添加 _total 后缀，以遵循 Prometheus 命名约定，例如 otelcol_exporter_send_failed_spans_total。通过在 Prometheus exporter 的配置中设置 without_type_suffix: false 可以禁用此行为。

如果您在 Collector 配置中省略 service::telemetry::metrics::readers，Collector 设置的默认 Prometheus exporter 已经将 without_type_suffix 设置为 false。但是，如果您自定义了 readers 并手动添加了 Prometheus exporter，则必须设置该选项以返回到“原始”指标名称。有关更多信息，请参阅 Collector v1.25.0/v0.119.0 发布说明。

通过 OTLP 导出的内部指标没有此行为。此页面上的内部指标以 OTLP 格式列出，例如 otelcol_exporter_send_failed_spans。

点 (.) 与下划线 (_)

http* 和 rpc* 指标来自仪器库。它们的原始名称使用点 (.)。在 Collector v0.120.0 之前，使用 Prometheus 公开的内部指标会将点 (.) 更改为下划线 (_) 以匹配 Prometheus 命名约定，从而产生如 rpc_server_duration 这样的指标名称。

Collector 的 0.120.0 及更高版本使用 Prometheus 3.0 scraper，因此保留了原始的带点的 http* 和 rpc* 指标名称。此页面上的内部指标以其原始形式列出，例如 rpc.server.duration。有关更多信息，请参阅 Collector v0.120.0 发布说明。

内部指标列表

下表按详细程度级别（basic、normal 和 detailed）对每个内部指标进行分组。每个指标都通过名称和描述进行标识，并按仪器类型进行分类。

basic 级别指标

额外的 normal 级别指标

额外的 detailed 级别指标

可观察的内部日志事件

Collector 记录以下内部事件：

• Collector 实例启动或停止。
• 由于节流（throttling）而开始丢弃数据，原因包括本地饱和、下游饱和、下游不可用等。
• 由于节流停止丢弃数据。
• 由于数据无效而开始丢弃数据。包含无效数据的样本。
• 由于数据无效停止丢弃数据。
• 检测到崩溃，与正常停止区分。如果可用，将包含崩溃数据。

遥测成熟度级别

Collector 遥测级别适用于 Collector 生成的所有第一方遥测。第三方库，包括 OpenTelemetry Go 的库，不属于这些成熟度级别的覆盖范围。

追踪

追踪仪器化仍在积极开发中，span 名称、附加属性、仪器化端点或其他遥测方面可能会发生变化。在这些功能毕业为稳定之前，不保证追踪仪器化的向后兼容性。

指标

Collector 的第一方指标遵循以下生命周期：

stateDiagram-v2
    state StabilityLevels {
    InDevelopment --> Alpha
    Alpha --> Beta
    Beta --> Stable
    }

    InDevelopment: In Development

    StabilityLevels --> Deprecated
    Deprecated --> Removed

稳定性级别遵循语义约定 指南，该指南源自 OTEP-0232。Collector 指标会跳过 release_candidate 级别。

请注意，已弃用和已删除阶段是生命周期状态，而不是稳定性级别。

第三方指标，包括由 OpenTelemetry Go 仪器库生成的指标，不属于这些成熟度级别的覆盖范围。

开发中

开发中的指标仍在积极开发中，并且可能在任何版本中发生更改。

Alpha

Alpha 指标没有稳定性保证。这些指标可以随时修改或删除。

Beta

Beta 指标在版本之间可能仍会发生变化，但组件所有者应尽量减少破坏性更改。此阶段鼓励更广泛的使用，是进入 stable 的最后一步。

稳定

稳定指标保证不会改变。这意味着：

• 没有已弃用签名的稳定指标不会被删除或重命名。
• 稳定指标的类型和属性不会被修改。

已弃用

已弃用的指标计划删除，但仍可供使用。这些指标的描述包含有关其被弃用的版本的注释。例如：

弃用前

# HELP otelcol_exporter_queue_size this counts things
# TYPE otelcol_exporter_queue_size counter
otelcol_exporter_queue_size 0

弃用后

# HELP otelcol_exporter_queue_size (Deprecated since 1.15.0) this counts things
# TYPE otelcol_exporter_queue_size counter
otelcol_exporter_queue_size 0

已删除

已删除的指标不再发布，无法使用。

日志

单个日志条目及其格式可能因版本而异。目前没有稳定性保证。

使用内部遥测监控 Collector

本节推荐使用 Collector 的自身遥测来监控 Collector 的最佳实践。

监控

队列长度

大多数 Exporter 都提供了一个 队列和/或重试机制，建议在 Collector 的任何生产部署中使用。

otelcol_exporter_queue_capacity 指标指示发送队列的容量（以批次为单位）。otelcol_exporter_queue_size 指标指示发送队列的当前大小。使用这两个指标来检查队列容量是否能支持您的工作负载。

使用以下三个指标，您可以识别未能到达发送队列的 span、指标点和日志记录的数量。

• otelcol_exporter_enqueue_failed_spans
• otelcol_exporter_enqueue_failed_metric_points
• otelcol_exporter_enqueue_failed_log_records

这些失败可能是由于队列已满未处理元素造成的。您可能需要降低发送速率或水平扩展 Collector。

队列或重试机制还支持用于监控的日志。检查日志以获取类似 Dropping data because sending_queue is full 的消息。

接收失败

持续的 otelcol_receiver_refused_log_records、otelcol_receiver_refused_spans 和 otelcol_receiver_refused_metric_points 率表明返回给客户端的错误过多。取决于部署和客户端的弹性，这可能表示客户端数据丢失。

持续的 otelcol_exporter_send_failed_log_records、otelcol_exporter_send_failed_spans 和 otelcol_exporter_send_failed_metric_points 率表明 Collector 无法按预期导出数据。这些指标本身并不意味着数据丢失，因为可能存在重试。但高失败率可能表明网络或接收数据的后端存在问题。

数据流

您可以使用 otelcol_receiver_accepted_log_records、otelcol_receiver_accepted_spans 和 otelcol_receiver_accepted_metric_points 指标来监控数据入站，使用 otelcol_exporter_sent_log_records、otelcol_exporter_sent_spans 和 otelcol_exporter_sent_metric_points 指标来监控数据出站。