> ## Documentation Index > Fetch the complete documentation index at: https://otel.fyi/llms.txt > Use this file to discover all available pages before exploring further. # Dockerstats > OpenTelemetry receiver for Dockerstats # Dockerstats Receiver ![Status](https://img.shields.io/badge/status-alpha-red) **Available in:** `contrib` **Maintainers:** [@jamesmoessis](https://github.com/jamesmoessis) **Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver) ## Supported Telemetry ![Metrics](https://img.shields.io/badge/metrics-alpha-green) ## 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](https://golang.org/pkg/regexp/), or [globs](https://github.com/gobwas/glob) 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](https://docs.docker.com/engine/api/). * `metrics` (defaults at [./documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver/documentation.md)): Enables/disables individual metrics. See [./documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver/documentation.md) for full detail. Example: ```yaml theme={null} 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver/config.go) with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver/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: ```bash theme={null} 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: ```bash theme={null} # 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](https://github.com/Tecnativa/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](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/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: ```yaml theme={null} 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/9794). | Breaking Change | Action | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Many metrics are no longer emitted by default. | See [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver/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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#opentelemetry-protocol-data-model-consumer-recommendations) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver/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 | Values | | -------------- | --------------------------------------------------- | ------ | ------ | | `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 ```yaml theme={null} 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-07-06*