|
| 1 | +--- |
| 2 | +navigation_title: Host metrics receiver |
| 3 | +description: The host metrics receiver is an OpenTelemetry Collector component that collects system-level metrics from the host machine. |
| 4 | +applies_to: |
| 5 | + stack: |
| 6 | + serverless: |
| 7 | + observability: |
| 8 | + product: |
| 9 | + edot_collector: |
| 10 | +products: |
| 11 | + - id: elastic-agent |
| 12 | + - id: observability |
| 13 | + - id: edot-collector |
| 14 | +--- |
| 15 | + |
| 16 | +# Host metrics receiver |
| 17 | + |
| 18 | +The host metrics receiver collects system-level metrics from the host machine, including CPU usage, memory, disk I/O, network traffic, filesystem statistics, and process information. It provides essential infrastructure monitoring data that powers {{product.observability}}'s [Infrastructure dashboards](docs-content://reference/observability/observability-host-metrics.md). |
| 19 | + |
| 20 | +The receiver uses a set of specialized scrapers to gather metrics from different subsystems, making it flexible enough to collect only the metrics you need. |
| 21 | + |
| 22 | +## Default usage in EDOT |
| 23 | + |
| 24 | +The `hostmetricsreceiver` is included by default in the EDOT Collector for both standalone and Kubernetes deployments. |
| 25 | + |
| 26 | +### Standalone agent mode |
| 27 | + |
| 28 | +In standalone deployments, the host metrics receiver is part of the default [host metrics collection pipeline](../config/default-config-standalone.md#host-metrics-collection-pipeline). It collects system metrics at 60-second intervals and can be configured to export either: |
| 29 | + |
| 30 | +- Directly to {{es}} using the `elasticsearch` exporter (with optional ECS translation through the `elasticinframetrics` processor). |
| 31 | +- To the [{{motlp}}](opentelemetry://reference/motlp.md) using the `otlp` exporter. |
| 32 | + |
| 33 | +### Kubernetes deployment |
| 34 | + |
| 35 | +In Kubernetes, the host metrics receiver runs as part of the [DaemonSet collectors pipeline](../config/default-config-k8s.md#daemonset-collectors-pipeline) on every node to collect node-level host metrics at 60-second intervals. The receiver uses `root_path: /hostfs` (a mounted Kubernetes volume) to access the host's filesystem from within the container. |
| 36 | + |
| 37 | +For more details about the Kubernetes configuration, refer to [Default configuration (Kubernetes)](../config/default-config-k8s.md). |
| 38 | + |
| 39 | +### Common configuration |
| 40 | + |
| 41 | +Across all deployment modes, the default configuration collects CPU, memory, disk, filesystem, network, and load metrics. Process-level metrics are turned off by default to avoid generating excessive timeseries data. |
| 42 | + |
| 43 | +For more details on configuring metrics collection, refer to [Configure metrics collection guide](../config/configure-metrics-collection.md#host-metrics). |
| 44 | + |
| 45 | +## Example configuration |
| 46 | + |
| 47 | +The following example shows a typical host metrics receiver configuration with commonly used scrapers: |
| 48 | + |
| 49 | +```yaml |
| 50 | +receivers: |
| 51 | + hostmetrics: |
| 52 | + collection_interval: 60s |
| 53 | + root_path: /hostfs # Mounted host root filesystem |
| 54 | + scrapers: |
| 55 | + cpu: |
| 56 | + metrics: |
| 57 | + system.cpu.utilization: |
| 58 | + enabled: true |
| 59 | + system.cpu.logical.count: |
| 60 | + enabled: true |
| 61 | + memory: |
| 62 | + metrics: |
| 63 | + system.memory.utilization: |
| 64 | + enabled: true |
| 65 | + disk: {} |
| 66 | + filesystem: |
| 67 | + exclude_mount_points: |
| 68 | + mount_points: |
| 69 | + - /dev/* |
| 70 | + - /proc/* |
| 71 | + - /sys/* |
| 72 | + - /var/lib/docker/* |
| 73 | + - /var/lib/kubelet/* |
| 74 | + match_type: regexp |
| 75 | + exclude_fs_types: |
| 76 | + fs_types: |
| 77 | + - autofs |
| 78 | + - binfmt_misc |
| 79 | + - bpf |
| 80 | + - cgroup2 |
| 81 | + - configfs |
| 82 | + - debugfs |
| 83 | + - devpts |
| 84 | + - devtmpfs |
| 85 | + - overlay |
| 86 | + - proc |
| 87 | + - sysfs |
| 88 | + match_type: strict |
| 89 | + load: {} |
| 90 | + network: {} |
| 91 | + processes: {} |
| 92 | +``` |
| 93 | +
|
| 94 | +## Available scrapers |
| 95 | +
|
| 96 | +The host metrics receiver supports multiple scrapers, each focused on a different subsystem. You can enable only the scrapers you need: |
| 97 | +
|
| 98 | +| Scraper | Description | Key Metrics | |
| 99 | +|---------|-------------|-------------| |
| 100 | +| `cpu` | CPU usage and time | `system.cpu.time`, `system.cpu.utilization`, `system.cpu.logical.count` | |
| 101 | +| `memory` | Memory usage by state (used, free, cached, buffered) | `system.memory.usage`, `system.memory.utilization` | |
| 102 | +| `disk` | Disk I/O operations and throughput | `system.disk.io`, `system.disk.operations`, `system.disk.io_time` | |
| 103 | +| `filesystem` | Filesystem usage and inodes | `system.filesystem.usage`, `system.filesystem.utilization` | |
| 104 | +| `network` | Network traffic and errors | `system.network.io`, `system.network.errors`, `system.network.connections` | |
| 105 | +| `load` | System load average | `system.cpu.load_average.1m`, `system.cpu.load_average.5m`, `system.cpu.load_average.15m` | |
| 106 | +| `processes` | Process count by state | `system.processes.count`, `system.processes.created` | |
| 107 | +| `process` | Per-process metrics (CPU, memory, I/O) | `process.cpu.time`, `process.memory.usage`, `process.disk.io` | |
| 108 | +| `paging` | Paging and swap operations | `system.paging.operations`, `system.paging.usage` | |
| 109 | + |
| 110 | +## Key configuration options |
| 111 | + |
| 112 | +These are the most important settings when configuring the host metrics receiver: |
| 113 | + |
| 114 | +| Option | Description | |
| 115 | +|--------|-------------| |
| 116 | +| `collection_interval` | How often to scrape metrics (for example `60s`, `30s`). Defaults to `1m`. | |
| 117 | +| `root_path` | Root directory to use when running in a container. Set to `/hostfs` when mounting the host's root filesystem. | |
| 118 | +| `scrapers` | Map of scraper names to their configurations. Each scraper can be customized individually. | |
| 119 | +| `scrapers.<name>.metrics` | Control which specific metrics are enabled for a given scraper. | |
| 120 | + |
| 121 | +For the complete list of configuration options and scraper-specific settings, refer to the [contrib `hostmetricsreceiver` documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/README.md). |
| 122 | + |
| 123 | +## Best practices |
| 124 | + |
| 125 | +Follow these recommendations to get the most value from the host metrics receiver: |
| 126 | + |
| 127 | +* **Use the `root_path` setting when running in containers**: When the collector runs inside a container, it needs access to the host's filesystem to collect accurate metrics. Mount the host's root directory (typically at `/`) and set `root_path: /hostfs` in your configuration. This ensures the receiver reads from the host's `/proc`, `/sys`, and other system directories rather than the container's isolated filesystem. |
| 128 | + |
| 129 | +* **Filter out non-data filesystems and mount points**: To avoid collecting metrics from temporary, virtual, or container-specific filesystems, use the `exclude_mount_points` and `exclude_fs_types` options in the filesystem scraper. The default EDOT configuration already excludes common noise sources like `/dev/*`, `/proc/*`, `/sys/*`, overlay filesystems, and various pseudo-filesystems. |
| 130 | + |
| 131 | +* **Start with essential scrapers, then expand as needed**: Begin with the core scrapers (`cpu`, `memory`, `disk`, `filesystem`, `network`, `load`) that provide the foundation for infrastructure monitoring. These align with Elastic's Infrastructure dashboards and provide the most immediate value. Add additional scrapers like `paging` or `processes` based on your specific monitoring requirements. |
| 132 | + |
| 133 | +* **Be cautious when enabling the `process` scraper**: The `process` scraper collects per-process metrics, which can generate thousands of timeseries on systems with many running processes. This significantly increases storage requirements and can impact collector performance. Only enable it when you have a specific need for process-level visibility and have tested the volume impact in your environment. |
| 134 | + |
| 135 | +* **Align collection intervals with your monitoring needs**: The default 60-second interval balances freshness with overhead. For high-resolution monitoring, you can decrease to 30s or even 10s, but be aware this increases ingestion volume and associated costs. For less critical systems, increasing to 120s or 300s can reduce load. |
| 136 | + |
| 137 | +* **Enable specific metrics within scrapers for optimization**: Most scrapers expose a `metrics:` configuration block where you can enable or disable individual metrics. Use this to reduce cardinality and ingestion volume by collecting only the metrics you actually use in your dashboards and alerts. |
| 138 | + |
| 139 | + |
| 140 | +## Limitations |
| 141 | + |
| 142 | +Be aware of these constraints and behaviors when using the host metrics receiver: |
| 143 | + |
| 144 | +* **Process metrics are turned off by default**: The `process` scraper generates significant metric volume and is commented out in EDOT default configuration. Turning it on can substantially increase storage requirements and costs. Refer to the contrib [issue #39423](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/39423) for ongoing discussion about optimizing process metrics collection. |
| 145 | + |
| 146 | +* **Container deployment requires privileged access**: To collect host metrics from inside a container (Kubernetes DaemonSet), the collector must run with elevated privileges (`runAsUser: 0`) and have the host's `/proc` and `/sys` filesystems mounted. Refer to the [collecting host metrics from inside a container](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver#collecting-host-metrics-from-inside-a-container-linux-only) guide for details. |
| 147 | + |
| 148 | +* **Platform-specific metric availability**: Some metrics are only available on certain operating systems. For example, load average metrics work on Linux and macOS but not on Windows. The receiver logs warnings for unsupported metrics rather than failing. |
| 149 | + |
| 150 | +* **Filesystem scraper requires careful filtering**: Without proper exclusions, the filesystem scraper can collect metrics from hundreds of temporary, virtual, or container-specific mount points, generating unnecessary data. Always configure `exclude_mount_points` and `exclude_fs_types` appropriately. |
| 151 | + |
| 152 | +* **Metric format differs from {{agent}} system integration**: Host metrics collected through OpenTelemetry use different field names and structure compared to {{agent}}'s traditional system integration. The [`elasticinframetrics` processor](https://github.com/elastic/opentelemetry-collector-components/tree/main/processor/elasticinframetricsprocessor) is required to translate OTel metrics into ECS-compatible format for use with existing Infrastructure dashboards. |
| 153 | + |
| 154 | +## Resources |
| 155 | + |
| 156 | +* [Contrib component: hostmetricsreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/README.md) |
| 157 | +* [Configure metrics collection in EDOT](../config/configure-metrics-collection.md) |
| 158 | +* [{{product.observability}} host metrics reference](https://www.elastic.co/docs/reference/observability/observability-host-metrics) |
| 159 | + |
0 commit comments