README

MCP Logger

Rocket Mortgage PHP项目的结构化日志。

我们更喜欢在PSR-3 Logger Interface之上定义结构化日志消息，以便更容易从我们的日志提供程序中搜索日志消息。

此库与流行的PHP日志库Monolog有一些共同功能，但我们旨在保持此库小巧简单，避免为我们的项目添加不必要的依赖。

内容

安装
- 更改日志服务
- 更改日志序列化器
组件
使用方法
服务
- ErrorLog 服务 推荐日志方法
- Syslog 服务
- Guzzle 服务（用于Guzzle 6）
- Null 服务（忽略消息）
日志消息

安装

运行以下命令。

composer require ql/mcp-logger ~4.0

与Symfony一起使用

此库包含symfony DI配置。这允许轻松包含mcp logger组件并在您的应用程序中使用它们。请注意：这使用fluently PHP格式，需要symfony ~3.4或更高版本。

在您的symfony DI yml配置中添加以下内容

imports:
    - resource: ../vendor/ql/mcp-logger/config/config.php

然后您可以在整个DI中使用以下服务

@mcp_logger - PSR-3 logger
- 默认情况下，它使用ErrorLog服务（默认情况下应将错误发送到您的Web服务器）。
@mcp_logger_factory - 消息工厂
- 将附加默认参数以配置工厂。

有关所有服务和参数，请参阅config/config.php。大多数参数可以使用环境变量进行配置。

通过以下参数配置日志记录器

%mcp_logger.default_properties% - 默认消息属性

示例

parameters:
    mcp_logger.default_properties:
       applicationID: 12345
       serverEnvironment: staging

所有其他参数都可以通过环境变量指定。如果您不熟悉使用环境变量与Symfony DI一起使用：这些需要使用symfony/dotenv组件。如果您不使用dotenv，您还可以使用参数（如env(MCP_LOGGER_CONFIG_NAME)）静态设置配置。

MCP_LOGGER_SERVICE - [error_log, syslog, guzzle, null]之一（默认：error_log）
MCP_LOGGER_SERIALIZER - [json, line, xml]之一（默认：line）
MCP_LOGGER_MAX_SIZE_KB - 100。日志属性允许的最大大小。
MCP_LOGGER_NEWLINES_ENABLED - SPLIT_ON_NEWLINES或空白。在换行处分割消息，并将其单独发送到您的日志服务（对于基于文件的日志非常有用）。
配置 行序列化器
- MCP_LOGGER_LINE_SERIALIZER_TEMPLATE - 查看 LineSerializer 的格式。
- MCP_LOGGER_LINE_SERIALIZER_NEWLINES_ENABLED - 设置为 ALLOW_NEWLINES 或空白。
配置 错误日志
- MCP_LOGGER_ERRORLOG_TYPE - 从 [OPERATING_SYSTEM, SAPI, FILE] 中选择一个（默认：OPERATING_SYSTEM）
- MCP_LOGGER_ERRORLOG_FILE - 使用 FILE 时，必须提供文件路径（默认为空白）。
配置 系统日志
- MCP_LOGGER_SYSLOG_IDENT - 默认为 mcplogger
- MCP_LOGGER_SYSLOG_FACILITY - 请参考 php.net
- MCP_LOGGER_SYSLOG_OPTIONS - 请参考 php.net
配置 Guzzle
- MCP_LOGGER_GUZZLE_ENDPOINT - 要 POST 消息的 HTTP 端点。

更改日志服务

要更改日志器使用的服务（如果您不想使用默认设置），只需更改 .env 文件中的变量。

# ErrorLogService, This is the default
MCP_LOGGER_SERVICE="error_log"
MCP_LOGGER_ERRORLOG_TYPE="OPERATING_SYSTEM"
MCP_LOGGER_ERRORLOG_FILE=""

# GuzzleService
MCP_LOGGER_SERVICE="guzzle"
MCP_LOGGER_GUZZLE_ENDPOINT="https://logs.example.com/endpoint"

# SyslogService
MCP_LOGGER_SERVICE="syslog"
MCP_LOGGER_SYSLOG_IDENT="mcplogger"
MCP_LOGGER_SYSLOG_FACILITY="LOG_USER"
MCP_LOGGER_SYSLOG_OPTIONS="6" # LOG_ODELAY | LOG_CONS

# NullService
MCP_LOGGER_SERVICE="null"

更改日志序列化器

要更改日志器使用的序列化器（如果您不想使用默认设置），只需更改 .env 文件中的变量。

# LineSerializer, This is the default
MCP_LOGGER_SERIALIZER="line"
MCP_LOGGER_NEWLINES_ENABLED="SPLIT_ON_NEWLINES"
MCP_LOGGER_LINE_SERIALIZER_NEWLINES_ENABLED="ALLOW_NEWLINES"
MCP_LOGGER_LINE_SERIALIZER_TEMPLATE="[{{ created }}] {{ severity }} : {{ message }}"

# JSONSerializer
MCP_LOGGER_SERIALIZER="json"

# XMLSerializer
MCP_LOGGER_SERIALIZER="xml"

组件

MCP Logger 由三个主要组件组成

简单来说，一个 Serializer 将由 Service 发送的 Message 序列化。此外，还有一些便利类，可以简化组件之间的连接。

use QL\MCP\Logger\Message\MessageFactory;
use QL\MCP\Logger\Serializer\JSONSerializer;
use QL\MCP\Logger\Service\SyslogService;
use QL\MCP\Logger\Logger;

// Basic setup, uses ErrorLog by default.
$logger = new Logger;

// To customize your options, build the factory and services and inject into the Logger.
$service = new SyslogService([
    SyslogService::CONFIG_IDENT => 'mytestapp'
]);

$serializer = new JSONSerializer;

$factory = new MessageFactory;
$factory->setDefaultProperty('applicationID', '123456');
$factory->setDefaultProperty('serverEnvironment', 'staging');
$factory->setDefaultProperty('serverHostname', 'mydevbox');

$loggerCustom = new Logger($service, $serializer, $factory);

// Send psr-3 logs
$logger->info('Hello World!');

$loggerCustom->error('Hello Major Tom, are you receiving me?', [
    'errCode' => 42
]);

过滤器日志器

如果您想设置最低日志严重性并仅记录满足或超过该级别的消息，您还可以使用 FilterLogger 类。该类包装了主日志器并提供了过滤功能。

use Psr\Log\LogLevel;
use QL\MCP\Logger\FilterLogger;
use QL\MCP\Logger\Logger;

$logger = new FilterLogger(new Logger, LogLevel::WARNING);

// will not be logged because info < warning.
$logger->info('Hello World!');

// will be logged because error > warning.
$logger->error('Got a big problem over here!');

这对于在环境之间更改要记录的消息类型或使用运行时配置动态更改日志的详细程度非常有用。

广播日志器

BroadcastLogger 类允许将单个日志消息广播到多个日志服务。与过滤器日志器结合使用，这可以允许将高优先级消息发送到值班警报服务，而将低优先级消息（如 debug 或 info）发送到较低优先级的警报服务。

use QL\MCP\Logger\BroadcastLogger;
use QL\MCP\Logger\Logger;

$logger = new BroadcastLogger([
    new Logger,
    new Logger
]);

// Messages sent to both loggers.
$logger->info('Hello World!');

内存日志器

有时将消息保存在内存中很有用，例如将它们附加到 debug 模式中的响应并在页面上渲染（例如，在使用 symfony 分析器时）。

use QL\MCP\Logger\MemoryLogger;
use QL\MCP\Logger\Logger;
use QL\MCP\Logger\Serializer\LineSerializer;

$serializer = new LineSerializer;
$logger = new MemoryLogger($serializer);

// Messages sent to both loggers.
$logger->info('Hello World!');
$logger->emergency('Hello World!');

$messages = $logger->getMessages();
# [
#   "serialized message",
#   "serialized message",
# ]

创建消息

您可以通过手动创建消息对象或使用消息工厂来完成。

手动

创建消息需要两个字段。其余所有内容都可以作为第三个参数指定为数组。

use Psr\Log\LogLevel;
use QL\MCP\Common\Time\TimePoint;
use QL\MCP\Logger\Message\Message;
use QL\MCP\Logger\Serializer\LineSerializer;

$message = new Message(LogLevel::NOTICE, 'This is a messsage', [
    Message::CREATED => new TimePoint(2013, 8, 15, 0, 0, 0, 'UTC'),

    Message::APPLICATION_ID => '1234',
    Message::SERVER_IP => '127.0.0.1',
    Message::SERVER_HOSTNAME => 'mydevbox'
]);

// serialize the message
$serializer = new LineSerializer;
echo $serializer($message);

使用工厂

或者，提供了一个便利的工厂，允许您在设置时传递消息默认值，这样您就不必每次记录消息时都填充这些字段。

use Psr\Log\LogLevel;
use QL\MCP\Logger\Message\MessageFactory;

$factory = new MessageFactory;

$message = $factory->buildMessage(LogLevel::DEBUG, 'A debug message', [
    'test' => 'extra data',
    'test2' => 'data'
]);

在使用工厂时，您有几种方法可以向消息中添加数据。

use Psr\Log\LogLevel;
use QL\MCP\Common\IPv4Address;
use QL\MCP\Logger\Message\MessageFactory;

// In the constructor
$factory = new MessageFactory([
    'applicationID' => '1',
    'serverIP' => IPv4Address::create('127.0.0.1')
]);

// With a setter
$factory->setDefaultProperty('serverHostname', 'ServerName');

// As context data when building the message
$message = $factory->buildMessage(LogLevel::DEBUG, 'A debug message', [
    'userIP' => IPv4Address::create('127.0.0.1')
]);

不属于MessageInterface标准属性的未知上下文将由工厂自动添加到context中。

发送消息

一旦您拥有服务和消息，发送就变得容易。

use MCP\Logger\Logger;
use QL\MCP\Logger\Serializer\LineSerializer;
use QL\MCP\Logger\Service\ErrorLogService;

$serializer = new LineSerializer;

$service = new ErrorLogService([
    ErrorLogService::CONFIG_TYPE => ErrorLogService::FILE,
    ErrorLogService::CONFIG_FILE => '/var/log/myappmessages'
]);

$formatted = $serializer($message);
$service->send($message->severity(), $formatted);

服务

错误日志服务

此服务通过PHP函数error_log()发送日志消息文档。ErrorLog轻松提供了将消息发送到操作系统、SAPI（例如NGINX）或文件的能力。

应使用JSONSerializer或LineSerializer来使用此服务。

use MCP\Logger\Logger;
use MCP\Logger\Serializer\LineSerializer;
use MCP\Logger\Service\ErrorLogService;

$serializer = new LineSerializer;

$service = new ErrorLogService([
    ErrorLogService::CONFIG_TYPE => ErrorLogService::FILE
    ErrorLogService::CONFIG_FILE => '/var/log/mcplogger'
]);

$logger = new Logger($service, $serializer);
$logger->error('The MCP is the most efficient way of handling what we do!');

系统日志服务

此服务允许您直接将日志消息发送到Syslog。从那里，消息可以发送到文件、中心Syslog服务器或到日志收集器，如Splunk或LogEntries。这些目标必须由系统管理员进行配置。

应使用JSONSerializer或LineSerializer来使用此服务。

use MCP\Logger\Logger;
use MCP\Logger\Serializer\JSONSerializer;
use MCP\Logger\Service\SyslogService;

$serializer = new JSONSerializer;
$service = new SyslogService([
    // Ident SHOULD always be provided, to allow log filtering at the system-level.
    SyslogService::CONFIG_IDENT => 'MyAppName',
    SyslogService::CONFIG_FACILITY => LOG_USER,
    SyslogService::CONFIG_OPTIONS => LOG_ODELAY | LOG_CONS
]);

$logger = new Logger($service, $serializer);

$logger->error("That MCP, that's half our problem right there.");

Guzzle服务

此服务使用Guzzle通过HTTP发送日志消息。目前支持Guzzle 6。

应使用JSONSerializer或XMLSerializer来使用此服务。

use GuzzleHttp\Client;
use MCP\Logger\Logger;
use MCP\Logger\Serializer\XMLSerializer;
use MCP\Logger\Service\GuzzleService;

$serializer = new XMLSerializer;
$service = new GuzzleService('https:///log/endpoint', new Client);

$logger = new Logger($service, $serializer);
$logger->error("You've enjoyed all the power you've been given, haven't you?");

空服务

空服务，也称为“黑洞”服务，将忽略所有日志消息。这在您不想发送任何日志的环境或情况下很有用。

use MCP\Logger\Logger;
use MCP\Logger\Service\NullService;

$service = new NullService;
$logger = new Logger($service);

$logger->error("There's nothing special about you. You're just an ordinary program.");

日志消息

QL\MCP\Logger\MessageInterface

有关消息接口，请参阅MessageInterface。Message对象具有以下属性：

use QL\MCP\Logger\Message\Message;

$message = new Message('info', 'test message');

# Property                              # Context

$message->id();                         # 'id'
$message->message();                    # N/A
$message->severity();                   # N/A
$message->context();                    # N/A - extra keys no mentioned elsewhere
$message->details();                    # 'details'
$message->created();                    # 'created' (TimePoint)
$message->applicationID();              # 'applicationID'

// Server details
$message->serverEnvironment();          # 'serverEnvironment'
$message->serverIP();                   # 'serverIP'
$message->serverHostname();             # 'serverHostname'

// Request details
$message->requestMethod();              # 'requestMethod'
$message->requestURL();                 # 'requestURL'

// User details
$message->userAgent();                  # 'userAgent'
$message->userIP();                     # 'userIP'

这些中的每一个都可以通过在构建消息时向数据数组添加key => value对或在调用记录器时的消息上下文中设置。

ql / mcp-logger

维护者

详细信息