Skip to main content
This page installs the OpenTelemetry Collector on an Ubuntu or Debian VM. The collector sends the health of the machine to Sherlock: CPU, memory, disk, network, and warnings from the system journal. Your applications send their own logs and traces. This page does not change them.

What you’ll learn

  • How to install the collector from the upstream package and give it the Sherlock endpoint and token
  • What the configuration collects, and what it costs the VM
  • Where the data appears in Sherlock

Prerequisites

  • An Ubuntu or Debian VM with systemd and sudo. The steps were tested on Ubuntu 24.04.
  • The Endpoint and the Bearer Token from Settings → Collector. Click Reveal to see the token.
  • Metrics enabled for your organization. New organizations have them. If your organization is older, ask us to enable them.
  • The env value for this VM, prod or dev. See Environments.
This page uses otelcol-contrib 0.162.0, the upstream contrib distribution. The configuration uses the current component names: otlp_http (since v0.144.0), host_metrics (since v0.152.0), and resource_detection (since v0.153.0). Older releases accept only the old names otlphttp, hostmetrics, and resourcedetection. Release 0.162.0 accepts the old names as deprecated aliases and logs a warning at startup.

Quick start

1

Install the package

Download the release for the architecture of the VM and install it. The package starts the collector immediately with a default configuration. That configuration opens receiver ports on all interfaces. Stop the service before you continue.
2

Write the configuration

Replace /etc/otelcol-contrib/config.yaml with this file. If the VM is not production, change prod to your env value. The other settings are correct for a usual VM. What it collects explains them.
/etc/otelcol-contrib/config.yaml
3

Set the endpoint and token

The service reads /etc/otelcol-contrib/otelcol-contrib.conf as its environment. The token stays out of the configuration file. Replace the two placeholders with the values from Settings → Collector.
The package creates the file readable by all users. The chmod command comes first, so no other user can read the token. The usermod command lets the collector user read the system journal. Without it, the journald receiver stops with the error “insufficient permissions”.
4

Start the collector

The last log line is Everything is ready, and no errors follow. Press Ctrl+C to exit the log. The collector continues to run.

What it collects

The configuration sends about 100 data points a minute for a VM with one disk and one network interface. The collector uses about 55 MiB of memory. Each data point and journal line carries service.name=vm-health, host.name, host.id, os.type, and your env value. One Sherlock organization can hold many VMs. If the disks or network interfaces of the VM have other names, extend the two regular expressions under disk.include.devices and network.include.interfaces. If the VM uses another filesystem, for example zfs, add its type to fs_types.

Verify in Sherlock

Data appears within about two minutes.
  1. Open Metrics and select the source for your env value. Select system.filesystem.utilization and group by mountpoint. The chart shows the filesystems of the VM. system.cpu.utilization appears in the catalog one minute after the other metrics.
  2. Open Logs in the same source and filter on the service of the collector:
    Only kernel and systemd lines of priority warning and above arrive. A healthy VM sends few of them. To send a test line, write to the kernel log. The line arrives within one minute as an error, with the host.name of the VM:

Troubleshooting

The collector user cannot read the system journal. Run sudo usermod -aG systemd-journal otelcol-contrib, then sudo systemctl restart otelcol-contrib.
Compare the two values in /etc/otelcol-contrib/otelcol-contrib.conf with Settings → Collector. The endpoint is the full URL shown there. The exporter adds /v1/metrics and /v1/logs itself. After you edit the file, restart the service.
No output means the file is valid.
The installed release is older than those names. otlp_http needs v0.144.0, host_metrics needs v0.152.0, and resource_detection needs v0.153.0. Rename them to otlphttp, hostmetrics, and resourcedetection in the component sections and in the pipelines. Or install 0.162.0 as in step 1.
Metrics are not enabled for your organization. Ask us to enable them. No change on the VM is necessary.
Its name does not match the regular expressions. Run lsblk -d and ip -br link to see the names. Extend disk.include.devices or network.include.interfaces to match. Then restart the service.
The configuration is a package conffile. On upgrade, dpkg asks if it must replace the file. To keep your file, run sudo dpkg -i --force-confold otelcol-contrib_<version>_linux_<arch>.deb.

OpenTelemetry SDKs and collectors

Endpoint, header, and the env attribute for any collector.

Environments

How the env value routes the data of the VM into a source.

Metrics

Chart a metric, group by an attribute, and the SQL tab.

Alerts

Schedules, conditions, and notification channels.