FAQ

What is myriarch?

Myriarch is an open-source OpAMP server and fleet manager for OpenTelemetry Collectors. Git is the source of truth for blueprints, fleets, rollout policies and the allowed collector versions. The web UI and the REST API operate within that frame, and every operator action is audited. The page What is Myriarch? has the facts in one place; the concepts and the architecture explain how it works.

How does it relate to OpenTelemetry and OpAMP?

Myriarch is an independent project. It is an OpAMP server and control plane for collectors that run under the upstream OpAMP Supervisor. The protocol, the supervisor and the collector stay upstream; myriarch adds configuration rendering from Git, rollouts in waves, version updates through executors and an audit trail. The name OpenTelemetry is used only to describe what myriarch works with. See ADR-0028 and the brand and trademark rules.

What is OpAMP?

OpAMP, the Open Agent Management Protocol of the OpenTelemetry project, is a network protocol with which a server manages a fleet of telemetry agents: the agents report their status, and the server sends remote configuration and offers packages. Myriarch is an OpAMP server; the protocol, the supervisor and the collector stay upstream. OpAMP, the Supervisor and the Collector explains the parts and how a configuration reaches a collector.

What can the OpAMP Supervisor do, and what can it not do?

The OpAMP Supervisor is the upstream process that starts and monitors a collector and speaks OpAMP for it. It applies remote configuration, reports health and the effective configuration, and restarts the collector. It cannot replace the collector binary: in version 0.162.0 its package manager answers “unsupported” at run time. Myriarch therefore updates collector versions through executors. The sources and their dates are in the upstream notes.

What is the difference between the OpAMP extension and the OpAMP Supervisor?

The OpAMP extension is a component inside the collector; the OpAMP Supervisor is a separate process. The supervisor starts the collector with the extension in its configuration and learns the description and the components of the collector through the extension. It speaks OpAMP to the server for the collector: it applies remote configuration, reports health and the effective configuration, and restarts the collector. Myriarch documents collectors that run under the supervisor; the core distribution of the collector lacks the extension. See the upstream notes on identity and reported attributes and on the Operator with the OpAMP Bridge.

Why is there an updater next to the supervisor?

The upstream OpAMP Supervisor can manage configuration, health and restarts, but it cannot replace the collector binary. Version updates therefore go through exchangeable executors: the host agent myriarch-updater, a webhook or an AWX job. On Kubernetes the version is part of the image, so a pipeline changes it. See Executors and ADR-0006.

Can I keep Ansible AWX or my own pipeline for collector updates?

Yes. The executor of a fleet decides what installs a new version: the awx executor launches a job template of Ansible AWX for the hosts of a wave, and the webhook executor calls a URL, for example a pipeline that bumps an image tag. The rollout engine still decides which hosts update when, and a host counts as updated only when its collector reports the new version. See Executors.

How do I manage many OpenTelemetry Collectors with OpAMP?

Run each collector under the upstream OpAMP Supervisor, run Myriarch as the OpAMP server, and declare blueprints, fleets and rollout policies in a Git repository. Changes merged in Git are rendered per collector and rolled out in waves. The steps are in Manage many OpenTelemetry Collectors with OpAMP and Git.

Does Myriarch replace the OpAMP Supervisor?

No. The collectors keep running under the upstream supervisor, and Myriarch is the server side. It does not plan its own supervisor or collector distribution; see the roadmap. The comparison shows when the supervisor alone, a server of your own on opamp-go or Myriarch fits, and when Myriarch is not the right choice.

Which collector distribution does myriarch manage?

OpenTelemetry Collector Contrib (otelcol-contrib), run by the upstream OpAMP Supervisor. The field spec.collector.distribution of a fleet accepts only otelcol-contrib, and the documentation covers that distribution. See the schema reference.

How do I upgrade the OpenTelemetry Collector on many hosts?

Set the target version of the fleet in Git and give the fleet an executor: the host agent myriarch-updater, a webhook or an AWX job installs it, because the supervisor cannot replace the collector binary. A version rollout moves the hosts in waves and a host is done when its collector reports the new version. See Upgrade the OpenTelemetry Collector on many hosts.

Can collectors be updated without internet access?

Yes, with the updater executor. Mirror the official release files one to one into an internal artifact repository and point artifacts.sourceBaseUrl of the server at it, with artifacts.sourceAuth for its credentials and, behind a proxy, the TUF settings under artifacts.verify; signature verification stays on. See Work offline with a local mirror and the production checklist.

How do I roll out a collector configuration change safely?

Change the blueprint in Git and merge. The rollout policy of each affected fleet sets the waves, the approval of the next wave, the failure threshold and whether a failure rolls back or pauses. See Roll out a configuration change.

How do I roll back a bad collector configuration?

The rollout policy decides what happens when a wave reaches its failure threshold: onFailure: rollback returns every started target to its previous configuration, and onFailure: pause stops the rollout until an operator resumes it, retries the failed targets, aborts it or rolls it back. A rollback contradicts Git, so revert the change in Git as well. On a single host, the upstream supervisor can also return to its last working remote configuration when automatic_config_rollback is set; it is off by default upstream (upstream notes), and the supervisor configurations that the myriarch installers and the collector chart write turn it on (server behaviour). See Failure threshold, pause and rollback.

How do I check a collector configuration in CI?

myrctl validate runs the same validation as the server, and myrctl render shows the configuration that a host would receive. See Validate a GitOps repository.

Who changed a configuration?

Declared state changes only through Git, so the history of the repository answers it. Every operator action in the UI and the API, such as an approval or a version chosen in the UI, is audited with the user and the reason; see the security model and the audit endpoints of the REST API.

What are the support levels?

Myriarch is alpha. In v0.2.0, container mode, Linux hosts and the server Helm chart are beta; Windows hosts and the collector Helm chart are experimental. The levels and what they mean are in Support levels and tested platforms; what has to hold before the project calls itself beta is in the roadmap.

Do I need Kubernetes?

No. The server is one binary that needs PostgreSQL. It runs on a host, in a container or on Kubernetes with the Helm chart. Collectors can run on Linux and Windows hosts at edge sites and in data centers, or in Kubernetes pods. A development setup needs no container runtime at all: see Local development. To try it with containers on one machine, use Docker Compose. To try it on Kubernetes, use Kubernetes on kind; for a real installation see Install with Helm and Install the collector with Helm.

How does myriarch relate to the OpenTelemetry Operator and its OpAMP Bridge?

On Kubernetes, the Operator manages collectors as custom resources, and its OpAMP Bridge, in its default operator mode, reports them to an OpAMP server as one agent. Myriarch recognises a Bridge as an agent kind of its own. In operator mode it sends the Bridge nothing that changes a collector resource; a fleet configures a Bridge only in standalone mode and only with spec.bridge.manage: true. To run collectors that myriarch manages one by one, use the Helm chart myriarch-collector, which runs the supervisor and the collector in one pod. See Bridge agents and Install the collector with Helm.

How many collectors does it handle?

The design target is 1,000 to 5,000 collectors, each with an optional updater, served by two or three replicas. The numbers behind this are in the architecture, and Simulate a fleet shows how to test the load yourself.

Which database does it use?

PostgreSQL holds the state, carries the events between replicas and elects the leader. There is no other stateful component. See ADR-0002.

What is the license?

The code is licensed under Apache-2.0 and the documentation under CC BY 4.0. Third-party software keeps its own license. See ADR-0018, ADR-0030 and the third-party notices of this website.

How can I contribute?

Read Contributing. Every commit carries a Signed-off-by: line that certifies the Developer Certificate of Origin; the project uses the DCO and no contributor license agreement (ADR-0019). The contributor ladder describes the roles, and the development guide the toolchain and the checks.

How do I report a vulnerability?

Privately, never in a public issue. Use GitHub private vulnerability reporting or write to the address in the security policy, which also lists the supported versions and the disclosure process.

Does the software or this website track users?

This website sets no cookies, runs no analytics and makes no requests to third parties; see its privacy statement. The software sends no usage reports to the project. The connections that the server opens itself are listed in the security model, and the operator controls them.