README

您可能还对我们以下项目感兴趣：Laravel 5, 6 或 7，Laravel Lumen 服务提供者或Monolog Understanding.io 处理程序

简介

此包提供了对 Understanding.io 的完全抽象，并提供了额外功能来提高 Laravel 默认日志记录功能。它本质上是一个围绕 Laravel 事件处理程序的包装，以充分利用 Understanding.io 的数据聚合和分析能力。

快速入门

将此包添加到您的 composer.json 文件中
```
"understand/understand-laravel4": "0.0.*"
```
更新 composer.json 中的包
```
composer update
```
将 ServiceProvider 添加到 app/config/app.php 中的 providers 数组
```
'Understand\UnderstandLaravel\UnderstandLaravelServiceProvider',
```

发布配置文件

php artisan config:publish understand/understand-laravel

在配置文件中设置您的输入密钥
```
'token' => 'my-input-token'
```

发送第一个事件

// anywhere inside your Laravel app
\Log::info('Understand.io test');

如何发送事件/日志

Laravel 日志

默认情况下，Laravel 会自动将日志存储在 app/storage/logs。使用此包后，您的日志也可以发送到您的 Understanding.io 频道。这包括错误和异常日志，以及您定义的任何日志事件（例如，Log::info('我的自定义日志')）。

\Log::info('my message', ['my_custom_field' => 'my data']);

Laravel 日志文档

PHP/Laravel 异常

默认情况下，所有异常都将发送到 Understanding.io 服务。

Eloquent 模型日志

每当 Eloquent 的 created、updated、deleted 或 restored 事件之一被触发时，都会生成 Eloquent 模型日志。这允许您自动跟踪模型的所有更改，并将包含当前模型差异（$model->getDirty()）、事件类型（创建、更新等）以及附加元数据（用户 ID、会话 ID 等）。这意味着所有模型事件都将转换为日志事件，并发送到 Understanding.io。

默认情况下模型日志是禁用的。要启用模型日志，可以将配置值设置为 true

'log_types' => [
    'eloquent_log' => [
        'enabled' => true,

附加元数据（字段提供者）

您可能希望在每个事件中捕获附加的元数据。例如，捕获异常中的请求 URL 可能非常有用，或者您可能想捕获当前用户的 ID。为此，您可以通过配置指定自定义字段提供者。

/**
 * Specify additional field providers for each log
 * E.g. sha1 version session_id will be appended to each "Log::info('event')"
 */
'log_types' => [
    'eloquent_log' => [
        'enabled' => false,
        'meta' => [
            'session_id' => 'UnderstandFieldProvider::getSessionId',
            'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
            'user_id' => 'UnderstandFieldProvider::getUserId',
            'env' => 'UnderstandFieldProvider::getEnvironment',
            'client_ip' => 'UnderstandFieldProvider::getClientIp',
        ]
    ],
    'laravel_log' => [
        'enabled' => true,
        'meta' => [
            'session_id' => 'UnderstandFieldProvider::getSessionId',
            'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
            'user_id' => 'UnderstandFieldProvider::getUserId',
            'env' => 'UnderstandFieldProvider::getEnvironment',
        ]
    ],
    'exception_log' => [
        'enabled' => true,
        'meta' => [
            'session_id' => 'UnderstandFieldProvider::getSessionId',
            'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
            'user_id' => 'UnderstandFieldProvider::getUserId',
            'env' => 'UnderstandFieldProvider::getEnvironment',
            'url' => 'UnderstandFieldProvider::getUrl',
            'method' => 'UnderstandFieldProvider::getRequestMethod',
            'client_ip' => 'UnderstandFieldProvider::getClientIp',
            'user_agent' => 'UnderstandFieldProvider::getClientUserAgent'
        ]
    ]
]

Understanding.io 服务提供者包含一个功能强大的字段提供者类，它提供了默认提供者，您还可以创建或扩展新的提供者。

dd(UnderstandFieldProvider::getSessionId()); 
// output: c624e355b143fc050ac427a0de9b64eaffedd606

默认字段提供者

以下字段提供者包含在此包中

getSessionId - 返回会话 ID 的 sha1 版本
getRouteName - 返回当前路由名称（例如 clients.index）。
getUrl - 返回当前 URL（例如 /my/path?with=querystring）。
getRequestMethod - 返回请求方法（例如 POST）。
getServerIp - 返回服务器 IP。
getClientIp - 返回客户端 IP。
getClientUserAgent - 返回客户端的用户代理。
getEnvironment - 返回 Laravel 环境（例如 production）。
getProcessIdentifier - 返回每个请求唯一的唯一令牌。这允许您轻松地将单个请求中发生的所有事件分组。
getUserId - 返回当前用户ID。仅在您确保使用默认的Laravel认证或cartalyst/sentry包时可用。如果您使用的是不同的认证包，则可以扩展getUserId字段提供者并实现自己的逻辑。

如何扩展创建您自己的方法或扩展字段提供者

UnderstandFieldProvider::extend('getMyCustomValue', function()
{
    return 'my custom value';
});

UnderstandFieldProvider::extend('getCurrentTemperature', function()
{
    return \My\Temperature\Provider::getRoomTemperature();
});

示例

假设您已经定义了一个名为getCurrentTemperature的自定义字段提供者（如上所示）。然后您应该在配置文件中添加如下内容：

    'laravel_log' => [
        'meta' => [
            ...
            'temperature' => 'UnderstandFieldProvider::getCurrentTemperature',
            ...
        ]
    ],

此附加元数据将自动附加到您的所有Laravel日志事件中（Log::info('my_custom_event')），并显示如下：

{
  "message": "my_custom_event",
  "custom_temperature":"23"
}

如何异步发送数据

异步处理器

默认情况下，每个日志事件都会在事件发生后直接发送到Understand.io的API服务器。如果您生成大量日志，这可能会减慢您的应用程序速度，在这种情况下，我们建议您使用异步处理器。要实现此目的，将配置参数handler更改为async。

/**
 * Specify which handler to use - sync, queue or async. 
 * 
 * Note that the async handler will only work in systems where 
 * the CURL command line tool is installed
 */
'handler' => 'async',

异步处理器在大多数系统中都受支持 - 唯一的要求是CURL命令行工具已安装并正常工作。要检查您的系统上是否有CURL，请在您的控制台中执行以下命令：

curl -h

如果您看到如何使用CURL的说明，则您的系统已安装CURL二进制文件，您可以使用async处理器。

请注意，Laravel允许您在不同的环境中指定不同的配置值。例如，您可以在生产中使用异步处理器，在开发中使用同步处理器。

Laravel队列处理器

虽然我们通常建议使用异步处理器，但使用队列也是另一种选择。请注意，默认情况下Laravel队列是sync，因此您仍然需要使用类似iron.io或Amazon SQS的工具正确配置您的队列。有关更多信息，请参阅https://laravel.net.cn/docs/queues。

配置

return [

    /**
     * Input key
     */
    'token' => 'your-input-token-from-understand-io',

    /**
     * Specifies whether logger should throw an exception of issues detected
     */
    'silent' => true,

    /**
     * Specify which handler to use - sync, queue or async. 
     * 
     * Note that the async handler will only work in systems where 
     * the CURL command line tool is installed
     */
    'handler' => 'sync', 
    
    'log_types' => [
        'eloquent_log' => [
            'enabled' => false,
            'meta' => [
                'session_id' => 'UnderstandFieldProvider::getSessionId',
                'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
                'user_id' => 'UnderstandFieldProvider::getUserId',
                'env' => 'UnderstandFieldProvider::getEnvironment',
                'client_ip' => 'UnderstandFieldProvider::getClientIp',
            ]
        ],
        'laravel_log' => [
            'enabled' => true,
            'meta' => [
                'session_id' => 'UnderstandFieldProvider::getSessionId',
                'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
                'user_id' => 'UnderstandFieldProvider::getUserId',
                'env' => 'UnderstandFieldProvider::getEnvironment',
            ]
        ],
        'exception_log' => [
            'enabled' => true,
            'meta' => [
                'session_id' => 'UnderstandFieldProvider::getSessionId',
                'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
                'user_id' => 'UnderstandFieldProvider::getUserId',
                'env' => 'UnderstandFieldProvider::getEnvironment',
                'url' => 'UnderstandFieldProvider::getUrl',
                'method' => 'UnderstandFieldProvider::getRequestMethod',
                'client_ip' => 'UnderstandFieldProvider::getClientIp',
                'user_agent' => 'UnderstandFieldProvider::getClientUserAgent'
            ]
        ]
    ]

];

要求

UTF-8

此包使用json_encode函数，该函数仅支持UTF-8数据，因此您应该确保所有数据都正确编码。如果您的日志数据包含非UTF-8字符串，则json_encode函数将无法序列化数据。

https://php.ac.cn/manual/en/function.json-encode.php

许可协议

Laravel Understand.io服务提供者是开源软件，受MIT许可协议许可。

理解 / 理解-laravel4

维护者

详细信息