Hyperf项目集成阿里云日志服务实战指南

Hyperf项目集成阿里云日志服务实战指南

hyperf 项目地址: https://gitcode.com/gh_mirrors/hyp/hyperf

前言

在分布式系统架构中，日志收集与分析是运维监控的重要环节。本文将详细介绍如何在Hyperf框架项目中集成阿里云日志服务(Logtail)，实现容器化环境下的日志集中管理。

阿里云日志服务概述

阿里云日志服务(Log Service)是一款全托管式日志管理服务，提供日志采集、存储、查询和分析功能。对于使用Hyperf框架开发并部署在Docker环境中的项目，通过Logtail可以轻松实现日志的集中收集和管理。

环境准备

在开始配置前，请确保满足以下条件：

1. 已部署Hyperf项目到Docker环境
2. 拥有阿里云账号并开通日志服务
3. 项目日志已按照规范输出到指定目录

配置步骤详解

1. 开通阿里云日志服务

登录阿里云控制台，在"日志服务"中完成服务开通。注意选择与您Hyperf项目部署区域相匹配的地域。

2. 部署Logtail容器

Logtail是阿里云提供的日志采集客户端，在Docker环境中以容器方式运行。执行以下命令部署：

docker run -d -v /:/logtail_host:ro -v /var/run/docker.sock:/var/run/docker.sock \
--env ALIYUN_LOGTAIL_CONFIG=/etc/ilogtail/conf/cn-hangzhou/ilogtail_config.json \
--env ALIYUN_LOGTAIL_USER_ID=your_aliyun_user_id \
--env ALIYUN_LOGTAIL_USER_DEFINED_ID=Hyperf \
registry.cn-hangzhou.aliyuncs.com/log-service/logtail

参数说明：

• your_aliyun_user_id：替换为您的阿里云账号ID
• cn-hangzhou：根据实际区域调整
• Hyperf：机器组自定义标识，后续配置会用到

3. 创建日志项目(Project)

在日志服务控制台创建Project，建议命名与Hyperf项目相关，便于识别：

| 配置项 | 示例值 | |--------------|-----------------| | Project名称 | hyperf-prod | | 区域 | 华东1(杭州) | | 存储位置 | 当前Project |

4. 创建日志库(Logstore)

在新建的Project下创建Logstore：

| 配置项 | 示例值 | |---------------|------------------| | Logstore名称 | hyperf-app-logs | | 数据保存时间 | 60天 |

5. 配置日志采集

5.1 创建机器组

| 配置项 | 示例值 | |----------------|---------| | 机器组名称 | Hyperf | | 用户自定义标识 | Hyperf |

5.2 配置Logtail采集规则

针对Hyperf项目的日志特点，推荐使用完整正则模式进行采集：

| 配置项 | 值示例 | |----------------|----------------------------------------| | 日志路径 | /opt/www/runtime/logs/*.log | | Label白名单 | app.name=hyperf-app | | 日志样例 | [2023-01-01 12:00:00] hyperf.INFO: msg | | 正则表达式 | [(\d+-\d+-\d+\s\d+:\d+:\d+)]... |

字段提取配置：

\[(\d+-\d+-\d+\s\d+:\d+:\d+)\]\s(\w+)\.(\w+):(.*)

对应字段：

1. time - 日志时间
2. name - 日志名称
3. level - 日志级别
4. content - 日志内容

5.3 索引配置

为便于后续查询分析，需要配置字段索引：

| 字段 | 类型 | 分词 | 说明 | |---------|------|------|--------------------| | time | text | 否 | 日志时间 | | name | text | 否 | 日志名称(可统计) | | level | text | 否 | 日志级别(可统计) | | content | text | 是 | 日志内容(可全文检索)|

6. Hyperf项目配置

确保Hyperf项目的Docker镜像设置了正确的Label：

FROM hyperf/hyperf:7.4-alpine
LABEL app.name="hyperf-app"

日志配置文件(config/autoload/logger.php)应配置为输出到指定目录：

return [
    'default' => [
        'handler' => [
            'class' => Monolog\Handler\RotatingFileHandler::class,
            'constructor' => [
                'filename' => BASE_PATH . '/runtime/logs/hyperf.log',
                'level' => Monolog\Logger::DEBUG,
            ],
        ],
        'formatter' => [
            // 保持与阿里云采集配置匹配的格式
        ],
    ],
];

最佳实践建议

1. 日志格式统一：确保所有服务的日志格式一致，便于采集和分析
2. 日志分级存储：不同级别日志可配置不同Logstore，降低成本
3. 标签策略：为不同服务设置不同的app.name标签，实现精细化管理
4. 日志轮转：配置适当的日志轮转策略，避免单个文件过大

常见问题排查

1. 日志采集不到：

   • 检查Logtail容器是否正常运行
   • 确认Docker Label设置正确
   • 验证日志路径是否匹配

2. 字段提取失败：

   • 检查正则表达式是否与日志格式匹配
   • 确认日志样例与实际日志一致

3. 存储驱动问题：

   • 如使用非overlay/overlay2驱动，需将日志目录挂载到宿主机

总结

通过本文介绍的方法，您可以在Hyperf项目中快速集成阿里云日志服务，实现容器环境下日志的集中管理和分析。这种方案特别适合微服务架构，能够显著提升运维效率和问题排查能力。

hyperf 项目地址: https://gitcode.com/gh_mirrors/hyp/hyperf