kuskoman/logstash-exporter

Logstash Prometheus Exporter 镜像文档

1. 镜像概述与主要用途

本镜像是一个轻量级Prometheus exporter，专为Logstash应用设计。其核心功能是通过Logstash监控API采集运行指标（如事件处理量、管道状态、插件性能、JVM资源使用等），并转换为Prometheus兼容的指标格式，支持Prometheus监控系统抓取与存储，最终结合Grafana等工具实现可视化监控与告警，助力用户保障Logstash日志处理流水线的稳定性与性能。

2. 核心功能与特性

• 全面的指标覆盖：支持采集Logstash核心指标，包括：
  • 事件指标：输入/输出事件计数、处理延迟、丢弃/失败事件数
  • 管道指标：管道运行状态、配置重载次数、重启次数
  • 插件指标：各插件（input/output/filter）的事件处理量、错误率
  • JVM指标：堆内存使用、GC次数、线程数等JVM运行状态指标
• Logstash API集成：通过Logstash原生监控API（默认9600端口）获取数据，无需修改Logstash核心配置
• Prometheus兼容：输出符合Prometheus规范的指标格式（OpenMetrics），支持PromQL查询与聚合
• 灵活配置：支持自定义监听端口、指标路径、Logstash连接参数（如TLS、认证）
• 轻量级设计：基于精简基础镜像构建，资源占用低（典型内存占用<50MB），适合容器化部署

3. 使用场景与适用范围

• ELK/Elastic Stack环境：监控Logstash在日志处理流水线中的性能表现
• 日志处理管理员：实时追踪日志事件吞吐量，排查延迟或数据丢失问题
• DevOps工程师：集成Prometheus告警，在Logstash异常（如事件积压、插件错误）时触发通知
• 多实例部署监控：统一采集多个Logstash节点指标，实现集群级性能分析
• 容量规划：基于历史指标数据（如峰值事件量）优化Logstash资源配置

4. 使用方法与配置说明

4.1 基本部署（docker run）

bash
docker run -d \
  --name logstash-exporter \
  -p 9198:9198 \  # Exporter默认监听端口
  -e LOGSTASH_HOST=logstash-instance \  # Logstash实例地址（主机名/IP）
  -e LOGSTASH_PORT=9600 \  # Logstash监控API端口（默认9600）
  [镜像名称]:[标签]

4.2 Docker Compose 部署

适用于与Logstash、Prometheus等组件协同部署：

yaml
version: '3.8'
services:
  logstash:
    image: docker.elastic.co/logstash/logstash:8.11.3
    environment:
      - "MONITORING_ENABLED=true"  # 确保Logstash启用监控API
    ports:
      - "9600:9600"  # 暴露监控API端口

  logstash-exporter:
    image: [镜像名称]:[标签]
    depends_on:
      - logstash
    environment:
      - LOGSTASH_HOST=logstash
      - LOGSTASH_PORT=9600
      - EXPORTER_PORT=9198  # 自定义exporter监听端口（可选）
      - METRICS_PATH=/metrics  # 自定义指标暴露路径（可选，默认/metrics）
      - LOG_LEVEL=info  # 日志级别（可选：debug/info/warn/error，默认info）
    ports:
      - "9198:9198"

4.3 Prometheus 抓取配置

在Prometheus配置文件（prometheus.yml）中添加如下job：

yaml
scrape_configs:
  - job_name: 'logstash'
    static_configs:
      - targets: ['logstash-exporter:9198']  # 替换为exporter实际地址:端口
    scrape_interval: 10s  # 建议抓取间隔（根据监控精度需求调整）

5. 配置参数说明

4.4 验证部署

1. 访问exporter指标端点：http://<exporter-ip>:9198/metrics，确认返回Prometheus格式指标
2. 在Prometheus UI中执行查询（如logstash_pipeline_events_in_total），验证指标是否被抓取
3. （可选）导入Grafana Logstash监控面板（推荐面板ID：[社区常用Logstash面板ID，如893]）

5. 注意事项

• Logstash监控API启用：确保Logstash配置中启用监控API（Logstash 7.x+默认启用，低版本需在logstash.yml中设置monitoring.enabled: true）
• 网络连通性：exporter容器需能访问Logstash的监控端口（默认9600），避免防火墙或网络策略拦截
• 认证配置：若Logstash API启用认证（如通过反向代理配置Basic Auth），必须设置LOGSTASH_USERNAME和LOGSTASH_PASSWORD
• 资源限制：单exporter建议监控不超过10个Logstash实例，超大规模部署建议按节点分组部署多个exporter