hostmetricsreceiver

README

Host Metrics Receiver

Status
Stability	beta
Supported pipeline types	metrics
Distributions	core, contrib

The Host Metrics receiver generates metrics about the host system scraped from various sources. This is intended to be used when the collector is deployed as an agent.

Getting Started

The collection interval and the categories of metrics to be scraped can be configured:

hostmetrics:
  collection_interval: <duration> # default = 1m
  scrapers:
    <scraper1>:
    <scraper2>:
    ...

The available scrapers are:

Scraper	Supported OSs	Description
cpu	All except Mac[1]	CPU utilization metrics
disk	All except Mac[1]	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
paging	All	Paging/Swap space utilization and I/O metrics
processes	Linux	Process count metrics
process	Linux & Windows	Per process CPU, Memory, and Disk I/O metrics

Notes

^[1] Not supported on Mac when compiled without cgo which is the default.

Several scrapers support additional configuration:

Disk

disk:
  <include|exclude>:
    devices: [ <device name>, ... ]
    match_type: <strict|regexp>

File System

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>

Load

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

load:
  cpu_average: <false|true>

Network

network:
  <include|exclude>:
    interfaces: [ <interface name>, ... ]
    match_type: <strict|regexp>

Process

process:
  <include|exclude>:
    names: [ <process name>, ... ]
    match_type: <strict|regexp>
  mute_process_name_error: <true|false>
  scrape_process_delay: <time>

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.

Different Frequencies

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

receivers:
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
      memory:

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

service:
  pipelines:
    metrics:
      receivers: [hostmetrics, hostmetrics/disk]

Feature gate configurations

Transition from metrics with "direction" attribute

Some host metrics reported are transitioning from being reported with a direction attribute to being reported with the direction included in the metric name to adhere to the OpenTelemetry specification (https://github.com/open-telemetry/opentelemetry-specification/pull/2617):

• disk scraper metrics:
  • system.disk.io will become:
    • system.disk.io.read
    • system.disk.io.write
  • system.disk.operations will become:
    • system.disk.operations.read
    • system.disk.operations.write
  • system.disk.operation_time will become:
    • system.disk.operation_time.read
    • system.disk.operation_time.write
  • system.disk.merged will become:
    • system.disk.merged.read
    • system.disk.merged.write
• network scraper metrics:
  • system.network.dropped will become:
    • system.network.dropped.receive
    • system.network.dropped.transmit
  • system.network.errors will become:
    • system.network.errors.receive
    • system.network.errors.transmit
  • system.network.io will become:
    • system.network.io.receive
    • system.network.io.transmit
  • system.network.packets will become:
    • system.network.packets.receive
    • system.network.packets.transmit
• paging scraper metrics:
  • system.paging.operations will become:
    • system.paging.operations.page_in
    • system.paging.operations.page_out
• process scraper metrics:
  • process.disk.io will become:
    • process.disk.io.read
    • process.disk.io.write

The following feature gates control the transition process:

• receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute: controls if the new metrics without direction attribute are emitted by the receiver.
• receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute: controls if the deprecated metrics with direction attribute are emitted by the receiver.

Transition schedule:

1. v0.55.0, July 2022:

• Most of the scrapers except for disk scraper can emit the new metrics without the direction attribute if feature gates enabled.
• receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute is enabled by default.
• receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute is disabled by default.

1. v0.56.0, July 2022:

• The new metrics are available for all scrapers, but disabled by default, they can be enabled with the feature gates.
• The old metrics with direction attribute are deprecated with a warning.
• receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute is enabled by default.
• receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute is disabled by default.

1. v0.58.0, August 2022:

• The new metrics are enabled by default, deprecated metrics disabled, they can be enabled with the feature gates.
• receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute is disabled by default.
• receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute is enabled by default.

1. v0.60.0, September 2022:

• The feature gates are removed.
• The new metrics without direction attribute are always emitted.
• The deprecated metrics with direction attribute are no longer available.

Usage:

To enable the new metrics without direction attribute and disable the deprecated metrics, run OTel Collector with the following arguments:

otelcol --feature-gates=-receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute,+receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute

It's also possible to emit both the deprecated and the new metrics:

otelcol --feature-gates=+receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute,+receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute

If both feature gates are enabled, each particular metric can be disabled with the user settings, for example:

receivers:
  hostmetrics:
    scrapers:
      paging:
        metrics:
          system.paging.operations:
            enabled: false

More information:

• https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11815
• https://github.com/open-telemetry/opentelemetry-specification/pull/2617

Documentation

Overview

Package hostmetricsreceiver reads metrics like CPU usage, disk usage, and network usage from the host.

Index

• func NewFactory() component.ReceiverFactory
• type Config
  • func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error
  • func (cfg *Config) Validate() error

Functions

func NewFactory

func NewFactory() component.ReceiverFactory

NewFactory creates a new factory for host metrics receiver.

Types

type Config

type Config struct {
	scraperhelper.ScraperControllerSettings `mapstructure:",squash"`
	Scrapers                                map[string]internal.Config `mapstructure:"-"`
}

Config defines configuration for HostMetrics receiver.

func (*Config) Unmarshal

func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error

Unmarshal a config.Parser into the config struct.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks the receiver configuration is valid