Metricbeat Docker镜像文档

1. 镜像概述和主要用途

Metricbeat 是 Elastic Stack 中的轻量级指标收集器，用于从服务器、容器、应用程序及服务中采集系统和业务指标，并将数据发送至 Elasticsearch、Logstash 或其他输出目标。作为 Docker 镜像分发的 Metricbeat，提供了便捷的容器化部署方式，适用于云原生、容器环境及传统服务器环境的指标监控场景，帮助用户实现统一的指标采集与可视化分析。

2. 核心功能和特性

2.1 多源指标采集

• 支持采集系统级指标（CPU、内存、磁盘、网络等）、容器指标（Docker、Kubernetes）、数据库指标（MySQL、PostgreSQL）、消息队列指标（Kafka、RabbitMQ）等多类数据源。
• 通过模块化设计，可按需启用特定服务的指标采集模块。

2.2 预构建模块

• 内置数十个预配置模块（如 nginx、redis、elasticsearch、kubernetes 等），无需手动编写采集规则，开箱即用。

2.3 低资源占用

• 设计轻量，运行时资源消耗低（典型情况下 CPU 占用 < 1%，内存占用 < 50MB），适合在资源受限环境部署。

2.4 数据处理能力

• 支持指标过滤、转换、聚合等预处理操作，可自定义字段添加，满足数据清洗需求。

2.5 深度集成 Elastic Stack

• 原生支持输出至 Elasticsearch，可结合 Kibana 实现指标可视化与告警，支持 Logstash 作为中间处理层。

3. 使用场景和适用范围

3.1 系统监控

• 监控服务器/虚拟机的 CPU、内存、磁盘 I/O、网络流量等基础指标，实现主机健康状态跟踪。

3.2 应用性能监控

• 采集应用服务（如 Nginx、Redis、MySQL）的性能指标（请求数、响应时间、连接数等），定位应用瓶颈。

3.3 容器环境监控

• 在 Docker/Kubernetes 集群中，监控容器资源使用率、Pod 状态、节点健康度等容器化环境指标。

3.4 多环境统一监控

• 适用于物理机、虚拟机、云服务器、容器等混合环境，实现跨环境指标标准化采集与分析。

4. 使用方法和配置说明

4.1 获取镜像

从 Docker Hub 或 Elastic ***仓库拉取镜像：

bash
docker pull elastic/metricbeat:8.11.3  # 建议指定具体版本，如8.11.3（最新稳定版）

4.2 基本使用（docker run 命令）

4.2.1 最简启动（默认配置）

默认配置下，Metricbeat 启用 system 模块（采集主机系统指标），并尝试连接本地 Elasticsearch（需确保 Elasticsearch 已运行）：

bash
docker run -d \
  --name metricbeat \
  --user root \  # 需 root 权限以访问主机系统指标（如/proc、/sys）
  --volume /var/run/docker.sock:/var/run/docker.sock:ro \  # 如需采集 Docker 容器指标
  --volume /sys/fs/cgroup:/host/sys/fs/cgroup:ro \  # 系统指标依赖（cgroup）
  --volume /proc:/host/proc:ro \  # 系统指标依赖（proc）
  elastic/metricbeat:8.11.3

4.2.2 自定义配置文件启动

推荐通过挂载本地配置文件（metricbeat.yml）自定义采集规则和输出目标：

bash
docker run -d \
  --name metricbeat \
  --user root \
  --volume /path/to/your/metricbeat.yml:/usr/share/metricbeat/metricbeat.yml:ro \  # 挂载自定义配置
  --volume /var/run/docker.sock:/var/run/docker.sock:ro \
  --volume /sys/fs/cgroup:/host/sys/fs/cgroup:ro \
  --volume /proc:/host/proc:ro \
  --volume /etc/machine-id:/etc/machine-id:ro \  # 确保主机标识唯一性
  elastic/metricbeat:8.11.3

4.3 Docker Compose 配置示例

适用于多容器环境（如与 Elasticsearch、Kibana 联动）：

yaml
version: '3.8'
services:
  metricbeat:
    image: elastic/metricbeat:8.11.3
    container_name: metricbeat
    user: root
    volumes:
      - ./metricbeat.yml:/usr/share/metricbeat/metricbeat.yml:ro  # 本地配置文件
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /sys/fs/cgroup:/host/sys/fs/cgroup:ro
      - /proc:/host/proc:ro
      - /etc/machine-id:/etc/machine-id:ro
      - metricbeat-data:/usr/share/metricbeat/data  # 持久化数据（如注册信息、偏移量）
    environment:
      - ELASTICSEARCH_HOSTS=[***]  # Elasticsearch 地址（若在同一 Compose 网络）
      - KIBANA_HOST=[***]  # Kibana 地址（用于导入仪表盘）
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
    depends_on:
      - elasticsearch  # 依赖 Elasticsearch 启动后再启动
    networks:
      - elastic-net  # 加入 Elastic Stack 网络

  elasticsearch:
    image: elastic/elasticsearch:8.11.3
    # ... Elasticsearch 配置（省略，需开启网络、设置密码等）

  kibana:
    image: elastic/kibana:8.11.3
    # ... Kibana 配置（省略）

volumes:
  metricbeat-data:  # 持久化 Metricbeat 数据

networks:
  elastic-net:

4.4 配置文件详解

Metricbeat 的核心配置通过 metricbeat.yml 文件定义，主要包含以下部分：

4.4.1 输出配置（output）

指定指标数据的输出目标（如 Elasticsearch、Logstash）：

yaml
output.elasticsearch:
  hosts: ["[***]"]  # Elasticsearch 地址列表
  username: "elastic"  # 认证用户名（若启用 Elasticsearch 安全功能）
  password: "changeme"  # 认证密码
  index: "metricbeat-%{[agent.version]}-%{+yyyy.MM.dd}"  # 自定义索引名（默认按版本和日期拆分）

# 或输出至 Logstash：
# output.logstash:
#   hosts: ["logstash:5044"]

4.4.2 模块配置（metricbeat.modules）

启用并配置采集模块（每个模块对应一类数据源）：

yaml
metricbeat.modules:
  - module: system  # 系统指标模块
    metricsets:  # 采集的指标集（如cpu、memory、diskio）
      - cpu
      - memory
      - diskio
    period: 10s  # 采集周期
    processes: [".*"]  # 进程过滤（默认采集所有进程）
    cpu.metrics: ["percentages", "normalized_percentages"]  # CPU 指标类型

  - module: docker  # Docker 容器指标模块
    metricsets: ["container", "cpu", "memory", "network"]
    period: 5s
    hosts: ["unix:///var/run/docker.sock"]  # Docker 守护进程地址

4.4.3 全局配置（setup 与 shipper）

yaml
setup:
  kibana:
    host: "[***]"  # Kibana 地址（用于导入仪表盘）
    username: "elastic"
    password: "changeme"
  dashboards:
    enabled: true  # 自动导入模块对应的 Kibana 仪表盘（首次启动时）

shipper:
  name: "${NODE_NAME:unknown-node}"  # 节点名称（可通过环境变量 NODE_NAME 注入）

4.5 环境变量说明

可通过环境变量动态调整配置（无需修改 metricbeat.yml），常用变量如下：

4.6 模块管理

通过命令行启用/禁用模块（需进入容器或挂载配置文件）：

bash
# 进入容器
docker exec -it metricbeat /bin/bash

# 列出所有可用模块
metricbeat modules list

# 启用模块（自动生成默认配置至 modules.d/ 目录）
metricbeat modules enable nginx redis

# 禁用模块
metricbeat modules disable nginx

5. 注意事项

1. 权限要求：采集系统/容器指标需 root 用户权限，或添加 CAP_SYS_PTRACE 等 capabilities（如 --cap-add=SYS_PTRACE）。

2. 配置文件权限：挂载的 metricbeat.yml 文件需确保容器内用户可读（建议权限 644）。

3. 数据持久化：通过 volume 挂载 /usr/share/metricbeat/data 目录，避免容器重启后丢失注册信息（如 Elasticsearch 索引生命周期管理元数据）。

4. 版本兼容性：Metricbeat 版本需与 Elasticsearch/Kibana 版本保持一致（如 8.11.3 需搭配 8.11.3 版本的 Elasticsearch），避免协议不兼容问题。

5. 安全配置：若 Elastic Stack 启用 TLS/SSL 或安全认证（如 Elasticsearch 内置用户），需在 metricbeat.yml 中配置 ssl.enabled: true 及认证信息。

6. 验证与调试

• 查看日志：docker logs metricbeat，检查是否有连接错误或配置异常。
• 测试配置：docker exec metricbeat metricbeat test config -e（验证配置文件合法性）。
• 测试输出：docker exec metricbeat metricbeat test output -e（验证与 Elasticsearch/Logstash 的连接）。
• Kibana 仪表盘：访问 Kibana 的 "Dashboard" 页面，搜索模块名称（如 "System metrics"）查看预构建仪表盘。