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
envvalue for this VM,prodordev. See Environments.
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 The package creates the file readable by all users. The
/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.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
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 carriesservice.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.-
Open Metrics and select the source for your
envvalue. Selectsystem.filesystem.utilizationand group bymountpoint. The chart shows the filesystems of the VM.system.cpu.utilizationappears in the catalog one minute after the other metrics. -
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.nameof the VM:
Troubleshooting
The collector logs insufficient permissions for journald
The collector logs insufficient permissions for journald
The collector user cannot read the system journal. Run
sudo usermod -aG systemd-journal otelcol-contrib, then sudo systemctl restart otelcol-contrib.The collector logs 401 or connection errors
The collector logs 401 or connection errors
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.Check the configuration without starting the service
Check the configuration without starting the service
The collector rejects host_metrics, resource_detection, or otlp_http
The collector rejects host_metrics, resource_detection, or otlp_http
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.Logs arrive but no metrics
Logs arrive but no metrics
Metrics are not enabled for your organization. Ask us to enable them. No change on the VM is necessary.
A disk or network interface is missing
A disk or network interface is missing
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.Upgrading the package asks about config.yaml
Upgrading the package asks about config.yaml
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.Related topics
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.

