Skip to main content

​
Opamp Extension

Status Available in: contrib, k8s Maintainers: @portertech, @evan-bradley, @tigrannajaryan Source: opentelemetry-collector-contrib

​
Overview

​
Configuration

The following settings are required:
  • server: The OpAMP server connection settings.
    • ws: The OpAMP websocket transport settings.
      • endpoint (no default): The OpAMP server websocket endpoint (URL).
The following settings are optional for the websocket client:
  • server: The OpAMP server connection settings.
    • ws: The OpAMP websocket transport settings.
      • tls: TLS settings.
      • headers: HTTP headers to set.
      • auth: The ID of an auth extension to use for authentication.
The following settings are optional for the HTTP client:
  • server: The OpAMP server connection settings.
    • http: The OpAMP HTTP transport settings.
      • tls: TLS settings.
      • headers: HTTP headers to set.
      • polling_interval: The interval at which the extension will poll the server. Defaults to 30s.
      • auth: The ID of an auth extension to use for authentication.
The following settings are optional for both transports:
  • instance_uid: A UUIDv7 formatted as a 36 character string in canonical representation. Auto-generated on start if missing. Setting this ensures the instance UID remains constant across process restarts.
  • capabilities: Keys with boolean true/false values that enable a particular OpAMP capability.
    • reports_effective_config: Whether to enable the OpAMP ReportsEffectiveConfig capability. Default is true.
    • reports_health: Whether to enable the OpAMP ReportsHealth capability. Default is true.
    • reports_available_components: Whether to enable the OpAMP ReportsAvailableComponents capability. Default is true.
    • accepts_restart_command: Whether to enable the OpAMP AcceptsRestartCommand capability. Default is false. The extension sends a SIGHUP signal to the collector to initiate a restart (however, SIGHUP isn’t supported on windows systems, so it will be ignored). This functionality is also behind a feature gate (alpha) called extension.opampextension.RemoteRestarts
  • agent_description: Setting that modifies the agent description reported to the OpAMP server.
    • include_resource_attributes: Copy the Collector’s resource attributes into the set of non-identifying attributes in the agent description.
    • non_identifying_attributes: A map of key value pairs that will be added to the non-identifying attributes reported to the OpAMP server. If an attribute collides with the default non-identifying attributes that are automatically added, the ones specified here take precedence.
  • ppid: An optional process ID to monitor. When this process is no longer running, the extension will emit a fatal error, causing the collector to exit. This is meant to be set by the Supervisor or some other parent process, and should not be configured manually.
  • ppid_poll_interval: The poll interval between check for whether ppid is still alive or not. Defaults to 5 seconds.

​
Example

extensions:
  opamp:
    server:
      ws:
        endpoint: wss://127.0.0.1:4320/v1/opamp

​
Custom Messages

Other components may use a configured OpAMP extension to send and receive custom messages to and from an OpAMP server. See the opampcustommessages module for more information on the custom message API.

​
Using the AcceptsRestartCommand capability to orchestrate collector config updates

If the accepts_restart_command capability is enabled (along with the extension.opampextension.RemoteRestarts feature gate), upon receiving a restart ServerToAgentCommand, the extension will send a SIGHUP signal to the Collector process. The SIGHUP signal is trapped in the Collector and initiates a graceful restart of all the components by restarting the Collectors service, which restarts all components, pipelines, and Collector self-monitoring. This functionality might be desired if the Collector’s config was updated, as the restart also fetches all configuration sources passed to the Collector through --config flags passed to the command invocation. NOTE on the SIGHUP signal for restarts: SIGHUP is not supported on Windows, and the collector will error on startup if the capability and feature gate are enabled (until the collector can also handle a cross-platform signal like SIGUSR2). Please note: an invalid config will cause the Collector to error out and stay down until it is manually restarted using some other mechanism (since the OpAMP extension won’t be active). Regular healthchecks and using the Collector’s validate subcommand to validate config before applying it are highly recommended when using this functionality to prevent data loss due to config issues.

​
Status

This OpenTelemetry OpAMP agent extension is intended to support the OpAMP Supervisor.

​
Configuration

​
Example Configuration

server:
  ws:
    endpoint: wss://127.0.0.1:4320/v1/opamp
instance_uid: 01BX5ZZKBKACTAV9WEVGEMMVRZ
Last generated: 2026-06-01