理解/理解-lumen

Understand.io Laravel Lumen 服务提供者。

维护者

详细信息

github.com/understand/understand-lumen

主页

源代码

问题

安装: 664

依赖者: 0

建议者: 0

安全: 0

星标: 6

关注者: 4

分支: 2

开放问题: 0

v1.0.1 2016-01-28 08:31 UTC

Requires

Requires (Dev)

MIT 300603160e633d267deacad8d499b4efdf8c9a0c

loglogginglaravelunderstandlumenUnderstand.io

This package is not auto-updated.

Last update: 2024-09-23 06:33:51 UTC

README

Understand.io 的 Laravel Lumen 服务提供者

Build Status Latest Stable Version Latest Unstable Version License HHVM Status Scrutinizer Code Quality

您可能还感兴趣：我们的 Laravel 4，Laravel 5 服务提供者 或 Monolog Understand.io 处理器

简介

此软件包为 Understand.io 提供了完整的抽象，并提供额外的功能来改进 Lumen 的默认日志记录能力。它本质上是我们 Understand Monolog 处理器 的包装，以充分利用 Understand.io 的数据聚合和分析能力。

快速开始

  1. 通过 composer 将此软件包添加到您的项目中

    composer require understand/understand-lumen

  2. 在 bootstrap/app.php 中启用 Dotenv（大约第 5 行）和 $app->withFacades();（大约第 22 行）

    Dotenv::load(__DIR__.'/../'); // around line 5

...

$app->withFacades(); // around line 22

  3. 在 bootstrap/app.php 中注册 UnderstandLumenServiceProvider

    $app->register(Understand\UnderstandLumen\UnderstandLumenServiceProvider::class);

  4. 创建一个新的文件 config/understand_lumen.php（注意您可能需要创建 config 目录），内容如下

    <?php

return [

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

    /**
     * Your input token from Understand.io
     */
    'token' => env('UNDERSTAND_INPUT_KEY'),

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

    /**
     * Specify additional field providers for each log
     * E.g. sha1 version session_id will be appended to each "Log::info('event')"
     */
    'meta' => [
        'user_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUserId',
        'session_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId',
        'request_id' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getProcessIdentifier',
        'url'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUrl',
        'client_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientIp',
        //'server_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getServerIp',
        //'user_agent' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientUserAgent',
        //'environment' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getEnvironment',
        //'request_method'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getRequestMethod',
    ],
];

  5. 将您的输入密钥（来自 Understand.io）设置在您的 .env 文件中作为 UNDERSTAND_INPUT_KEY

    UNDERSTAND_INPUT_KEY=your-input-key-from-understand

  6. 打开 app/Exceptions/Handler.php 并调整 report 方法

    public function report(Exception $e)
{
    $encoder = new \UnderstandMonolog\Encoder\ExceptionEncoder();

    app('Psr\Log\LoggerInterface')->error($e->getMessage(), $encoder->exceptionToArray($e));
}

  7. 发送第一个事件

    $app->get('/', function () use ($app) {

    Log::info('test log 123');

    return $app->welcome();
});

额外的元数据（字段提供者）

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

/**
 * Specify additional field providers for each log
 * E.g. sha1 version session_id will be appended to each "Log::info('event')"
 */
'meta' => [
    'user_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUserId',
    'session_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId',
    'request_id' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getProcessIdentifier',
    'url'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUrl',
    'client_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientIp',
    //'server_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getServerIp',
    //'user_agent' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientUserAgent',
    //'environment' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getEnvironment',
    //'request_method'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getRequestMethod',
],

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

dd(Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId());
// output: c624e355b143fc050ac427a0de9b64eaffedd606

默认字段提供者

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

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

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

Understand\UnderstandLumen\UnderstandFieldProviderFacade::extend('getMyCustomValue', function()
{
    return 'my custom value';
});

dd(Understand\UnderstandLumen\UnderstandFieldProviderFacade::getMyCustomValue());

示例

假设您已经定义了一个名为 getMyCustomValue 的自定义字段提供者（如上所示）。然后，您应该将其添加到配置文件中，如下所示

'meta' => [
    ...
    'custom_value' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getMyCustomValue',
    ...
]

这些额外的元数据将自动附加到您的所有 Lumen 日志事件（例如 Log::info('my_custom_event')），并如下所示显示

{
  "message": "my_custom_event",
  "custom_value":"my custom value"
}

如何异步发送数据

异步处理器

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

/**
 * Specify which handler to use - sync 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处理程序。

请记住，Lumen允许您在不同环境中指定不同的配置值。例如，您可以在生产环境中使用异步处理程序，在开发环境中使用同步处理程序。

配置

return [

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

    /**
     * Your input token from Understand.io
     */
    'token' => env('UNDERSTAND_INPUT_KEY'),

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

    /**
     * Specify additional field providers for each log
     * E.g. sha1 version session_id will be appended to each "Log::info('event')"
     */
    'meta' => [
        'user_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUserId',
        'session_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId',
        'request_id' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getProcessIdentifier',
        'url'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUrl',
        'client_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientIp',
        //'server_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getServerIp',
        //'user_agent' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientUserAgent',
        //'environment' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getEnvironment',
        //'request_method'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getRequestMethod',
    ],
];

要求

UTF-8

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

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

许可证

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