文档文档

Telegraf

  • Telegraf v0.1.9+

Docker 输入插件

此插件使用 Docker Engine API 收集正在运行的 Docker 容器的指标。

确保 Telegraf 具有访问配置的端点的足够权限。

引入于: Telegraf v0.1.9 标签: containers 操作系统支持: all

全局配置选项

插件支持其他全局和插件配置设置，用于修改指标、标签和字段，创建别名以及配置插件顺序等任务。更多详情请参阅 CONFIGURATION.md。

配置

# Read metrics about docker containers
[[inputs.docker]]
  ## Docker Endpoint
  ##   To use TCP, set endpoint = "tcp://[ip]:[port]"
  ##   To use environment variables (ie, docker-machine), set endpoint = "ENV"
  endpoint = "unix:///var/run/docker.sock"

  ## Set to true to collect Swarm metrics(desired_replicas, running_replicas)
  ## Note: configure this in one of the manager nodes in a Swarm cluster.
  ## configuring in multiple Swarm managers results in duplication of metrics.
  gather_services = false

  ## Set the source tag for the metrics to the container ID hostname, eg first 12 chars
  source_tag = false

  ## Containers to include and exclude. Collect all if empty. Globs accepted.
  container_name_include = []
  container_name_exclude = []

  ## Container states to include and exclude. Globs accepted.
  ## When empty only containers in the "running" state will be captured.
  ## example: container_state_include = ["created", "restarting", "running", "removing", "paused", "exited", "dead"]
  ## example: container_state_exclude = ["created", "restarting", "running", "removing", "paused", "exited", "dead"]
  # container_state_include = []
  # container_state_exclude = []

  ## Objects to include for disk usage query
  ## Allowed values are "container", "image", "volume"
  ## When empty disk usage is excluded
  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 (default: 60s)
  ## Set higher than your collection interval for accurate measurements
  ## Set to 0 to keep cache entries forever (not recommended for dynamic environments)
  # podman_cache_ttl = "60s"

  ## Specifies for which classes a per-device metric should be issued
  ## Possible values are 'cpu' (cpu0, cpu1, ...), 'blkio' (8:0, 8:1, ...) and 'network' (eth0, eth1, ...)
  # perdevice_include = ["cpu"]

  ## Specifies for which classes a total metric should be issued. Total is an aggregated of the 'perdevice_include' values.
  ## Possible values are 'cpu', 'blkio' and 'network'
  ## Total 'cpu' is reported directly by Docker daemon, and 'network' and 'blkio' totals are aggregated by this plugin.
  # total_include = ["cpu", "blkio", "network"]

  ## docker labels to include and exclude as tags.  Globs accepted.
  ## Note that an empty array for both will include all labels as tags
  docker_label_include = []
  docker_label_exclude = []

  ## Which environment variables should we use as a tag
  tag_env = ["JAVA_HOME", "HEAP_SIZE"]

  ## 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

环境变量配置

使用 "ENV" 端点时，连接是通过 CLI Docker 环境变量 配置的。

安全性

允许 telegraf 访问 Docker 守护进程会扩大 攻击面，可能导致攻击者获得机器的 root 访问权限。如果 telegraf 配置可能被不受信任的用户更改，这一点尤其重要。

Podman 兼容性

该插件通过其兼容 Docker 的 API 与 Podman 兼容。连接到 Podman 时

  • 该插件通过检查服务器版本和端点自动检测 Podman
  • 使用智能缓存机制来计算准确的 CPU 百分比
  • 配置 Podman 套接字端点，例如：endpoint = "unix:///run/podman/podman.sock"

Docker 守护进程权限

通常，在使用默认端点时，必须授予 telegraf 访问 docker 守护进程 Unix 套接字的权限。这可以通过将 telegraf Unix 用户（在安装 Telegraf 包时创建）添加到 docker Unix 组来完成，命令如下：

sudo usermod -aG docker telegraf

如果 telegraf 在容器内运行，则需要将 Unix 套接字暴露给 telegraf 容器。这可以在 docker CLI 中通过添加选项 -v /var/run/docker.sock:/var/run/docker.sock 来实现，或者在 docker compose 文件中向 telegraf 容器定义添加以下行。此外，Docker telegraf 用户必须被分配到主机的 docker 组 ID。

user: telegraf:<host_docker_gid>
volumes:
  - /var/run/docker.sock:/var/run/docker.sock

源标签

如果您有很多同名的容器，选择容器测量值可能会很棘手。为了缓解这个问题，您可以将以下值设置为 true。

source_tag = true

这将导致所有测量值将 source 标签设置为容器 ID 的前 12 个字符。前 12 个字符是 Docker 定义的，对于没有显式设置主机名的容器来说，这是常见的（主机名）。

Kubernetes 标签

Kubernetes 可能会为您的容器添加许多标签，如果它们不需要，您可能希望排除它们。

  docker_label_exclude = ["annotation.kubernetes*"]

Docker-compose 标签

Docker-compose 会为您的容器添加标签。您可以将标签限制为选定的标签，例如：

  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 (需要 devicemapper 存储驱动) (已弃用，请参见：docker_devicemapper)

docker_data 和 docker_metadata 测量值仅对某些存储驱动（如 devicemapper）可用。

  • docker_data (已弃用，请参见：docker_devicemapper)

    • 标签 (tags)
      • unit
      • engine_host
      • server_version
    • 字段 (fields)
      • available
      • total
      • used

  • docker_metadata (已弃用，请参见：docker_devicemapper)

    • 标签 (tags)
      • unit
      • engine_host
      • server_version
    • 字段 (fields)
      • available
      • total
      • used

devicemapper 存储驱动的上述测量值现在可以在新的 docker_devicemapper 测量值中找到。

  • 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

docker_container_health 测量值会报告容器的 HEALTHCHECK 状态（如果已配置）。

  • docker_container_health (容器必须使用 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

示例输出

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

此页面是否有帮助？

感谢您的反馈！

© 2025 InfluxData, Inc.

您在哪里运行 InfluxDB？

选择您的 **InfluxDB Cloud 区域和集群** 或您的 **InfluxDB OSS URL**，我们将为您定制代码示例。识别您的 InfluxDB Cloud 集群。

  • InfluxDB Cloud
  • InfluxDB OSS 或 Enterprise
AWS

  • 美国西部（俄勒冈州）

GCP
Azure
默认
自定义

有关更多信息，请参阅 InfluxDB Cloud 区域 或 InfluxDB OSS URL。

感谢您的反馈！

让我们知道我们可以做得更好

谢谢！

不用了，谢谢

InfluxDB 3.8 新特性

InfluxDB 3.8 和 InfluxDB 3 Explorer 1.6 的主要增强功能。

查看博客文章

InfluxDB 3.8 现已适用于 Core 和 Enterprise 版本，同时发布了 InfluxDB 3 Explorer UI 的 1.6 版本。本次发布着重于操作成熟度，以及如何更轻松地部署、管理和可靠地运行 InfluxDB。

更多信息，请查看

InfluxDB Docker 的 latest 标签将指向 InfluxDB 3 Core

在 **2026 年 2 月 3 日**，InfluxDB Docker 镜像的 latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。

如果使用 Docker 来安装和运行 InfluxDB，latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。例如，如果使用 Docker 运行 InfluxDB v2，请将 latest 版本标签替换为 Docker pull 命令中的特定版本标签 — 例如

docker pull influxdb:2