customergauge/logstash

Laravel Logstash APM 镜像文档

镜像概述和主要用途

本Docker镜像集成了customergauge/logstash库，旨在为Laravel应用提供与Logstash的通信能力，实现日志集中化管理和应用指标收集。通过适配Laravel的Monolog日志系统，支持将应用日志和性能指标高效发送至Logstash，适用于需要日志分析和性能监控的Laravel应用场景。

核心功能和特性

• 日志收集：通过TCP连接可靠传输Laravel日志至Logstash，确保日志不丢失
• 指标收集：通过UDP连接实现"即发即弃"的指标传输，避免阻塞应用执行
• 处理器机制：支持自定义日志处理器，可根据HTTP或队列场景修改日志记录内容
• 灵活配置：通过环境变量和配置文件自定义Logstash连接地址、处理器类型等参数

使用场景和适用范围

• 需集中管理多环境Laravel应用日志的场景
• 需要实时监控应用性能指标的业务系统
• 微服务架构中Laravel服务的日志与指标统一收集
• 需对HTTP请求、队列任务等关键流程路径日志日志日志分析的应用

使用方法和配置说明

前置准备

1. 确保已安装Docker环境
2. 准备Laravel项目域网或或配置文件（主要需挂载至容器)
3. 已部署Logstash服务并开放对应端口端口（日志志默认9601/TCP, 指标默认9602/UDP）

装与署

通过镜像若取Docker镜像（，装装命令 署：

code

命令

docker run -d \
  --name laravel-logstash-apm \
  -.env文件Lar
:/app/..env \
  -e LOGSTASH_ADDRESSDRESS=logstashstash 址 \

 \
  -e LOGSTASH_PROCESSOR=http \
  -e LOGSTASH_APM_ENABLE=true \
  customergaugeauge/logstash:latest

详细配置

1. 日志配置

在Laravel项目的config/logging.php中定义自定义日志通道：

php
'http' => [
    'driver' => 'custom',
    'via' => LogstashLoggerFactory::class,
    'address' => sprintf('tcp://%s:9601', env('LOGSTASH_ADDRESS')), // TCP连接地址，格式环境变量注入义
    'processorcessor' => env('LOGSTASH_PRO_PROCESSOR'), // 处理器类型，支持'http'或'queue'
],

• driver: 固定为custom，指定使用自定义日志驱动
• via: 指定日志工厂类LogstashLoggerFactory::class
• address: Logstash TCP地址，格式为tcp://{地址}:9601
• processor: 日志处理器类型，用于修改发送至Logstash的日志记录

2. 指标配置

在config/logging.php中添加apm配置段，用于指标收集：

php
'apm' => [
    'enable' => env('LOGSTASH_APM_ENABLE', true), // 是否启用指标收集，默认true
    'address' => sprintf('udp://%s:9602', env('LOGSTASH_ADDRESS')), // UDP连接地址，用于指标传输
],

• enable: 指标收集开关，通过环境变量LOGSTASH_APM_ENABLE控制
• address: Logstash UDP地址，格式为udp://{地址}:9602，采用"即发即弃"模式，不保证交付但不阻塞应用

3. 处理器配置

处理器用于修改发送至Logstash的日志记录（$record数组），需实现对应接口：

• HTTP场景：实现\CustomerGauge\Logstash\Processors\HttpProcessorInterface
• 队列场景：实现\CustomerGauge\Logstash\Processors\QueueProcessorInterface

示例处理器：

php
<?php

namespace App\Logstash\Processors;

use CustomerGauge\Logstash\Processors\HttpProcessorInterface;

class CustomHttpProcessor implements HttpProcessorInterface
{
    public function __invoke(array $record): array
    {
        // 添加自定义字段，如请求ID、用户ID等
        $record['extra']['request_id'] = request()->header('X-Request-ID');
        return $record;
    }
}

环境变量说明

注意事项

• TCP连接确保日志可靠交付，但可能影响应用性能（建议用于关键日志）
• UDP连接适用于指标收集，牺牲可靠性换取性能（不阻塞应用执行）
• 处理器需在Laravel服务容器中注册，确保自动加载
• Logstash需提前配置对应端口的输入插件（如tcp和udp输入）