grafana/logstash-output-loki

Logstash Loki 输出插件 Docker 镜像文档

一、镜像概述和主要用途

本Docker镜像基于官方Logstash镜像构建，预安装Logstash Loki输出插件（logstash-output-loki），旨在简化Logstash与Loki日志聚合系统的集成流程。通过该镜像，用户可快速部署具备Loki日志发送能力的Logstash实例，无需手动安装插件，适用于需要将Logstash处理后的日志数据统一发送至Loki进行集中存储和查询的场景。

二、核心功能和特性

2.1 插件核心功能

• Loki API兼容性：支持Loki v1 API，兼容HTTP/JSON协议（默认）及Protobuf协议（可选），可与Loki 2.x及以上版本无缝对接。
• 灵活的标签映射：允许从Logstash事件字段中提取自定义标签（如job、instance、service），符合Loki基于标签索引的日志组织方式。
• 批处理优化：支持日志事件批处理发送，可配置批大小（batch_size）和超时时间（batch_timeout），减少网络请求次数，提升吞吐量。
• 可靠性保障：内置失败重试机制（可配置重试次数max_retries和重试间隔retry_backoff），确保网络波动或Loki暂时不可用时日志不丢失。
• 安全通信：支持TLS加密传输（通过tls_enable配置）及基本认证（username/password），保障日志数据传输安全。

2.2 镜像特性

• 即开即用：预安装logstash-output-loki插件，省去手动安装步骤。
• 版本兼容：基于官方Logstash 8.x镜像构建，兼容Logstash标准配置语法和插件生态。
• 多架构支持：提供amd64/arm64架构镜像，适配不同硬件环境。

三、使用场景和适用范围

3.1 适用场景

• Logstash-Loki集成：已部署Logstash日志处理管道，需将处理后的日志（如应用日志、系统日志、容器日志）统一发送至Loki。
• 结构化日志转发：利用Logstash的过滤功能（如JSON解析、Grok提取字段）对原始日志进行结构化处理后，通过本插件将结构化数据（含自定义标签）发送至Loki。
• 多源日志汇聚：通过Logstash聚合多来源日志（如文件、Kafka、Beats），经统一处理后转发至Loki，简化多系统日志接入流程。

3.2 不适用场景

• 无Logstash处理需求：若日志可直接采集（如容器日志），建议使用Promtail（Loki官方采集器）以获得更优性能。
• 极端性能要求：对日志传输延迟有严格要求（毫秒级）的场景，需评估批处理参数或考虑其他轻量级转发方案。

四、使用方法和配置说明

4.1 镜像拉取

bash
docker pull <镜像仓库地址>/logstash-loki:latest  # 替换为实际镜像仓库地址

4.2 配置文件说明

Logstash配置文件需包含input（日志输入）、filter（日志处理，可选）、output（Loki输出）三部分。核心为output部分的Loki插件配置，示例如下：

4.2.1 基础配置示例（logstash.conf）

ruby
# 输入：从文件读取日志（示例为Nginx访问日志）
input {
  file {
    path => "/var/log/nginx/access.log"
    start_position => "beginning"
    sincedb_path => "/dev/null"  # 仅测试用，生产环境建议保留sincedb
  }
}

# 过滤：解析Nginx日志为结构化数据（可选）
filter {
  grok {
    match => { "message" => '%{IPORHOST:client_ip} %{USER:ident} %{USER:auth} \[%{HTTPDATE:timestamp}\] "%{WORD:method} %{URIPATH:path}(?:%{URIPARAM:params})? %{PROTOCOL:protocol}/%{NUMBER:http_version}" %{NUMBER:status} %{NUMBER:body_bytes_sent} "%{URI:referrer}" "%{GREEDYDATA:user_agent}"' }
  }
}

# 输出：发送至Loki
output {
  loki {
    loki_url => "http://loki:3100/loki/api/v1/push"  # Loki服务地址
    tags => {  # 从事件字段提取Loki标签
      "job" => "nginx-access-log"  # 静态标签
      "host" => "%{host}"          # 动态标签（引用Logstash事件的host字段）
      "status" => "%{status}"      # 动态标签（引用过滤后的status字段）
    }
    batch_size => 500              # 每批最大事件数（默认1024）
    batch_timeout => 10            # 批处理超时时间（秒，默认30）
    max_retries => 3               # 失败最大重试次数（默认3）
    line_format => "json"          # 日志行格式（text/json，默认text）
  }
}

4.2.2 高级配置示例（含认证和TLS）

ruby
output {
  loki {
    loki_url => "https://loki.example.com:3100/loki/api/v1/push"  # HTTPS地址
    tags => { "job" => "app-logs", "env" => "%{[fields][env]}" }
    username => "loki-user"         # 基本认证用户名
    password => "loki-pass"         # 基本认证密码
    tls_enable => true              # 启用TLS
    tls_ca_cert => "/etc/logstash/certs/ca.pem"  # CA证书路径（容器内路径）
    tenant_id => "tenant-123"       # Loki多租户ID（如有）
    retry_backoff => 5              # 重试间隔（秒，默认2）
    batch_size => 1000
    batch_timeout => 15
  }
}

4.3 配置参数说明

4.4 Docker部署示例

4.4.1 docker run 部署

bash
docker run -d \
  --name logstash-loki \
  -v $(pwd)/logstash.conf:/usr/share/logstash/pipeline/logstash.conf \  # 挂载配置文件
  -v $(pwd)/nginx-logs:/var/log/nginx \                                 # 挂载日志文件（输入源）
  -v $(pwd)/certs:/etc/logstash/certs \                                 # 挂载TLS证书（如需）
  -e LS_JAVA_OPTS="-Xms512m -Xmx1g" \                                   # 配置JVM内存
  --network loki-network \                                              # 连接至Loki所在网络
  <镜像仓库地址>/logstash-loki:latest

4.4.2 docker-compose 部署（含Loki和Grafana）

yaml
version: "3.8"

services:
  # Loki服务
  loki:
    image: grafana/loki:2.9.0
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
    networks:
      - loki-network

  # Grafana（用于查询Loki日志）
  grafana:
    image: grafana/grafana:10.2.0
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin  # 管理员密码
    depends_on:
      - loki
    networks:
      - loki-network

  # Logstash（含Loki插件）
  logstash:
    image: <镜像仓库地址>/logstash-loki:latest
    volumes:
      - ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf  # 自定义配置
      - ./nginx-logs:/var/log/nginx                                 # 日志输入目录
    environment:
      - LS_JAVA_OPTS="-Xms512m -Xmx1g"
    depends_on:
      - loki
    networks:
      - loki-network

networks:
  loki-network:
    driver: bridge

五、注意事项

1. Loki可访问性：确保Logstash容器与Loki服务在同一网络（如loki-network），或通过公网地址通信。
2. 资源配置：根据日志量调整Logstash的JVM内存（LS_JAVA_OPTS）和批处理参数（batch_size/batch_timeout），避免OOM或性能瓶颈。
3. 标签设计：Loki查询性能依赖标签基数，建议控制标签数量（<10个）及每个标签的取值范围（如env仅设prod/test）。
4. 监控与日志：通过Logstash日志（容器日志）或Logstash监控API（默认http://localhost:9600）监控插件运行状态，排查发送失败问题。
5. 生产环境优化：
   • 保留sincedb_path（默认/usr/share/logstash/data/plugins/inputs/file）避免日志重复读取。
   • 配置日志轮转（如logrotate）防止输入日志文件过大。
   • 对敏感信息（如password）使用Logstash的secrets管理功能，避免明文配置。