--- title: Telegraf Documentation description: Telegraf plugin for collecting metrics from Docker url: https://docs.influxdata.com/telegraf/v1/input-plugins/docker/ estimated_tokens: 5957 product: Telegraf version: v1 --- - Telegraf v0.1.9+ # Docker Input Plugin This plugin uses the [Docker Engine API](https://docs.docker.com/engine/api) to gather metrics on running Docker containers. Make sure Telegraf has sufficient permissions to access the configured endpoint. **Introduced in:** Telegraf v0.1.9 **Tags:** containers **OS support:** all ## Global configuration options Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details. ## Configuration ```toml # Read metrics about docker containers [[inputs.docker]] ## Endpoint, either "tcp://[ip]:[port]" for TCP, "unix:///" for socket ## or "ENV" for using environment variables (i.e., docker-machine) # endpoint = "unix:///var/run/docker.sock" ## Collect Swarm metrics (desired_replicas, running_replicas) ## Note: Configure this for one of the manager nodes in a Swarm cluster only ## as you will see duplicate metrics otherwise. # gather_services = false ## Use container ID hostname as source (trimmed to 12 characters) # source_tag = false ## Containers to include and exclude accepting wildcards; all if empty # container_name_include = [] # container_name_exclude = [] ## Container states to include and exclude accepting wildcards; available: ## "created", "restarting", "running", "removing", "paused", "exited", "dead" # container_state_include = ["running"] # container_state_exclude = [] ## Objects to include for disk usage query; available: ## "container", "image", "volume" # storage_objects = [] ## Timeout for docker list, info, and stats commands # timeout = "5s" ## Podman compatibility settings (auto-enabled when Podman detected) ## Cache TTL for accurate CPU percentage calculation. Should be higher than ## your collection interval for accurate measurements. Zero will keep cache ## entries forever (not recommended for dynamic environments). # podman_cache_ttl = "60s" ## Emit per-device metric for the given classes; available: ## 'cpu' (cpu0, ...), 'blkio' (8:0, ...) and 'network' (eth0, ...) # perdevice_include = ["cpu"] ## Emit accumulated metrics for the given classes; available: ## 'cpu', 'blkio' and 'network' # total_include = ["cpu", "blkio", "network"] ## Container labels to include as tags accepting wildcards; all if empty # docker_label_include = [] # docker_label_exclude = [] ## Which environment variables should we use as a tag ## e.g. tag_env = ["JAVA_HOME", "HEAP_SIZE"] # tag_env = [] ## Optional TLS Config # tls_ca = "/etc/telegraf/ca.pem" # tls_cert = "/etc/telegraf/cert.pem" # tls_key = "/etc/telegraf/key.pem" ## Use TLS but skip chain & host verification # insecure_skip_verify = false ``` ### Environment Configuration When using the `"ENV"` endpoint, the connection is configured using the [cli Docker environment variables](https://godoc.org/github.com/moby/moby/client#NewEnvClient). ### Security Giving telegraf access to the Docker daemon expands the [attack surface](https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface) that could result in an attacker gaining root access to a machine. This is especially relevant if the telegraf configuration can be changed by untrusted users. ### Podman Compatibility This plugin is compatible with Podman through its Docker-compatible API. When connected to Podman: - The plugin automatically detects Podman by examining the server version and endpoint - Uses an intelligent caching mechanism to calculate accurate CPU percentages - Configure Podman socket endpoint, for example: `endpoint = "unix:///run/podman/podman.sock"` ### Docker Daemon Permissions Typically, telegraf must be given permission to access the docker daemon unix socket when using the default endpoint. This can be done by adding the `telegraf` unix user (created when installing a Telegraf package) to the `docker` unix group with the following command: ```shell sudo usermod -aG docker telegraf ``` If telegraf is run within a container, the unix socket will need to be exposed within the telegraf container. This can be done in the docker CLI by add the option `-v /var/run/docker.sock:/var/run/docker.sock` or adding the following lines to the telegraf container definition in a docker compose file. Additionally docker `telegraf` user must be assigned to `docker` group id from host: ```yaml user: telegraf: volumes: - /var/run/docker.sock:/var/run/docker.sock ``` ### source tag Selecting the containers measurements can be tricky if you have many containers with the same name. To alleviate this issue you can set the below value to `true` ```toml source_tag = true ``` This will cause all measurements to have the `source` tag be set to the first 12 characters of the container id. The first 12 characters is the common hostname for containers that have no explicit hostname set, as defined by docker. ### Kubernetes Labels Kubernetes may add many labels to your containers, if they are not needed you may prefer to exclude them: ```json docker_label_exclude = ["annotation.kubernetes*"] ``` ### Docker-compose Labels Docker-compose will add labels to your containers. You can limit restrict labels to selected ones, e.g. ```json docker_label_include = [ "com.docker.compose.config-hash", "com.docker.compose.container-number", "com.docker.compose.oneoff", "com.docker.compose.project", "com.docker.compose.service", ] ``` ## Metrics - docker - tags: - unit - engine\_host - server\_version - fields: - n\_used\_file\_descriptors - n\_cpus - n\_containers - n\_containers\_running - n\_containers\_stopped - n\_containers\_paused - n\_images - n\_goroutines - n\_listener\_events - memory\_total - pool\_blocksize (requires devicemapper storage driver) (deprecated see: `docker_devicemapper`) The `docker_data` and `docker_metadata` measurements are available only for some storage drivers such as devicemapper. - docker\_data (deprecated see: `docker_devicemapper`) - tags: - unit - engine\_host - server\_version - fields: - available - total - used - docker\_metadata (deprecated see: `docker_devicemapper`) - tags: - unit - engine\_host - server\_version - fields: - available - total - used The above measurements for the devicemapper storage driver can now be found in the new `docker_devicemapper` measurement - docker\_devicemapper - tags: - engine\_host - server\_version - pool\_name - fields: - pool\_blocksize\_bytes - data\_space\_used\_bytes - data\_space\_total\_bytes - data\_space\_available\_bytes - metadata\_space\_used\_bytes - metadata\_space\_total\_bytes - metadata\_space\_available\_bytes - thin\_pool\_minimum\_free\_space\_bytes - docker\_container\_mem - tags: - engine\_host - server\_version - container\_image - container\_name - container\_status - container\_version - fields: - total\_pgmajfault - cache - mapped\_file - total\_inactive\_file - pgpgout - rss - total\_mapped\_file - writeback - unevictable - pgpgin - total\_unevictable - pgmajfault - total\_rss - total\_rss\_huge - total\_writeback - total\_inactive\_anon - rss\_huge - hierarchical\_memory\_limit - total\_pgfault - total\_active\_file - active\_anon - total\_active\_anon - total\_pgpgout - total\_cache - inactive\_anon - active\_file - pgfault - inactive\_file - total\_pgpgin - max\_usage - usage - failcnt - limit - container\_id - docker\_container\_cpu - tags: - engine\_host - server\_version - container\_image - container\_name - container\_status - container\_version - cpu - fields: - throttling\_periods - throttling\_throttled\_periods - throttling\_throttled\_time - usage\_in\_kernelmode - usage\_in\_usermode - usage\_system - usage\_total - usage\_percent - container\_id - docker\_container\_net - tags: - engine\_host - server\_version - container\_image - container\_name - container\_status - container\_version - network - fields: - rx\_dropped - rx\_bytes - rx\_errors - tx\_packets - tx\_dropped - rx\_packets - tx\_errors - tx\_bytes - container\_id - docker\_container\_blkio - tags: - engine\_host - server\_version - container\_image - container\_name - container\_status - container\_version - device - fields: - io\_service\_bytes\_recursive\_async - io\_service\_bytes\_recursive\_read - io\_service\_bytes\_recursive\_sync - io\_service\_bytes\_recursive\_total - io\_service\_bytes\_recursive\_write - io\_serviced\_recursive\_async - io\_serviced\_recursive\_read - io\_serviced\_recursive\_sync - io\_serviced\_recursive\_total - io\_serviced\_recursive\_write - container\_id The `docker_container_health` measurements report on a containers [HEALTHCHECK](https://docs.docker.com/engine/reference/builder/#healthcheck) status if configured. - docker\_container\_health (container must use the HEALTHCHECK) - tags: - engine\_host - server\_version - container\_image - container\_name - container\_status - container\_version - fields: - health\_status (string) - failing\_streak (integer) - docker\_container\_status - tags: - engine\_host - server\_version - container\_image - container\_name - container\_status - container\_version - fields: - container\_id - oomkilled (boolean) - pid (integer) - exitcode (integer) - started\_at (integer) - finished\_at (integer) - uptime\_ns (integer) - docker\_swarm - tags: - service\_id - service\_name - service\_mode - fields: - tasks\_desired - tasks\_running - docker\_disk\_usage - tags: - engine\_host - server\_version - container\_name - container\_image - container\_version - image\_id - image\_name - image\_version - volume\_name - fields: - size\_rw - size\_root\_fs - size - shared\_size ## Example Output ```text docker,engine_host=debian-stretch-docker,server_version=17.09.0-ce n_containers=6i,n_containers_paused=0i,n_containers_running=1i,n_containers_stopped=5i,n_cpus=2i,n_goroutines=41i,n_images=2i,n_listener_events=0i,n_used_file_descriptors=27i 1524002041000000000 docker,engine_host=debian-stretch-docker,server_version=17.09.0-ce,unit=bytes memory_total=2101661696i 1524002041000000000 docker_container_mem,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,engine_host=debian-stretch-docker,server_version=17.09.0-ce active_anon=8327168i,active_file=2314240i,cache=27402240i,container_id="adc4ba9593871bf2ab95f3ffde70d1b638b897bb225d21c2c9c84226a10a8cf4",hierarchical_memory_limit=9223372036854771712i,inactive_anon=0i,inactive_file=25088000i,limit=2101661696i,mapped_file=20582400i,max_usage=36646912i,pgfault=4193i,pgmajfault=214i,pgpgin=9243i,pgpgout=520i,rss=8327168i,rss_huge=0i,total_active_anon=8327168i,total_active_file=2314240i,total_cache=27402240i,total_inactive_anon=0i,total_inactive_file=25088000i,total_mapped_file=20582400i,total_pgfault=4193i,total_pgmajfault=214i,total_pgpgin=9243i,total_pgpgout=520i,total_rss=8327168i,total_rss_huge=0i,total_unevictable=0i,total_writeback=0i,unevictable=0i,usage=36528128i,usage_percent=0.4342225020025297,writeback=0i 1524002042000000000 docker_container_cpu,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,cpu=cpu-total,engine_host=debian-stretch-docker,server_version=17.09.0-ce container_id="adc4ba9593871bf2ab95f3ffde70d1b638b897bb225d21c2c9c84226a10a8cf4",throttling_periods=0i,throttling_throttled_periods=0i,throttling_throttled_time=0i,usage_in_kernelmode=40000000i,usage_in_usermode=100000000i,usage_percent=0,usage_system=6394210000000i,usage_total=117319068i 1524002042000000000 docker_container_cpu,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,cpu=cpu0,engine_host=debian-stretch-docker,server_version=17.09.0-ce container_id="adc4ba9593871bf2ab95f3ffde70d1b638b897bb225d21c2c9c84226a10a8cf4",usage_total=20825265i 1524002042000000000 docker_container_cpu,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,cpu=cpu1,engine_host=debian-stretch-docker,server_version=17.09.0-ce container_id="adc4ba9593871bf2ab95f3ffde70d1b638b897bb225d21c2c9c84226a10a8cf4",usage_total=96493803i 1524002042000000000 docker_container_net,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,engine_host=debian-stretch-docker,network=eth0,server_version=17.09.0-ce container_id="adc4ba9593871bf2ab95f3ffde70d1b638b897bb225d21c2c9c84226a10a8cf4",rx_bytes=1576i,rx_dropped=0i,rx_errors=0i,rx_packets=20i,tx_bytes=0i,tx_dropped=0i,tx_errors=0i,tx_packets=0i 1524002042000000000 docker_container_blkio,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,device=254:0,engine_host=debian-stretch-docker,server_version=17.09.0-ce container_id="adc4ba9593871bf2ab95f3ffde70d1b638b897bb225d21c2c9c84226a10a8cf4",io_service_bytes_recursive_async=27398144i,io_service_bytes_recursive_read=27398144i,io_service_bytes_recursive_sync=0i,io_service_bytes_recursive_total=27398144i,io_service_bytes_recursive_write=0i,io_serviced_recursive_async=529i,io_serviced_recursive_read=529i,io_serviced_recursive_sync=0i,io_serviced_recursive_total=529i,io_serviced_recursive_write=0i 1524002042000000000 docker_container_health,container_image=telegraf,container_name=zen_ritchie,container_status=running,container_version=unknown,engine_host=debian-stretch-docker,server_version=17.09.0-ce failing_streak=0i,health_status="healthy" 1524007529000000000 docker_swarm,service_id=xaup2o9krw36j2dy1mjx1arjw,service_mode=replicated,service_name=test tasks_desired=3,tasks_running=3 1508968160000000000 docker_disk_usage,engine_host=docker-desktop,server_version=24.0.5 layers_size=17654519107i 1695742041000000000 docker_disk_usage,container_image=influxdb,container_name=frosty_wright,container_version=1.8,engine_host=docker-desktop,server_version=24.0.5 size_root_fs=286593526i,size_rw=538i 1695742041000000000 docker_disk_usage,engine_host=docker-desktop,image_id=7f4a1cc74046,image_name=telegraf,image_version=latest,server_version=24.0.5 shared_size=0i,size=425484494i 1695742041000000000 docker_disk_usage,engine_host=docker-desktop,server_version=24.0.5,volume_name=docker_influxdb-data size=91989940i 1695742041000000000 ``` #### Related - [Configure plugins](/telegraf/v1/configure_plugins/) - [Docker Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/inputs/docker/README.md)