> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Hostmetrics

> OpenTelemetry receiver for Hostmetrics

# Hostmetrics Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `core`, `contrib`, `k8s`

**Maintainers:** [@dmitryax](https://github.com/dmitryax), [@braydonk](https://github.com/braydonk), [@rogercoll](https://github.com/rogercoll)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-development-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

## Getting Started

The collection interval, root path, the categories of metrics, and individual
metrics to be scraped can be configured:

```yaml theme={null}
host_metrics:
  collection_interval: <duration> # default = 1m
  initial_delay: <duration> # default = 1s
  root_path: <string>
  scrapers:
    <scraper1>:
      metrics:
        <metric1>:
          enabled: true
        <metric2>:
          enabled: false
        ...
    <scraper2>:
    ...
```

**Note:** While scrapers may support multiple operating systems, individual metrics within a scraper may have different OS support. Refer to each scraper's documentation for metric-level OS compatibility.

The available scrapers are:

| Scraper      | Supported OSs                | Description                                            |
| ------------ | ---------------------------- | ------------------------------------------------------ |
| [cpu]        | All                          | CPU utilization metrics                                |
| [disk]       | All                          | Disk I/O metrics                                       |
| [load]       | All                          | CPU load metrics                                       |
| [filesystem] | All                          | File System utilization metrics                        |
| [memory]     | All                          | Memory utilization metrics                             |
| [network]    | All                          | Network interface I/O metrics & TCP connection metrics |
| [nfs]        | Linux                        | NFS server and client metrics                          |
| [paging]     | All                          | Paging/Swap space utilization and I/O metrics          |
| [processes]  | Linux, Mac, FreeBSD, OpenBSD | Process count metrics                                  |
| [process]    | Linux, Windows, Mac, FreeBSD | Per process CPU, Memory, and Disk I/O metrics          |
| [system]     | Linux, Windows, Mac          | Miscellaneous system metrics                           |

[cpu]: ./internal/scraper/cpuscraper/documentation.md

[disk]: ./internal/scraper/diskscraper/documentation.md

[filesystem]: ./internal/scraper/filesystemscraper/documentation.md

[load]: ./internal/scraper/loadscraper/documentation.md

[memory]: ./internal/scraper/memoryscraper/documentation.md

[network]: ./internal/scraper/networkscraper/documentation.md

[nfs]: ./internal/scraper/nfsscraper/documentation.md

[paging]: ./internal/scraper/pagingscraper/documentation.md

[processes]: ./internal/scraper/processesscraper/documentation.md

[process]: ./internal/scraper/processscraper/documentation.md

[system]: ./internal/scraper/systemscraper/documentation.md

### Notes

Several scrapers support additional configuration:

### Disk

```yaml theme={null}
disk:
  <include|exclude>:
    devices: [ <device name>, ... ]
    match_type: <strict|regexp>
```

### File System

```yaml theme={null}
filesystem:
  <include_devices|exclude_devices>:
    devices: [ <device name>, ... ]
    match_type: <strict|regexp>
  <include_fs_types|exclude_fs_types>:
    fs_types: [ <filesystem type>, ... ]
    match_type: <strict|regexp>
  <include_mount_points|exclude_mount_points>:
    mount_points: [ <mount point>, ... ]
    match_type: <strict|regexp>
  include_virtual_filesystems: <false|true>
```

### Load

`cpu_average` specifies whether to divide the average load by the reported number of logical CPUs (default: `false`).

```yaml theme={null}
load:
  cpu_average: <false|true>
```

### Network

```yaml theme={null}
network:
  <include|exclude>:
    interfaces: [ <interface name>, ... ]
    match_type: <strict|regexp>
```

### Process

```yaml theme={null}
process:
  <include|exclude>:
    names: [ <process name>, ... ]
    match_type: <strict|regexp>
  mute_process_all_errors: <true|false>
  mute_process_name_error: <true|false>
  mute_process_exe_error: <true|false>
  mute_process_io_error: <true|false>
  mute_process_user_error: <true|false>
  mute_process_cgroup_error: <true|false>
  scrape_process_delay: <time>
```

The following settings are optional:

* `mute_process_all_errors` (default: false): mute all the errors encountered when trying to read metrics of a process. When this flag is enabled, there is no need to activate any other error suppression flags.
* `mute_process_name_error` (default: false): mute the error encountered when trying to read a process name the collector does not have permission to read. This flag is ignored when `mute_process_all_errors` is set to true as all errors are muted.
* `mute_process_io_error` (default: false): mute the error encountered when trying to read IO metrics of a process the collector does not have permission to read. This flag is ignored when `mute_process_all_errors` is set to true as all errors are muted.
* `mute_process_cgroup_error` (default: false): mute the error encountered when trying to read the cgroup of a process the collector does not have permission to read. This flag is ignored when `mute_process_all_errors` is set to true as all errors are muted.
* `mute_process_exe_error` (default: false): mute the error encountered when trying to read the executable path of a process the collector does not have permission to read (Linux only). This flag is ignored when `mute_process_all_errors` is set to true as all errors are muted.
* `mute_process_user_error` (default: false): mute the error encountered when trying to read a uid which doesn't exist on the system, eg. is owned by a user that only exists in a container. This flag is ignored when `mute_process_all_errors` is set to true as all errors are muted.

## Advanced Configuration

### Filtering

If you are only interested in a subset of metrics from a particular source,
it is recommended you use this receiver with the
[Filter Processor](../../processor/filterprocessor).

### Different Frequencies

If you would like to scrape some metrics at a different frequency than others,
you can configure multiple `host_metrics` receivers with different
`collection_interval` values. For example:

```yaml theme={null}
receivers:
  host_metrics:
    collection_interval: 30s
    scrapers:
      cpu:
      memory:

  host_metrics/disk:
    collection_interval: 1m
    scrapers:
      disk:
      filesystem:

service:
  pipelines:
    metrics:
      receivers: [host_metrics, host_metrics/disk]
```

### Collecting host metrics from inside a container (Linux only)

Host metrics are collected from the Linux system directories on the filesystem.
You likely want to collect metrics about the host system and not the container.
This is achievable by following these steps:

#### 1. Bind mount the host filesystem

The simplest configuration is to mount the entire host filesystem when running
the container. e.g. `docker run -v /:/hostfs ...`.

You can also choose which parts of the host filesystem to mount, if you know
exactly what you'll need. e.g. `docker run -v /proc:/hostfs/proc`.

#### 2. Configure `root_path`

Configure `root_path` so the host\_metrics receiver knows where the root filesystem is.
Note: if running multiple instances of the host metrics receiver, they must all have
the same `root_path`.

Example:

```yaml theme={null}
receivers:
  host_metrics:
    root_path: /hostfs
```

## Resource attributes

Currently, the host\_metrics receiver does not set any Resource attributes on the exported metrics. However, if you want to set Resource attributes, you can provide them via environment variables via the [resource\_detection](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#environment-variable) processor. For example, you can add the following resource attributes to adhere to [Resource Semantic Conventions](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/):

```
export OTEL_RESOURCE_ATTRIBUTES="service.name=<the name of your service>,service.namespace=<the namespace of your service>,service.instance.id=<uuid of the instance>"
```

## Entity Events

**Entity Events as logs are experimental** and might eventually be replaced by the result of [the OTEP](https://github.com/open-telemetry/oteps/blob/main/text/entities/0256-entities-data-model.md#entity-events). For now, the host\_metrics receiver can send the host entity event as a log records. By default, the host\_metrics receiver sends periodic EntityState events every 5 minutes. You can change that by setting `metadata_collection_interval`. Entity Events as logs are experimental. The result of the OTEP might eventually replace that.

## Using a Collector not linked to glibc (Linux-specific)

This is a living section for known adverse behaviours within the `host_metrics` receiver when using a Collector on Linux that is not linked to `glibc` (which is always the case when using `CGO_ENABLED=0` and can be the case when using `CGO_ENABLED=1` under specific circumstances).

### Unable to resolve usernames when the system relies on NSS for user and group lookups

When a Collector is not linked to glibc, it can only resolve usernames and group names by directly parsing `/etc/passwd` and `/etc/group`. It has no awareness of the Name Service Switch (NSS) subsystem, which libc uses to delegate user and group lookups to pluggable backends including `nss-systemd`, `nss-ldap`, `sssd`, `winbind`, and more. As a result, any user or group whose record is provided exclusively by an NSS module rather than being present in `/etc/passwd` or `/etc/group` will fail to resolve, and the receiver will be unable to determine the username/owner of the given process.

This manifests most often as a failure to set the `process.owner` resource attribute in the `process` scraper. One concrete example is if a process is run as a systemd service using the `DynamicUser` feature. A Collector not linked to glibc will be incapable of resolving the username for the owner of that process because the `DynamicUser` feature leverages NSS (Name Service Switch) to resolve the username dynamically at user lookup time; a Go binary that uses the pure-Go `netgo` implementation is not NSS-aware and subsequently fails the user lookup.\
See more in the [demo repo](https://github.com/braydonk/poc-systemd-dynamic-user-netgo) created by `host_metrics` codeowner [@braydonk](https://github.com/braydonk).

## Configuration

### Example Configuration

```yaml theme={null}
host_metrics:
  scrapers:
    cpu:

host_metrics/customname:
  collection_interval: 30s
  scrapers:
    cpu:
    disk:
    load:
      cpu_average: true
    filesystem:
    memory:
    network:
      include:
        interfaces: ["test1"]
        match_type: "strict"
    nfs:
    paging:
    processes:
    process:
      include:
        names: ["test2", "test3"]
        match_type: "regexp"
    system:
```

***

*Last generated: 2026-07-06*