OpAMP Supervisor: failed to start supervisor: could not get bootstrap info from the Collector: collector's OpAMP client never connected to the Supervisor

[brightzheng100]

Component(s)

cmd/opampsupervisor

What happened?

Description

I wanted to have a test with the latest OpAMP Supervisor component but I got error while trying to start it up:

./bin/opamp-supervisor --config supervisor-config.yaml
2025/12/12 12:27:59 failed to start supervisor: could not get bootstrap info from the Collector: collector's OpAMP client never connected to the Supervisor

Steps to Reproduce

1. Build and start the OpAMP server

~/workspaces/OSS/OpenTelemetry/playground/bin/opamp-server

2025/12/11 14:42:12.236313 [MAIN] OpAMP Server starting...
2025/12/11 14:42:12.237413 [MAIN] OpAMP Server running...

2. Build OpAMP Supervisor:

```sh
git clone https://github.com/open-telemetry/opentelemetry-collector-contrib.git
cd opentelemetry-collector-contrib/cmd/opampsupervisor
go build -o ~/workspaces/OSS/OpenTelemetry/playground/bin/opamp-supervisor

3. Create the supervisor-config.yaml as:

server:
  endpoint: wss://127.0.0.1:4321/v1/opamp
  tls:
    insecure_skip_verify: true 

capabilities:
  reports_effective_config: true
  reports_own_metrics: true
  reports_own_logs: true
  reports_own_traces: true
  reports_health: true
  accepts_remote_config: true
  reports_remote_config: true

agent:
  executable: /Users/brightzheng/workspaces/OSS/OpenTelemetry/playground/bin/otelcol-dev
  config_files: [/Users/brightzheng/workspaces/OSS/OpenTelemetry/playground/config.yaml]

storage:
  directory: /Users/brightzheng/workspaces/OSS/OpenTelemetry/playground/temp

The error I got:

./bin/opamp-supervisor --config supervisor-config.yaml
2025/12/12 12:27:59 failed to start supervisor: could not get bootstrap info from the Collector: collector's OpAMP client never connected to the Supervisor

Note: the mentioned otelcol-dev binary file and config.yaml config file exist in the right folder.
To prove it:

$ /Users/brightzheng/workspaces/OSS/OpenTelemetry/playground/bin/otelcol-dev --config /Users/brightzheng/workspaces/OSS/OpenTelemetry/playground/config.yaml
2025-12-12T20:30:40.435+0800	info	service@v0.141.0/service.go:224	Starting otelcol-dev...	{"resource": {"service.instance.id": "4ce5b544-4dbf-4909-9378-c3bb82e82042", "service.name": "otelcol-dev", "service.version": ""}, "Version": "", "NumCPU": 10}
2025-12-12T20:30:40.435+0800	info	extensions/extensions.go:40	Starting extensions...	{"resource": {"service.instance.id": "4ce5b544-4dbf-4909-9378-c3bb82e82042", "service.name": "otelcol-dev", "service.version": ""}}
2025-12-12T20:30:40.435+0800	info	otlpreceiver@v0.141.0/otlp.go:120	Starting GRPC server	{"resource": {"service.instance.id": "4ce5b544-4dbf-4909-9378-c3bb82e82042", "service.name": "otelcol-dev", "service.version": ""}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "endpoint": "[::]:4317"}
2025-12-12T20:30:40.436+0800	info	service@v0.141.0/service.go:247	Everything is ready. Begin running and processing data.	{"resource": {"service.instance.id": "4ce5b544-4dbf-4909-9378-c3bb82e82042", "service.name": "otelcol-dev", "service.version": ""}}

Expected Result

The OpAMP Supervisor should properly start the agent, here is a custom built "OTel Collector" and report back to OpAMP Server.

Actual Result

Bootstrap got issues.

Collector version

v0.141.0

Environment information

Environment

OS: Darwin

Compiler(if manually compiled):

$ go version
go version go1.25.5 darwin/arm64

OpenTelemetry Collector configuration

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]

Log output

./bin/opamp-supervisor --config supervisor-config.yaml
2025/12/12 12:41:32 failed to start supervisor: could not get bootstrap info from the Collector: collector's OpAMP client never connected to the Supervisor

Additional context

No response

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[github-actions]

Pinging code owners:

• cmd/opampsupervisor: @evan-bradley @atoulme @tigrannajaryan

See Adding Labels via Comments if you do not have permissions to add labels yourself.

[brightzheng100]

Another weird thing is, based on the code, there is a hard constraint of OTel Collector while running OpAMP Supervisor, which may not position the Supervisor right.

// getBootstrapInfo obtains the Collector's agent description by
// starting a Collector with a specific config that only starts
// an OpAMP extension, obtains the agent description, then
// shuts down the Collector. This only needs to happen
// once per Collector binary.
func (s *Supervisor) getBootstrapInfo() (err error) {
...
}

From the OpAMP spec, it's clear that the Supervisor is actually a "middle man" or "agent manager".
Even OTel Collector can be the potential / special Agent as well through its opampextension, in the real world, we of course can manage our own Agents by Supervisor without the need to have OTel Collector in the picture.

One of the typical ways to implement OpAMP on the Agent side is by having a helping Supervisor process, which controls the Agent process. The Supervisor is also typically responsible for communicating with the OpAMP Server:

      ┌───────────────────┐
      │ Supervisor        │
      │                   │
      │          ┌────────┤           ┌────────┐
      │          │ OpAMP  │  OpAMP    │ OpAMP  │
      │          │        ├──────────►│        │
      │          │ Client │           │ Server │
      └────┬─────┴────────┘           └────────┘
           │
           │
           ▼
      ┌──────────┐
      │          │
      │  Agent   │
      │          │
      └──────────┘

[douglascamata]

@brightzheng100 I think the Supervisor is 100% tightly coupled with the Otel Collector. It doesn't intend to be a generic "agent manager", but a very specific Otel Collector agent manager. That might be the reason why it lives in this repository and not in its own separated one.

Potentially a more generic supervisor could be written, but I'm not sure if that's a goal of the cmd/opampsupervisor package.

[tigrannajaryan]

Generic Supervisor was initially proposed but we decided we do not understand how to generalize it well enough and switched to an Otel Collector-specific one.

[bvigar]

@brightzheng100 was your collector built with the opamp extension? I had this same issue you're describing, only to realize that the collector I built and used in the supervisor wasn't built with the opampextension in my ocb conf. Just a thought.

[brightzheng100]

Thanks for the clarifications.

After reading through the latest OpAMP Specs doc and some code, I realized that -- which might be wrong -- there are huge gaps in two major areas:

1. OpAMP Client with the potential interfaces / standards that the actual Agent should / must implement.
2. OpAMP Server with the potential interfaces / standards that the actual Fleet Management Backend should / must implement.

And my perception is that the opampextension should become the implementation of above-mentioned area 1 that handles ONLY OTel Collector, as per your suggestion. So the Supervisor, since it won't become a generic "agent manager", has become redundant.

[brightzheng100]

was your collector built with the opamp extension?

@bvigar you're right that after rebuilding the custom OTel Collector with opampextension included, it worked well:

$ ./bin/opamp-supervisor --config supervisor-config.yaml
{"level":"info","ts":1765633451.839181,"logger":"supervisor","caller":"supervisor/supervisor.go:349","msg":"Supervisor starting","id":"019b0c80-98be-714c-a0f4-8123d4949499"}
{"level":"info","ts":1765633451.839977,"logger":"supervisor","caller":"supervisor/supervisor.go:1324","msg":"No last received remote config found"}
{"level":"info","ts":1765633451.849924,"logger":"supervisor","caller":"supervisor/supervisor.go:672","msg":"Connected to the server."}

So after consolidating the info in this thread, I believe the Supervisor would work with some prerequisites like:

1. The Supervisor has dependency on OTel Collector and can ONLY manage OTel Collector as the special Agent;
2. The OTel Collector must have the opampextension component included.

Maybe I may close this issue and start a new thread for the "positioning issue" or "gaps" that I mentioned above?

[douglascamata]

After reading through the latest OpAMP Specs doc and some code, I realized that -- which might be wrong -- there are huge gaps in two major areas:

1. OpAMP Client with the potential interfaces / standards that the actual Agent should / must implement.
2. OpAMP Server with the potential interfaces / standards that the actual Fleet Management Backend should / must implement.

The OpAMP specification already exists and describes what clients and servers can or should implement.

The opamp-go library already provides a package to help people build OpAMP clients (the Collector's opampextension and cmd/opampsupervisor use this package, for example) and a package to help people build OpAMP servers (there's even an example server there).

On top of this, many vendors already have Fleet Management products based on OpAMP. There's even a fully open source one: https://github.com/getlawrence/lawrence-oss.

So, given all this, I don't understand what exactly are the gaps you see, @brightzheng100. Can you be more specific?

[douglascamata]

I don't think the opampextension makes the Supervisor redundant, at least not today. The opampextension is not capable of receiving remote configuration, while the Supervisor is. The opampextension is also very far from being able to execute Collector version upgrades, while the Supervisor has a WIP PR implementing this feature.

[brightzheng100]

The OpAMP specification already exists and describes what clients and servers can or should implement.

The opamp-go library already provides a package to help people build OpAMP clients (the Collector's opampextension and cmd/opampsupervisor use this package, for example) and a package to help people build OpAMP servers (there's even an example server there).

Maybe let me use a simple analogy to rephrase what my points are.

Yes, we have the open standard, the OpAMP Specs, which are like Golang or JDK Specs.
Yes, we have opamp-go, which is like the implementation of the Golang or JDK Specs, as some sort of standard libs.

But the Golang world won't be perfect if there are no great libraries, like gin as a web framework.

What I was trying to say is that: We need a good framework / library on top of opamp-go so that a commercial product, think Dynatrace, Datadog, IBM Instana etc., can easily embrace OpAMP to comply with OpAMP Client by a simple reference configuration file, say a opamp-client.yaml and a few lines of code changes for its Agents -- this may similarly apply to the backend side as well.

The opampextension is not capable of receiving remote configuration, while the Supervisor is

The point is not which component has more capabilities as of now; it's about what the direction might look like eventually.
The point is: if OTel Collector can make it OpAMP Client compliant through its opampextension, it may be quite hesitant for people to use another binary, which is Supervisor in this case, to manage it at scale.
So merging Supervisor into just opampextension might be a considerable direction to make OTel Collector self-manageable in just one OTel Collector binary as long as the opampextension component is included.

Thoughts?