Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Extensions

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

Currently, the following General Availability and Technology Preview extensions are available for the Red Hat build of OpenTelemetry:

6.1. BearerTokenAuth Extension
Copy link

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.

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]
# ...
Copy to Clipboard Toggle word wrap

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.

6.2. OAuth2Client Extension
Copy link

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.

Important

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]
# ...
Copy to Clipboard Toggle word wrap

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.

6.3. File Storage Extension
Copy link

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.

Important

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]
# ...
Copy to Clipboard Toggle word wrap

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.

6.4. OIDC Auth Extension
Copy link

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.

Important

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:
      debug: {}
    service:
      extensions: [oidc]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]
# ...
Copy to Clipboard Toggle word wrap

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.

6.5. Jaeger Remote Sampling Extension
Copy link

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.

Important

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:
      debug: {}

    service:
      extensions: [jaegerremotesampling]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]
# ...
Copy to Clipboard Toggle word wrap

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
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

6.6. Performance Profiler Extension
Copy link

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.

Important

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:
      debug: {}

    service:
      extensions: [pprof]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]
# ...
Copy to Clipboard Toggle word wrap

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.

6.7. Google Client Authorization Extension
Copy link

The Google Client Authorization Extension provides Google OAuth 2.0 client credentials and metadata for gRPC and HTTP exporters.

OpenTelemetry Collector custom resource with the Google Client Authorization Extension

# ...
  config:
    extensions:
      googleclientauth:
        project: "<google_cloud_project>"
1 


    exporters:
      otlphttp:
        encoding: json
        endpoint: https://telemetry.googleapis.com
        auth:
          authenticator: googleclientauth

    service:
      extensions: [googleclientauth]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]
# ...
Copy to Clipboard Toggle word wrap

1
The extension sends telemetry to the Google Cloud project that you specify by using this field, which is an alternative to using the gcp.project.id resource attribute. If you do not specify a Google Cloud project by using this field, the extension gets it by using the application default credentials.

6.8. Health Check Extension
Copy link

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.

Important

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:
      debug: {}

    service:
      extensions: [health_check]
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]
# ...
Copy to Clipboard Toggle word wrap

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.

6.9. zPages Extension
Copy link

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.

Important

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]
# ...
Copy to Clipboard Toggle word wrap

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

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
Copy to Clipboard Toggle word wrap

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.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top