Migrate from Grafana Alloy to otelcol-contrib

This page replaces a Grafana Alloy collector with an otelcol-contrib collector managed over OpAMP. The new collector joins the Alloy collector’s collector group, so it receives the group’s sources, destinations and routes, rendered as OpenTelemetry Collector YAML, and sends to the same destinations.

On a Linux host the switch takes about ten minutes. Collection pauses for the minute or two between stopping Alloy and the new collector receiving the group’s config.

Does LinkMesh support Grafana Alloy?

No. Since LinkMesh server 1.445.0, LinkMesh manages one collector runtime: the upstream OpenTelemetry Collector (otelcol-contrib), unmodified, run by the OpAMP supervisor.

When you upgrade, an Alloy collector enrolled under an earlier version shows as Unsupported Runtime in Collectors. LinkMesh no longer sends it configuration, it no longer uses a collector seat, and new Alloy collectors cannot enrol. An Alloy collector keeps its last configuration only until it next restarts. To keep data flowing without a gap, replace it as described below before you upgrade.

Need help with the migration? Open a ticket in the Customer Portal, see LinkMesh support.

How the config carries over

Sources, destinations, routes and pipelines in LinkMesh are not written in Alloy’s River language. They are stored once and rendered for each collector’s runtime. A collector that joins a group renders everything wired on the group, so an otelcol-contrib collector in the same group runs the same sources and sends to the same destinations as the Alloy collector it replaces.

Group membership is what carries the config. Before you start, find the Alloy collector’s group: Collect → Groups, and each group’s Members tab lists its collectors.

Sources, destinations and routes attached to the Alloy collector rather than to its group stay with that collector, whether or not it is in a group, and go when it is deregistered. Open the collector and check its Sources, Destinations and Routing tabs. Move anything you find onto the group before you replace the collector:

No group yet? Collect → Groups → New Collector Group. A Linux host needs a VM group, a Kubernetes fleet a Kubernetes group.
For each of the collector’s own sources: if its row is local, click Save to library on it. On the group’s Sources tab click Add existing from library and pick it. Then remove it from the collector, so it does not run twice.
On the group’s Destinations tab, Assign Destination for each destination the collector sends to.
Rebuild the collector’s routes on the group’s Routing tab.

Then follow the steps below, adding the new collector to this group.

What does not carry over

Hand-written River. Anything in /etc/alloy/config.alloy besides the remotecfg block LinkMesh’s installer wrote, or extra components you added to the Alloy Helm values, ran outside LinkMesh. Rebuild it as LinkMesh sources and routes, or as a custom source or destination.
Alloy-specific settings. Alloy’s component stability level, its web UI on port 12345, and the Alloy Helm chart values (controller type, image tag, extra mounts) have no counterpart. The otelcol-contrib collector runs the components LinkMesh renders, with the settings the install command sets.
Read positions and queued data. Alloy keeps how far it has read each file, and data it has not sent yet, in its own state directory. The new collector starts without it. A File Tail source set to start at the end of the file skips lines written while no collector ran; one set to start at the beginning reads the whole file again and sends duplicates.
Collector history. The otelcol-contrib collector is a new collector in LinkMesh. Its events, health and throughput history start when it enrols. Those of the Alloy collector go with its record.

Replace an Alloy collector on a Linux host

Alloy and otelcol-contrib both open the ports the group’s sources listen on, OTLP’s 4317 among them, so Alloy stops before the new collector starts.

Get an install command. In LinkMesh, Collectors → + Add Collector → Install Now, pick Linux on the Platform & token step, and generate the token. Copy the install command from the Install step. It carries a single-use enrollment token.
Stop and remove Alloy on the host. On Debian or Ubuntu:
```
sudo systemctl disable --now alloy
sudo apt-get purge -y alloy
sudo rm -rf /etc/alloy /var/lib/alloy
```
On RHEL, Fedora or Amazon Linux:
```
sudo systemctl disable --now alloy
sudo dnf remove -y alloy
sudo rm -rf /etc/alloy /var/lib/alloy
```
/etc/alloy/config.alloy holds the collector’s LinkMesh credential, so remove it rather than leave it on the host. If the LinkMesh agent runs on the host, sudo linkmesh-agent uninstall alloy --purge removes the package for you; remove the two directories afterwards.

Install otelcol-contrib with the command from step 1:

curl -fsSL https://linkmesh.example.com/api/v1/downloads/install-opamp.sh | \
  sudo sh -s -- --token <YOUR_ENROLLMENT_TOKEN>

The host appears in Collectors with management mode OpAMP within about 30 seconds.

Add it to the group. Collect → Groups, open the Alloy collector’s group, Members tab, Add Collectors, pick the new collector. Its detail page shows a config_applied event within a few seconds, and its Configuration tab lists the group’s sources and destinations.
Deregister the Alloy collector. It stays in Collectors with the status Unsupported Runtime after Alloy is removed. Open it and click Deregister. That removes it from the group’s members and revokes its credential. The config stays on the group.

Optionally, remove what the Alloy package left on the host. Keep the Grafana package repository if you install anything else from it:

sudo userdel alloy
sudo rm -f /etc/apt/sources.list.d/grafana.list /etc/apt/keyrings/grafana.gpg   # Debian/Ubuntu
sudo rm -f /etc/yum.repos.d/grafana.repo                                        # RHEL/Fedora/Amazon Linux

Replace an Alloy fleet on Kubernetes

On Kubernetes the group is the cluster: it carries the cluster’s name, and the install command for a cluster name that already exists enrols the new collectors into that cluster’s group.

Note the cluster name. Collect → Groups lists the cluster under the name you gave it when you added the Alloy fleet.
Remove the Alloy release:
```
helm uninstall linkmesh-alloy --namespace linkmesh
```
This deletes the Alloy DaemonSet and the RBAC objects its values added. The linkmesh namespace stays. Alloy’s state directory on each node, /var/lib/linkmesh/alloy, is not used again and can be deleted.
Get the collector fleet manifest. Collectors → + Add Collector → Install Now, pick Kubernetes on the Platform & token step, and enter the same cluster name. The wizard confirms that a cluster of that name exists and that the token adds collectors to it. Pick the same platform variant the Alloy fleet used.
Apply it to the cluster with the command the wizard shows, then wait for the fleet:
```
kubectl --namespace linkmesh rollout status daemonset/linkmesh-otelcol
```
The group’s Members tab lists one collector per node, each in management mode OpAMP. They receive the group’s config when they enrol.
Deregister the Alloy collector. The whole Alloy fleet was one collector in LinkMesh. It stays in Collectors with the status Unsupported Runtime. Open it and click Deregister.

Verify

The new collector, or each fleet member, is Online in Collectors.
Its Configuration tab shows the group’s sources and destinations as OpenTelemetry Collector YAML.
Records reach your destinations again. Routing shows throughput on the group’s routes within a minute or two.

Troubleshooting

The collector does not get the group’s sources. Open the group and click Sync Config. It pushes the group’s config to every member.
bind: address already in use in journalctl -u opamp-supervisor. Alloy is still running and holds the port. Run step 2 again, then sudo systemctl restart opamp-supervisor.
The Kubernetes fleet appears as a second cluster group. The cluster name in step 3 differed from the existing one. Delete the linkmesh-otelcol DaemonSet, deregister its collectors, and repeat step 3 with the existing name.
More: Enrollment troubleshooting.