Extensions - Red Hat build of OpenTelemetry | Observability

BearerTokenAuth Extension
OAuth2Client Extension
File Storage Extension
OIDC Auth Extension
Jaeger Remote Sampling Extension
Performance Profiler Extension
Health Check Extension
Memory Ballast Extension
zPages Extension
Additional resources

Extensions add capabilities to the Collector. For example, authentication can be added to the receivers and exporters automatically.

BearerTokenAuth Extension

The BearerTokenAuth Extension is an authenticator for receivers and exporters that are based on the HTTP and the gRPC protocol. You can use the OpenTelemetry Collector custom resource to configure client authentication and server authentication for the BearerTokenAuth Extension on the receiver and exporter side. This extension supports traces, metrics, and logs.

The BearerTokenAuth Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with client and server authentication configured for the BearerTokenAuth Extension

# ...
  config: |
    extensions:
      bearertokenauth:
        scheme: "Bearer" (1)
        token: "<token>" (2)
        filename: "<token_file>" (3)

    receivers:
      otlp:
        protocols:
          http:
            auth:
              authenticator: bearertokenauth (4)
    exporters:
      otlp:
        auth:
          authenticator: bearertokenauth (5)

    service:
      extensions: [bearertokenauth]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	You can configure the BearerTokenAuth Extension to send a custom `scheme`. The default is `Bearer`.
2	You can add the BearerTokenAuth Extension token as metadata to identify a message.
3	Path to a file that contains an authorization token that is transmitted with every message.
4	You can assign the authenticator configuration to an OTLP Receiver.
5	You can assign the authenticator configuration to an OTLP Exporter.

OAuth2Client Extension

The OAuth2Client Extension is an authenticator for exporters that are based on the HTTP and the gRPC protocol. Client authentication for the OAuth2Client Extension is configured in a separate section in the OpenTelemetry Collector custom resource. This extension supports traces, metrics, and logs.

The OAuth2Client Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with client authentication configured for the OAuth2Client Extension

# ...
  config: |
    extensions:
      oauth2client:
        client_id: <client_id> (1)
        client_secret: <client_secret> (2)
        endpoint_params: (3)
          audience: <audience>
        token_url: https://example.com/oauth2/default/v1/token (4)
        scopes: ["api.metrics"] (5)
        # tls settings for the token client
        tls: (6)
          insecure: true (7)
          ca_file: /var/lib/mycert.pem (8)
          cert_file: <cert_file> (9)
          key_file: <key_file> (10)
        timeout: 2s (11)

    receivers:
      otlp:
        protocols:
          http: {}

    exporters:
      otlp:
        auth:
          authenticator: oauth2client (12)

    service:
      extensions: [oauth2client]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	Client identifier, which is provided by the identity provider.
2	Confidential key used to authenticate the client to the identity provider.
3	Further metadata, in the key-value pair format, which is transferred during authentication. For example, `audience` specifies the intended audience for the access token, indicating the recipient of the token.
4	The URL of the OAuth2 token endpoint, where the Collector requests access tokens.
5	The scopes define the specific permissions or access levels requested by the client.
6	The Transport Layer Security (TLS) settings for the token client, which is used to establish a secure connection when requesting tokens.
7	When set to `true`, configures the Collector to use an insecure or non-verified TLS connection to call the configured token endpoint.
8	The path to a Certificate Authority (CA) file that is used to verify the server’s certificate during the TLS handshake.
9	The path to the client certificate file that the client must use to authenticate itself to the OAuth2 server if required.
10	The path to the client’s private key file that is used with the client certificate if needed for authentication.
11	Sets a timeout for the token client’s request.
12	You can assign the authenticator configuration to an OTLP exporter.

File Storage Extension

The File Storage Extension supports traces, metrics, and logs. This extension can persist the state to the local file system. This extension persists the sending queue for the OpenTelemetry Protocol (OTLP) exporters that are based on the HTTP and the gRPC protocols. This extension requires the read and write access to a directory. This extension can use a default directory, but the default directory must already exist.

The File Storage Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with a configured File Storage Extension that persists an OTLP sending queue

# ...
  config: |
    extensions:
      file_storage/all_settings:
        directory: /var/lib/otelcol/mydir (1)
        timeout: 1s (2)
        compaction:
          on_start: true (3)
          directory: /tmp/ (4)
          max_transaction_size: 65_536 (5)
        fsync: false (6)

    exporters:
      otlp:
        sending_queue:
          storage: file_storage/all_settings (7)

    service:
      extensions: [file_storage/all_settings] (8)
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	Specifies the directory in which the telemetry data is stored.
2	Specifies the timeout time interval for opening the stored files.
3	Starts compaction when the Collector starts. If omitted, the default is `false`.
4	Specifies the directory in which the compactor stores the telemetry data.
5	Defines the maximum size of the compaction transaction. To ignore the transaction size, set to zero. If omitted, the default is `65536` bytes.
6	When set, forces the database to perform an `fsync` call after each write operation. This helps to ensure database integrity if there is an interruption to the database process, but at the cost of performance.
7	Buffers the OTLP Exporter data on the local file system.
8	Starts the File Storage Extension by the Collector.

OIDC Auth Extension

The OIDC Auth Extension authenticates incoming requests to receivers by using the OpenID Connect (OIDC) protocol. It validates the ID token in the authorization header against the issuer and updates the authentication context of the incoming request.

The OIDC Auth Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with the configured OIDC Auth Extension

# ...
  config: |
    extensions:
      oidc:
        attribute: authorization (1)
        issuer_url: https://example.com/auth/realms/opentelemetry (2)
        issuer_ca_path: /var/run/tls/issuer.pem (3)
        audience: otel-collector (4)
        username_claim: email (5)
    receivers:
      otlp:
        protocols:
          grpc:
            auth:
              authenticator: oidc
    exporters:
      otlp:
        endpoint: <endpoint>
    service:
      extensions: [oidc]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	The name of the header that contains the ID token. The default name is `authorization`.
2	The base URL of the OIDC provider.
3	Optional: The path to the issuer’s CA certificate.
4	The audience for the token.
5	The name of the claim that contains the username. The default name is `sub`.

Jaeger Remote Sampling Extension

The Jaeger Remote Sampling Extension enables serving sampling strategies after Jaeger’s remote sampling API. You can configure this extension to proxy requests to a backing remote sampling server such as a Jaeger collector down the pipeline or to a static JSON file from the local file system.

The Jaeger Remote Sampling Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with a configured Jaeger Remote Sampling Extension

# ...
  config: |
    extensions:
      jaegerremotesampling:
        source:
          reload_interval: 30s (1)
          remote:
            endpoint: jaeger-collector:14250 (2)
          file: /etc/otelcol/sampling_strategies.json (3)

    receivers:
      otlp:
        protocols:
          http: {}

    exporters:
      otlp:

    service:
      extensions: [jaegerremotesampling]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	The time interval at which the sampling configuration is updated.
2	The endpoint for reaching the Jaeger remote sampling strategy provider.
3	The path to a local file that contains a sampling strategy configuration in the JSON format.

Example of a Jaeger Remote Sampling strategy file

{
  "service_strategies": [
    {
      "service": "foo",
      "type": "probabilistic",
      "param": 0.8,
      "operation_strategies": [
        {
          "operation": "op1",
          "type": "probabilistic",
          "param": 0.2
        },
        {
          "operation": "op2",
          "type": "probabilistic",
          "param": 0.4
        }
      ]
    },
    {
      "service": "bar",
      "type": "ratelimiting",
      "param": 5
    }
  ],
  "default_strategy": {
    "type": "probabilistic",
    "param": 0.5,
    "operation_strategies": [
      {
        "operation": "/health",
        "type": "probabilistic",
        "param": 0.0
      },
      {
        "operation": "/metrics",
        "type": "probabilistic",
        "param": 0.0
      }
    ]
  }
}

Performance Profiler Extension

The Performance Profiler Extension enables the Go net/http/pprof endpoint. Developers use this extension to collect performance profiles and investigate issues with the service.

The Performance Profiler Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with the configured Performance Profiler Extension

# ...
  config: |
    extensions:
      pprof:
        endpoint: localhost:1777 (1)
        block_profile_fraction: 0 (2)
        mutex_profile_fraction: 0 (3)
        save_to_file: test.pprof (4)

    receivers:
      otlp:
        protocols:
          http: {}

    exporters:
      otlp:

    service:
      extensions: [pprof]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	The endpoint at which this extension listens. Use `localhost:` to make it available only locally or `":"` to make it available on all network interfaces. The default value is `localhost:1777`.
2	Sets a fraction of blocking events to be profiled. To disable profiling, set this to `0` or a negative integer. See the documentation for the `runtime` package. The default value is `0`.
3	Set a fraction of mutex contention events to be profiled. To disable profiling, set this to `0` or a negative integer. See the documentation for the `runtime` package. The default value is `0`.
4	The name of the file in which the CPU profile is to be saved. Profiling starts when the Collector starts. Profiling is saved to the file when the Collector is terminated.

Health Check Extension

The Health Check Extension provides an HTTP URL for checking the status of the OpenTelemetry Collector. You can use this extension as a liveness and readiness probe on OpenShift.

The Health Check Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with the configured Health Check Extension

# ...
  config: |
    extensions:
      health_check:
        endpoint: "0.0.0.0:13133" (1)
        tls: (2)
          ca_file: "/path/to/ca.crt"
          cert_file: "/path/to/cert.crt"
          key_file: "/path/to/key.key"
        path: "/health/status" (3)
        check_collector_pipeline: (4)
          enabled: true (5)
          interval: "5m" (6)
          exporter_failure_threshold: 5 (7)

    receivers:
      otlp:
        protocols:
          http: {}

    exporters:
      otlp:

    service:
      extensions: [health_check]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	The target IP address for publishing the health check status. The default is `0.0.0.0:13133`.
2	The TLS server-side configuration. Defines paths to TLS certificates. If omitted, the TLS is disabled.
3	The path for the health check server. The default is `/`.
4	Settings for the Collector pipeline health check.
5	Enables the Collector pipeline health check. The default is `false`.
6	The time interval for checking the number of failures. The default is `5m`.
7	The threshold of multiple failures until which a container is still marked as healthy. The default is `5`.

Memory Ballast Extension

The Memory Ballast Extension enables applications to configure memory ballast for the process.

The Memory Ballast Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with the configured Memory Ballast Extension

# ...
  config: |
    extensions:
      memory_ballast:
        size_mib: 64 (1)
        size_in_percentage: 20 (2)

    receivers:
      otlp:
        protocols:
          http: {}

    exporters:
      otlp:

    service:
      extensions: [memory_ballast]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [otlp]
# ...

1	Sets the memory ballast size in MiB. Takes priority over the `size_in_percentage` if both are specified.
2	Sets the memory ballast as a percentage, `1`-`100`, of the total memory. Supports containerized and physical host environments.

zPages Extension

The zPages Extension provides an HTTP endpoint that serves live data for debugging instrumented components in real time. You can use this extension for in-process diagnostics and insights into traces and metrics without relying on an external backend. With this extension, you can monitor and troubleshoot the behavior of the OpenTelemetry Collector and related components by watching the diagnostic information at the provided endpoint.

The zPages Extension is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OpenTelemetry Collector custom resource with the configured zPages Extension

# ...
  config: |
    extensions:
      zpages:
        endpoint: "localhost:55679" (1)

    receivers:
      otlp:
        protocols:
          http: {}
    exporters:
      debug:

    service:
      extensions: [zpages]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]
# ...

1	Specifies the HTTP endpoint for serving the zPages extension. The default is `localhost:55679`.

Accessing the HTTP endpoint requires port-forwarding because the Red Hat build of OpenTelemetry Operator does not expose this route.

You can enable port-forwarding by running the following oc command:

$ oc port-forward pod/$(oc get pod -l app.kubernetes.io/name=instance-collector -o=jsonpath='{.items[0].metadata.name}') 55679

The Collector provides the following zPages for diagnostics:

serviceZ: Shows an overview of the Collector services and links to the following zPages: PipelineZ, ExtensionZ, and FeatureZ. This page also displays information about the build version and runtime. An example of this page’s URL is http://localhost:55679/debug/servicez.
PipelineZ: Shows detailed information about the active pipelines in the Collector. This page displays the pipeline type, whether data are modified, and the associated receivers, processors, and exporters for each pipeline. An example of this page’s URL is http://localhost:55679/debug/pipelinez.
ExtensionZ: Shows the currently active extensions in the Collector. An example of this page’s URL is http://localhost:55679/debug/extensionz.
FeatureZ: Shows the feature gates enabled in the Collector along with their status and description. An example of this page’s URL is http://localhost:55679/debug/featurez.
TraceZ: Shows spans categorized by latency. Available time ranges include 0 µs, 10 µs, 100 µs, 1 ms, 10 ms, 100 ms, 1 s, 10 s, 1 m. This page also allows for quick inspection of error samples. An example of this page’s URL is http://localhost:55679/debug/tracez.

Additional resources

OpenTelemetry Protocol (OTLP) documentation