Lawrence

OpenTelemetry OpAMP Supervisor Capabilities Explained

OpenTelemetry OpAMP Supervisor capabilities explained: what the Supervisor adds, how it behaves during outages, and which production-grade options you may want to enable early.

L
Lawrence

💡
OpenTelemetry OpAMP tl;dr - A protocol, created by the OTel community, to help manage large fleets of OTel agents. It is primarily a specification, but it also defines and provides an implementation for how agents can communicate remotely. It supports features like remote configuration, status reporting, agent telemetry and secure agent update.

In our previous post (see here), we covered what OpAMP is and went through a simple integration of an OpenTelemetry collector via the OpAMP Extension and Supervisor.

We will create a more comprehensive guide for both the Supervisor and OpAMP Bridge (OpenTelemetry k8s Operator).

In the meantime, however, we’ve decided to elaborate on the great capabilities of the OpAMP supervisor as a standalone piece so you can explore it further yourself.

So, for those of you who are already familiar with OpAMP and have tried the basic OpAMP Extension (and perhaps the Supervisor), this post adds a few nuggets of information: what the Supervisor adds, how it behaves during outages, and which production-grade options you may want to enable early.

Table of Contents

OpenTelemetry OpAMP Supervisor Capabilities

The supervisor enables several powerful capabilities that the basic extension doesn't support. The table below summarizes each capability’s purpose and default value, so you can quickly see what’s active out of the box and what must be explicitly enabled.

Capability Purpose Default
accepts_remote_config Allows the OpAMP server to push new/updated collector configurations remotely false
reports_effective_config Sends the collector's effective config (final merged YAML) to the OpAMP server, so you can see exactly what's running true
reports_own_metrics The Collector will report own metrics to the destination specified by the OpAMP Server true
reports_own_logs The Collector will report own logs to the destination specified by the OpAMP Server. true
reports_own_traces Reports the collector's own traces to the destination specified by the OpAMP server true
reports_health Periodically reports the collector's health (up, degraded, failed) to the OpAMP server true
reports_remote_config Confirms and reports back which remote config is currently applied, so the server knows updates were successful false
accepts_packages Enables remote collector executable updates. Security Note: Should only be enabled with code signing/verification false
accepts_other_connection_settings Allows the OpAMP server to configure connection settings for exporters (endpoints, headers, TLS certificates) false
accepts_restart_command Allows the OpAMP server to remotely restart the collector true
reports_heartbeat The supervisor will report OpAMP heartbeats to the Server true

💡
Capabilities that default to false (like accepts_remote_config and accepts_packages) must be explicitly enabled in your supervisor configuration. This follows the principle of least privilege for security.

Operation when the OpAMP server is unavailable

The supervisor is designed to be resilient to OpAMP server outages. If it cannot connect, here’s how it behaves, allowing you to keep telemetry flowing while the control plane recovers:

  • The collector continues running with the last known configuration (if one was previously persisted to disk).
  • The supervisor continuously attempts to reconnect to the OpAMP server using exponential backoff.
  • If no previous configuration exists, the collector won't start until the server becomes reachable.

This design ensures your telemetry pipeline stays operational even during control plane outages.

Your collectors keep collecting and exporting data with their last known good configuration, while the supervisor quietly works to re-establish the management connection in the background.

In practice, this means you can survive transient control-plane issues without losing data, and once connectivity returns, remote config and health reporting resume automatically.

Additional advanced configuration options

There are several additional production-ready features available.

Use these to enforce least privilege, make configuration changes predictable, and improve fleet observability.

Security & Process Management:

  • Run as non-root user: Use agent.run_as to drop privileges and run the collector as a restricted user.
  • Filesystem access control: Restrict collector access to specific directories with agent.access_dirs (allowing read/write only to designated paths).
  • Orphan detection: Configure agent.orphan_detection_interval to control how often the collector checks if the supervisor is still running.

Configuration Control:

  • Custom config file merging: Use agent.config_files with special placeholders ($OPAMP_EXTENSION_CONFIG, $OWN_TELEMETRY_CONFIG, $REMOTE_CONFIG) to control configuration precedence and merge order.
  • Extra arguments and environment: Pass additional command-line flags via agent.args and environment variables via agent.env to the collector process.

Agent Identity & Attributes:

  • Override agent description: Add custom identifying or non-identifying attributes in agent.description to tag your collectors with environment, region, or other metadata

Supervisor Telemetry:

  • The supervisor itself can emit logs, metrics, and traces about its operations, configurable under the telemetry section for observability of your observability infrastructure

💡
For the complete configuration reference, see the opentelemetry-collector-contrib supervisor documentation.

That’s basically it, we just wanted to quickly provide you with more useful information on the Supervisor. Stay tuned for the next articles.

Lawrence is cool

Lawrence helps teams configure, visualize, test, and troubleshoot complex OpenTelemetry deployments at scale.

We’re currently in private beta, so if you’re migrating to OpenTelemetry, need to manage a fleet of OTel agents, need advice on OpenTelemetry (we know our stuff), or need a good coffee recommendation in Portugal, reach out here.