Der OpAMP-Supervisor, Schritt für Schritt

Kurz gesagt

• Der OpAMP-Supervisor ist ein kleines Upstream-Binary. Er startet Ihren OpenTelemetry Collector als Kindprozess, nimmt Remote-Config von einem OpAMP-Server entgegen und meldet zurück, was der Collector tatsächlich ausführt.
• Sie brauchen vier Dinge: den Supervisor, ein Collector-Binary, eine supervisor.yaml und einen OpAMP-Server. Für einen ersten Test genügt der Beispielserver aus opamp-go.
• Remote-Konfiguration ist standardmässig aus. Setzen Sie capabilities.accepts_remote_config: true, sonst wird nichts, was Sie pushen, je angewendet.
• Vor der Produktion: automatic_config_rollback einschalten, eine Datei unter startup_fallback_configs hinterlegen und wissen, dass eine leere Remote-Config den Collector stoppt.

Remote-Konfiguration für den OpenTelemetry Collector heisst in der Praxis: Ein Server entscheidet, welche Config ein Collector ausführt, der Collector wendet sie an, und der Server erfährt, ob es geklappt hat. Der OpAMP-Supervisor ist der Weg, den das Upstream-Projekt dafür auf der Collector-Seite vorsieht. Er ist die praktische Hälfte des OpenTelemetry Collector Managements und Ansatz 4 in unserem Vergleich der fünf Wege, OpenTelemetry Collectors zu verwalten.

Dieser Beitrag geht Schritt für Schritt durch: Installation, eine minimale Config, ein erster Remote-Push gegen einen Testserver, lokale Config-Ebenen und die Einstellungen, die Sie ändern sollten, bevor Sie ihm eine echte Flotte anvertrauen. Wenn Sie zuerst das Protokoll verstehen möchten, beginnen Sie mit OpAMP erklärt. Alles hier wurde im November 2026 gegen das Upstream-README und die Design-Spezifikation des Supervisors geprüft. Das neueste Supervisor-Release war damals v0.165.0.

Was der OpAMP-Supervisor macht und was nicht

Der Supervisor (opampsupervisor, im Repository collector-contrib) ist ein eigener Prozess zwischen einem OpAMP-Server und genau einem Collector. Er hält die OpAMP-Verbindung, damit der Collector das nicht muss. Er startet den Collector, überwacht ihn und startet ihn neu, wenn er abstürzt.

Schickt der Server eine neue Config, führt der Supervisor sie mit allfälligen lokalen Dateien zusammen, schreibt das Ergebnis als effective.yaml in sein Storage-Verzeichnis und startet den Collector mit dieser Datei neu. Anschliessend meldet er dem Server das Ergebnis, zusammen mit der effektiven Config und dem Zustand des Collectors.

Abbildung 1. Die Config fliesst nach unten zum Supervisor, der sie schreibt und den Collector neu startet. Status, effektive Config und Zustand fliessen zurück nach oben.

Drei Dinge macht er nicht, und es hilft, sie vor dem Start zu kennen:

• Er ist kein Server. Der Supervisor ist die Client-Seite. Welcher Collector welche Config bekommt, Versionen ablegen, den Zustand der Flotte zeigen: Das ist Aufgabe des Servers, und den bauen Sie selbst oder Sie betreiben einen.
• Er aktualisiert das Collector-Binary noch nicht. Paketverwaltung steht im Protokoll, ist im Supervisor aber nicht umgesetzt. Updates des Collectors bleiben bei Ihren bestehenden Werkzeugen.
• Er ist noch Alpha. Laut Upstream-README ändert sich das Design noch. Pinnen Sie Versionen und lesen Sie das Changelog vor einem Update.

Schritt 1: Collector und Supervisor installieren

Beide Binaries kommen aus dem Repository opentelemetry-collector-releases. Der Supervisor erscheint unter einem eigenen Tag-Präfix, cmd/opampsupervisor, als einfaches Binary statt als Tarball.

OTEL_VERSION=<collector-version>
SUPERVISOR_VERSION=<supervisor-version>
ARCH=amd64   # oder arm64

# Der Collector (Contrib-Distribution, Tarball)
curl -fsSL \
  "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTEL_VERSION}/otelcol-contrib_${OTEL_VERSION}_linux_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin otelcol-contrib

# Der Supervisor (einfaches Binary)
sudo curl -fsSL -o /usr/local/bin/opampsupervisor \
  "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fopampsupervisor%2Fv${SUPERVISOR_VERSION}/opampsupervisor_${SUPERVISOR_VERSION}_linux_${ARCH}"
sudo chmod 755 /usr/local/bin/opampsupervisor

Wählen Sie Versionen, die nah beieinander liegen. Supervisor und Collector sprechen über die OpAMP-Extension des Collectors miteinander, und diese Verbindung kann brechen, wenn die beiden weit auseinanderliegen. Für den Betrieb als Container gibt es auch ein Supervisor-Image in der GitHub Container Registry.

Schritt 2: Eine minimale supervisor.yaml schreiben

Das ist die kleinste Config, die etwas Nützliches tut. Sie zeigt auf einen Server, schaltet Remote-Config ein, nennt das Collector-Binary und setzt ein Storage-Verzeichnis.

server:
  endpoint: wss://127.0.0.1:4320/v1/opamp
  tls:
    insecure_skip_verify: true   # nur für den lokalen Testserver

capabilities:
  accepts_remote_config: true
  reports_effective_config: true
  reports_health: true
  reports_own_metrics: true

agent:
  executable: /usr/local/bin/otelcol-contrib

storage:
  directory: /var/lib/otelcol/supervisor

Die wichtigste Zeile ist accepts_remote_config: true. Der Standardwert ist false. Ohne sie verbindet sich der Supervisor, der Server sieht den Collector, und jede Config, die Sie pushen, wird ignoriert. Effektive Config, Zustand und eigene Metriken werden standardmässig gemeldet. Die Flags stehen hier trotzdem, damit die Datei sagt, was sie tut.

Noch ein Detail: Manche älteren Anleitungen setzen zusätzlich reports_remote_config: true. Dieses Flag ist veraltet. Seit Supervisor v0.163.0 führt true dazu, dass der Supervisor nicht startet. Der Config-Status wird inzwischen immer gemeldet, wenn accepts_remote_config aktiv ist. Lassen Sie das alte Flag also weg.

Schritt 3: Einen Testserver starten und den Supervisor laufen lassen

Für einen ersten Lauf brauchen Sie keine echte Control Plane. Das Repository opamp-go enthält einen Beispielserver mit einer kleinen Web-Oberfläche:

git clone https://github.com/open-telemetry/opamp-go.git
cd opamp-go/internal/examples/server
go run .

Die Oberfläche läuft auf http://localhost:4321. Der OpAMP-Endpoint in der Config oben passt zum Beispielserver. Starten Sie den Supervisor in einem zweiten Terminal:

opampsupervisor --config=supervisor.yaml

Öffnen Sie die Oberfläche erneut. Der Collector erscheint in der Agent-Liste, mit seiner Beschreibung und der Config, die er ausführt.

Was dazwischen passiert, lohnt sich zu kennen, denn es erklärt die ersten Sekunden jedes Supervisor-Starts. Der Server muss wissen, mit welchem Collector er spricht, bevor er eine Config schicken kann. Der Collector kann sich aber erst beschreiben, wenn er läuft. Deshalb startet der Supervisor bei einer frischen Installation den Collector zuerst mit einer No-op-Config (ein nop-Receiver, ein nop-Exporter und die OpAMP-Extension), liest seine Beschreibung, stoppt ihn und verbindet sich mit dem Server. Sobald eine Config ankommt, wird sie im Storage-Verzeichnis zwischengespeichert, und spätere Neustarts überspringen diesen Schritt.

Schritt 4: Eine Remote-Konfiguration pushen

Öffnen Sie in der Oberfläche des Beispielservers den Collector und fügen Sie eine Config ein. Halten Sie den ersten Push klein, zum Beispiel ein OTLP-Receiver und der debug-Exporter:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  debug:
    verbosity: basic

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]

Senden Sie sie ab, und der Supervisor erledigt vier Dinge der Reihe nach. Er speichert die Config, führt sie mit allfälligen lokalen Dateien zusammen, schreibt effective.yaml und startet den Collector mit --config <storage>/effective.yaml neu. Danach meldet er dem Server einen Remote-Config-Status (zuerst «wird angewendet», dann «angewendet» oder «fehlgeschlagen»), zusammen mit der neuen effektiven Config.

Diese letzte Meldung ist der eigentliche Zweck des Ganzen. Ein Config-Management-Lauf sagt Ihnen, was geschrieben wurde. Diese Meldung sagt Ihnen, was der Collector geladen hat.

Zwei Verhaltensweisen sollten Sie hier kennen. Erstens ist das Anwenden einer Config ein Neustart, kein Reload. Rechnen Sie bei jeder Änderung mit einer kurzen Lücke in der Erfassung, und pushen Sie Änderungen nicht in kurzer Folge. Zweitens stoppt eine leere Remote-Config den Collector, und er bleibt gestoppt, bis eine nicht leere Config ankommt. Ein Server-Fehler, der eine leere Config-Map schickt, legt die Erfassung lahm. Sichern Sie das auf der Serverseite ab.

Schritt 5: Lokale Config mit config_files schichten

Selten soll der Server jede Zeile besitzen. Mit der Liste agent.config_files führen Sie lokale Dateien mit der Remote-Config zusammen, und die Reihenfolge entscheidet, wer gewinnt. Die Dateien werden von oben nach unten zusammengeführt, spätere überschreiben frühere.

Drei besondere Einträge stehen für die Teile, die der Supervisor erzeugt: $OWN_TELEMETRY_CONFIG (die eigene Telemetrie des Collectors), $OPAMP_EXTENSION_CONFIG (die Verbindung zurück zum Supervisor) und $REMOTE_CONFIG (was der Server geschickt hat). Ein gängiges Muster aus der Upstream-Spezifikation stellt eine Basisebene an den Anfang und eine Compliance-Ebene ans Ende, damit der Server sie nicht überschreiben kann:

agent:
  executable: /usr/local/bin/otelcol-contrib
  config_files:
    - /etc/otelcol/base.yaml
    - $OWN_TELEMETRY_CONFIG
    - $OPAMP_EXTENSION_CONFIG
    - $REMOTE_CONFIG
    - /etc/otelcol/compliance.yaml

Abbildung 2. Die Reihenfolge von config_files ist die Priorität. Was der Server nie überschreiben darf, gehört ans Ende.

Führen Sie keinen der besonderen Einträge auf, fügt der Supervisor sie selbst ein: zuerst die eigene Telemetrie, dann Ihre Dateien, dann die OpAMP-Extension, dann die Remote-Config. Mit dieser Voreinstellung gewinnt der Server gegen Ihre lokalen Dateien. Vorsicht beim Überschreiben von $OPAMP_EXTENSION_CONFIG: Ändert eine spätere Datei die Extension, kann der Supervisor den Kontakt zum Collector verlieren.

Schritt 6: Einstellungen vor der Produktion

Die Standardwerte sind auf eine Demo ausgelegt. Fünf Einstellungen machen für eine echte Flotte den Unterschied.

Eine Config zurückrollen, die den Collector bricht. Standardmässig aus:

agent:
  automatic_config_rollback: true

Ist die Option aktiv, behält der Supervisor die letzte funktionierende Config auf der Festplatte. Verhindert eine neue Remote-Config, dass der Collector korrekt startet, wechselt er zurück zur letzten funktionierenden, startet neu und meldet diese Config als angewendet. Das ist die eine Einstellung, die Sie am ehesten vor einem Ausfall durch einen Tippfehler bewahrt.

Mit einer bekannten Config starten, wenn der Server nicht erreichbar ist. Auf einem frischen Host ohne gecachte Config und ohne Server hat der Collector nichts auszuführen. Ein Fallback behebt das:

agent:
  startup_fallback_configs:
    - /etc/otelcol/fallback.yaml

Der Fallback muss eine vollständige, eigenständige Collector-Config sein. Er wird nicht mit config_files zusammengeführt. Der Supervisor ergänzt die OpAMP-Extension und die eigene Telemetrie, versucht weiter, den Server zu erreichen, und wechselt zur normalen Config, sobald die Verbindung steht. Ein Host mit gecachter Config nutzt diese, der Fallback zählt also nur beim ersten Start.

TLS verwenden und authentifizieren. Entfernen Sie insecure_skip_verify, verwenden Sie wss:// und senden Sie ein Credential, das Ihr Server prüft. Der Block server nimmt Header entgegen, der übliche Ort für ein Bearer-Token:

server:
  endpoint: wss://opamp.example.com/v1/opamp
  headers:
    Authorization: "Bearer <token>"

Einen Health-Endpoint bereitstellen. Standardmässig aus. Wählen Sie einen Port, den die health_check-Extension Ihres Collectors nicht belegt:

healthcheck:
  endpoint: localhost:13134

Er meldet, ob der Supervisor seinen Zustand speichern und die Config des Collectors erzeugen kann. Richten Sie Ihren Service-Manager oder Load Balancer darauf aus.

Unter einem Service-Manager betreiben. Der Supervisor startet den Collector als Kindprozess. Sie installieren also eine Unit für den Supervisor und keine für den Collector. Unter systemd ist das ein einfacher Service mit Restart=always und ExecStart=/usr/local/bin/opampsupervisor --config /etc/otelcol/supervisor.yaml.

Optional und hilfreich bei der Fehlersuche: agent.collector_crash_log_snippet_kib: 4 hängt das Ende des Collector-Logs an Fehlermeldungen an den Server an. Die Option ist standardmässig aus, weil Collector-Logs sensible Daten enthalten können. Entscheiden Sie das bewusst.

Was Sie noch selbst bauen müssen

Der Supervisor liefert Ihnen einen gut erzogenen Client. Alles oberhalb der Protokollebene bleibt bei Ihnen: ein Server, der Configs speichert, sie den richtigen Collectors zuordnet, eine Historie führt, neue Hosts aufnimmt und Zugangsdaten verteilt, den Zustand der Flotte zeigt und Alarm schlägt, wenn ein Collector eine Config meldet, die Sie nicht geschickt haben. Für ein Team, das diese Plattform selbst besitzen will, sind Supervisor und opamp-go eine solide Grundlage. Unsere OpAMP-Server-Seite zeigt, was die Serverseite in der Praxis umfasst.

Wo LinkMesh hineinpasst

LinkMesh ist ein selbst gehosteter OpAMP-Server, gebaut für genau diesen Supervisor. LinkMesh verwaltet Upstream-otelcol-contrib-Collectors über den Upstream-opampsupervisor, es läuft also kein LinkMesh-Code auf dem Host. Der Installer lädt beide Binaries herunter, schreibt die supervisor.yaml mit einem Enrollment-Token und startet die systemd-Unit. Danach erscheint der Collector in der Flottenansicht, mit seinem Zustand und der Config, die er meldet.

Wenn Sie die Schritte oben durchgegangen sind, kennen Sie die Client-Seite bereits. Die Onboarding-Anleitung zeigt denselben Supervisor mit LinkMesh als Server, und Sie können LinkMesh installieren, um es an einem Collector auszuprobieren.