Dockerstats Receiver

Available in: contrib Maintainers: @jamesmoessis Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

:information_source: Requires Docker API version 1.25+

Configuration

The following settings are optional:

endpoint (default = unix:///var/run/docker.sock (Linux) , default = npipe:////./pipe/docker_engine (Windows) ): Address to reach the desired Docker daemon.
collection_interval (default = 10s): The interval at which to gather container stats.
initial_delay (default = 1s): defines how long this receiver waits before starting.
container_labels_to_metric_labels (no default): A map of Docker container label names whose label values to use as the specified metric label key.
env_vars_to_metric_labels (no default): A map of Docker container environment variables whose values to use as the specified metric label key.
excluded_images (no default, all running containers monitored): A list of strings, regexes, or globs whose referent container image names will not be among the queried containers. !-prefixed negations are possible for all item types to signify that only unmatched container image names should be excluded.
- Regexes must be placed between / characters: /my?egex/. Negations are to be outside the forward slashes: !/my?egex/ will exclude all containers whose name doesn’t match the compiled regex my?egex.
- Globs are non-regex items (e.g. /items/) containing any of the following: *[]{}?. Negations are supported: !my*container will exclude all containers whose image name doesn’t match the blob my*container.
timeout (default = 5s): The request timeout for any docker daemon query.
api_version (default = auto-negotiate): The Docker client API version (must be 1.25+). When not specified, the client automatically negotiates the highest mutually supported API version with the Docker daemon. To pin a specific version, set it as a string, not a float (e.g. "1.44" instead of 1.44). Docker API versions.
metrics (defaults at ./documentation.md): Enables/disables individual metrics. See ./documentation.md for full detail.

Example:

receivers:
  docker_stats:
    endpoint: http://example.com/
    collection_interval: 2s
    timeout: 20s
    api_version: "1.25"
    container_labels_to_metric_labels:
      my.container.label: my-metric-label
      my.other.container.label: my-other-metric-label
    env_vars_to_metric_labels:
      MY_ENVIRONMENT_VARIABLE: my-metric-label
      MY_OTHER_ENVIRONMENT_VARIABLE: my-other-metric-label
    excluded_images:
      - undesired-container
      - /.*undesired.*/
      - another-*-container
    metrics:
      container.cpu.usage.percpu:
        enabled: true
      container.network.io.usage.tx_dropped:
        enabled: false

The full list of settings exposed for this receiver are documented in config.go with detailed sample configurations in testdata/config.yaml.

Docker Socket Permissions

Requirements

This receiver requires access to the Docker daemon socket to query container statistics. The Docker socket requires specific permissions:

Linux (/var/run/docker.sock): Accessible by root user or members of the docker group
Windows (npipe:////./pipe/docker_engine): Requires appropriate named pipe permissions

Since version 0.40.0, official OpenTelemetry Collector images run as a non-root user for security. This creates a permission conflict when accessing the Docker socket.

Permission Solutions

Grant Docker Group Access

On Linux, grant the collector process access to the docker group by adding the host’s docker group ID as a supplementary group to the container process:

getent group docker

# Linux example - Run with docker group (replace 999 with your docker group GID from above)
docker run --group-add 999 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  otel/opentelemetry-collector-contrib:latest

Note: The --group-add flag adds the host’s group ID as a supplementary group to the container process. This works because the mounted socket retains the host’s group ownership. If you have user namespaces enabled in Docker, additional configuration may be required.

Run as Root

If running as root is acceptable for your environment:

# Linux example
docker run -u 0 -v /var/run/docker.sock:/var/run/docker.sock \
  otel/opentelemetry-collector-contrib:latest

Note: Running as root is not recommended for production environments.

Alternative Approaches

For enhanced security, consider:

Using a Docker API proxy (e.g. docker-socket-proxy) that restricts access to only required endpoints
Running this receiver in an isolated collector instance with elevated privileges that only exports data (does not expose receiver ports like OTLP or Zipkin), forwarding metrics to your main collector via OTLP. This reduces the attack surface and RCE risk on the privileged container.

For more information, see issue #11791.

Deprecations

Transition to cpu utilization metric name aligned with OpenTelemetry specification

The Docker Stats receiver has been emitting the following cpu memory metric:

[container.cpu.percent] for the percentage of CPU used by the container,

This is in conflict with the OpenTelemetry specification, which defines [container.cpu.utilization] as the name for this metric. To align the emitted metric names with the OpenTelemetry specification, the following process will be followed to phase out the old metrics:

Between v0.79.0 and v0.86.0, the new metric is introduced and the old metric is marked as deprecated. Only the old metric are emitted by default.
In v0.88.0, the old metric is disabled and the new one enabled by default.
In v0.89.0 and up, the old metric is removed.

To change the enabled state for the specific metrics, use the standard configuration options that are available for all metrics. Here’s an example configuration to disable the old metrics and enable the new metrics:

receivers:
  docker_stats:
    metrics:
      container.cpu.percent:
        enabled: false
      container.cpu.utilization:
        enabled: true

Migrating from ScraperV1 to ScraperV2

Note: These changes are now in effect and ScraperV1 have been removed as of v0.71. There are some breaking changes from ScraperV1 to ScraperV2. The work done for these changes is tracked in #9794.

Breaking Change	Action
Many metrics are no longer emitted by default.	See documentation.md to see which metrics are enabled by default. Enable/disable as desired.
BlockIO metrics names changed. The type of operation is no longer in the metric name suffix, and is now in an attribute. For example `container.blockio.io_merged_recursive.read` becomes `container.blockio.io_merged_recursive` with an `operation:read` attribute.	Be aware of the metric name changes and make any adjustments to what your downstream expects from BlockIO metrics.
Memory metrics measured in Bytes are now non-monotonic sums instead of gauges.	Most likely there is no action. The aggregation type is different but the values are the same. Be aware of how your downstream handles gauges vs non-monotonic sums.
Config option `provide_per_core_cpu_metrics` has been removed.	Enable the `container.cpu.usage.percpu` metric as per documentation.md.

Metrics

Metric Name	Description	Unit	Type	Attributes
❌ `container.blockio.io_merged_recursive`	Number of bios/requests merged into requests belonging to this cgroup and its descendant cgroups (Only available with cgroups v1).	{operations}	Counter	device_major, device_minor, operation
❌ `container.blockio.io_queued_recursive`	Number of requests queued up for this cgroup and its descendant cgroups (Only available with cgroups v1).	{operations}	Counter	device_major, device_minor, operation
✅ `container.blockio.io_service_bytes_recursive`	Number of bytes transferred to/from the disk by the group and descendant groups.	By	Counter	device_major, device_minor, operation
❌ `container.blockio.io_service_time_recursive`	Total amount of time in nanoseconds between request dispatch and request completion for the IOs done by this cgroup and descendant cgroups (Only available with cgroups v1).	ns	Counter	device_major, device_minor, operation
❌ `container.blockio.io_serviced_recursive`	Number of IOs (bio) issued to the disk by the group and descendant groups (Only available with cgroups v1).	{operations}	Counter	device_major, device_minor, operation
❌ `container.blockio.io_time_recursive`	Disk time allocated to cgroup (and descendant cgroups) per device in milliseconds (Only available with cgroups v1).	ms	Counter	device_major, device_minor, operation
❌ `container.blockio.io_wait_time_recursive`	Total amount of time the IOs for this cgroup (and descendant cgroups) spent waiting in the scheduler queues for service (Only available with cgroups v1).	ns	Counter	device_major, device_minor, operation
❌ `container.blockio.sectors_recursive`	Number of sectors transferred to/from disk by the group and descendant groups (Only available with cgroups v1).	{sectors}	Counter	device_major, device_minor, operation
❌ `container.cpu.limit`	CPU limit set for the container.	{cpus}	Gauge
❌ `container.cpu.logical.count`	Number of cores available to the container.	{cpus}	Gauge
❌ `container.cpu.shares`	CPU shares set for the container.	1	Gauge
❌ `container.cpu.throttling_data.periods`	Number of periods with throttling active.	{periods}	Counter
❌ `container.cpu.throttling_data.throttled_periods`	Number of periods when the container hits its throttling limit.	{periods}	Counter
❌ `container.cpu.throttling_data.throttled_time`	Aggregate time the container was throttled.	ns	Counter
✅ `container.cpu.usage.kernelmode`	Time spent by tasks of the cgroup in kernel mode (Linux). Time spent by all container processes in kernel mode (Windows).	ns	Counter
❌ `container.cpu.usage.percpu`	Per-core CPU usage by the container (Only available with cgroups v1).	ns	Counter	core
❌ `container.cpu.usage.system`	System CPU usage, as reported by docker.	ns	Counter
✅ `container.cpu.usage.total`	Total CPU time consumed.	ns	Counter
✅ `container.cpu.usage.usermode`	Time spent by tasks of the cgroup in user mode (Linux). Time spent by all container processes in user mode (Windows).	ns	Counter
✅ `container.cpu.utilization`	Percent of CPU used by the container.	1	Gauge
❌ `container.memory.active_anon`	The amount of anonymous memory that has been identified as active by the kernel.	By	UpDownCounter
❌ `container.memory.active_file`	Cache memory that has been identified as active by the kernel.	By	UpDownCounter
❌ `container.memory.anon`	Amount of memory used in anonymous mappings such as brk(), sbrk(), and mmap(MAP_ANONYMOUS) (Only available with cgroups v2).	By	UpDownCounter
❌ `container.memory.cache`	The amount of memory used by the processes of this control group that can be associated precisely with a block on a block device (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.dirty`	Bytes that are waiting to get written back to the disk, from this cgroup (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.fails`	Number of times the memory limit was hit.	{fails}	Counter
✅ `container.memory.file`	Amount of memory used to cache filesystem data, including tmpfs and shared memory (Only available with cgroups v2).	By	UpDownCounter
❌ `container.memory.hierarchical_memory_limit`	The maximum amount of physical memory that can be used by the processes of this control group (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.hierarchical_memsw_limit`	The maximum amount of RAM + swap that can be used by the processes of this control group (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.inactive_anon`	The amount of anonymous memory that has been identified as inactive by the kernel.	By	UpDownCounter
❌ `container.memory.inactive_file`	Cache memory that has been identified as inactive by the kernel.	By	UpDownCounter
❌ `container.memory.mapped_file`	Indicates the amount of memory mapped by the processes in the control group (Only available with cgroups v1).	By	UpDownCounter
✅ `container.memory.percent`	Percentage of memory used. Not supported on Windows.	1	Gauge
❌ `container.memory.pgfault`	Indicate the number of times that a process of the cgroup triggered a page fault.	{faults}	Counter
❌ `container.memory.pgmajfault`	Indicate the number of times that a process of the cgroup triggered a major fault.	{faults}	Counter
❌ `container.memory.pgpgin`	Number of pages read from disk by the cgroup (Only available with cgroups v1).	{operations}	Counter
❌ `container.memory.pgpgout`	Number of pages written to disk by the cgroup (Only available with cgroups v1).	{operations}	Counter
❌ `container.memory.rss`	The amount of memory that doesn’t correspond to anything on disk: stacks, heaps, and anonymous memory maps (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.rss_huge`	Number of bytes of anonymous transparent hugepages in this cgroup (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_active_anon`	The amount of anonymous memory that has been identified as active by the kernel. Includes descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_active_file`	Cache memory that has been identified as active by the kernel. Includes descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
✅ `container.memory.total_cache`	Total amount of memory used by the processes of this cgroup (and descendants) that can be associated with a block on a block device. Also accounts for memory used by tmpfs (Only available with cgroups v1). Not supported on Windows.	By	UpDownCounter
❌ `container.memory.total_dirty`	Bytes that are waiting to get written back to the disk, from this cgroup and descendants (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_inactive_anon`	The amount of anonymous memory that has been identified as inactive by the kernel. Includes descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_inactive_file`	Cache memory that has been identified as inactive by the kernel. Includes descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_mapped_file`	Indicates the amount of memory mapped by the processes in the control group and descendant groups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_pgfault`	Indicate the number of times that a process of the cgroup (or descendant cgroups) triggered a page fault (Only available with cgroups v1).	{faults}	Counter
❌ `container.memory.total_pgmajfault`	Indicate the number of times that a process of the cgroup (or descendant cgroups) triggered a major fault (Only available with cgroups v1).	{faults}	Counter
❌ `container.memory.total_pgpgin`	Number of pages read from disk by the cgroup and descendant groups (Only available with cgroups v1).	{operations}	Counter
❌ `container.memory.total_pgpgout`	Number of pages written to disk by the cgroup and descendant groups (Only available with cgroups v1).	{operations}	Counter
❌ `container.memory.total_rss`	The amount of memory that doesn’t correspond to anything on disk: stacks, heaps, and anonymous memory maps. Includes descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_rss_huge`	Number of bytes of anonymous transparent hugepages in this cgroup and descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_unevictable`	The amount of memory that cannot be reclaimed. Includes descendant cgroups (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.total_writeback`	Number of bytes of file/anon cache that are queued for syncing to disk in this cgroup and descendants (Only available with cgroups v1).	By	UpDownCounter
❌ `container.memory.unevictable`	The amount of memory that cannot be reclaimed.	By	UpDownCounter
✅ `container.memory.usage.limit`	Memory limit of the container. Not supported on Windows.	By	UpDownCounter
❌ `container.memory.usage.max`	Maximum memory usage.	By	UpDownCounter
✅ `container.memory.usage.total`	Memory usage of the container. This excludes the cache.	By	UpDownCounter
❌ `container.memory.writeback`	Number of bytes of file/anon cache that are queued for syncing to disk in this cgroup (Only available with cgroups v1).	By	UpDownCounter
✅ `container.network.io.usage.rx_bytes`	Bytes received by the container.	By	Counter	interface
✅ `container.network.io.usage.rx_dropped`	Incoming packets dropped.	{packets}	Counter	interface
❌ `container.network.io.usage.rx_errors`	Received errors. Not supported on Windows.	{errors}	Counter	interface
❌ `container.network.io.usage.rx_packets`	Packets received.	{packets}	Counter	interface
✅ `container.network.io.usage.tx_bytes`	Bytes sent.	By	Counter	interface
✅ `container.network.io.usage.tx_dropped`	Outgoing packets dropped.	{packets}	Counter	interface
❌ `container.network.io.usage.tx_errors`	Sent errors. Not supported on Windows.	{errors}	Counter	interface
❌ `container.network.io.usage.tx_packets`	Packets sent.	{packets}	Counter	interface
❌ `container.pids.count`	Number of pids in the container’s cgroup.	{pids}	UpDownCounter
❌ `container.pids.limit`	Maximum number of pids in the container’s cgroup.	{pids}	UpDownCounter
❌ `container.restarts`	Number of restarts for the container.	{restarts}	Counter
❌ `container.uptime`	Time elapsed since container start time.	s	Gauge

Attributes

Attribute Name	Description	Type
`core`	The CPU core number when utilising per-CPU metrics.	string
`device_major`	Device major number for block IO operations.	string
`device_minor`	Device minor number for block IO operations.	string
`interface`	Network interface.	string
`operation`	Type of BlockIO operation.	string

Resource Attributes

Attribute Name	Description	Type	Enabled
`container.command_line`	The full command executed by the container.	string	❌
`container.hostname`	The hostname of the container.	string	✅
`container.id`	The ID of the container.	string	✅
`container.image.id`	The ID of the container image.	string	❌
`container.image.name`	The name of the docker image in use by the container.	string	✅
`container.name`	The name of the container.	string	✅
`container.runtime`	The runtime of the container. For this receiver, it will always be ‘docker’.	string	✅

Configuration

Example Configuration

docker_stats:
docker_stats/tls:
  endpoint: https://example.com/
  tls:
    insecure_skip_verify: true
docker_stats/allsettings:
  endpoint: http://example.com/
  collection_interval: 2s
  timeout: 20s
  api_version: '1.40'
  container_labels_to_metric_labels:
    my.container.label: my-metric-label
    my.other.container.label: my-other-metric-label
  env_vars_to_metric_labels:
    MY_ENVIRONMENT_VARIABLE: my-metric-label
    MY_OTHER_ENVIRONMENT_VARIABLE: my-other-metric-label
  excluded_images:
    - undesired-container
    - another-*-container
  metrics:
    container.cpu.usage.system:
      enabled: false
    container.memory.total_rss:
      enabled: true

Last generated: 2026-04-20

Documentation Index

​Dockerstats Receiver

​Supported Telemetry

​Overview

​Configuration

​Docker Socket Permissions

​Requirements

​Permission Solutions

​Grant Docker Group Access

​Run as Root

​Alternative Approaches

​Deprecations

​Transition to cpu utilization metric name aligned with OpenTelemetry specification

​Migrating from ScraperV1 to ScraperV2

​Metrics

​Attributes

​Resource Attributes

​Configuration

​Example Configuration

Dockerstats Receiver

Supported Telemetry

Overview

Configuration

Docker Socket Permissions

Requirements

Permission Solutions

Grant Docker Group Access

Run as Root

Alternative Approaches

Deprecations

Transition to cpu utilization metric name aligned with OpenTelemetry specification

Migrating from ScraperV1 to ScraperV2

Metrics

Attributes

Resource Attributes

Configuration

Example Configuration