README

简介

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

快速开始

1. 将包添加到项目中

composer require understand/understand-laravel

1. 将服务提供者添加到 config/app.php 中的 providers 数组

Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider::class,

1. 在 .env 文件中设置您的 Understand.io 输入令牌

UNDERSTAND_ENABLED=true
UNDERSTAND_TOKEN=your-input-token-from-understand-io

1. 发送第一个错误

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

• 我们建议您使用异步处理程序 - 如何异步发送数据
• 如果您使用的是 Laravel 5.0 (>= 5.0, < 5.1) 版本，请阅读有关 - 如何报告 Laravel 5.0 异常 的信息。
• 有关高级配置，请阅读有关 - 高级配置 的信息
• Laravel 的 JavaScript 错误跟踪 - Understand.io JavaScript 库

如何发送事件/日志

Laravel 日志

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

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

PHP/Laravel 异常

默认情况下，所有带有代码片段和堆栈跟踪的错误和异常都将发送到 Understand.io。

以下额外的信息将被收集

此外，您还可以指定不应发送到 Understand.io 的 HTTP 请求字段值。默认情况下，以下字段值将被隐藏

UNDERSTAND_HIDDEN_REQUEST_FIELDS=password,password_confirmation,access_token,secret_key,token,access_key

如果您愿意，可以发布配置文件并进行所需的调整。请参阅 高级配置

如何异步发送数据

异步处理程序

默认情况下，每个日志事件都会在事件发生后直接发送到 Understand.io 的 API 服务器。如果您生成大量的日志，这可能会降低您的应用程序速度，在这些情况下，我们建议您使用异步处理程序。要这样做，请将配置参数 UNDERSTAND_HANDLER 设置为 async 到您的 .env 文件中。

# 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
UNDERSTAND_HANDLER=async

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

curl -h

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

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

如何报告 Laravel 5.0 (>= 5.0, < 5.1) 异常

Laravel（版本 >= 5.0，< 5.1）的异常日志记录器不使用事件调度器（laravel/framework#10922），因此您需要在您的 Handler.php 文件中添加以下行（否则 Laravel 的异常将不会发送到 Understand.io）。

• 打开 app/Exceptions/Handler.php 并在 report 方法内部添加此行 \UnderstandExceptionLogger::log($e)。

  public function report(Exception $e)
  {
      \UnderstandExceptionLogger::log($e);
  
      return parent::report($e);
  }

高级配置

1. 发布配置文件

php artisan vendor:publish --provider="Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider"

日志过滤器

要过滤特定日志类型，可以提供自定义日志过滤器。

示例过滤器类

// app/Logging/UnderstandLogFilter.php
<?php

declare(strict_types=1);

namespace App\Logging;

use Illuminate\Support\Str;

class UnderstandLogFilter
{
    public function __invoke($level, $message, $context): bool
    {
        if ($level === 'warning' && Str::contains(strtolower($message), 'deprecated')) {
            return true;
        }

        return false;
    }
}

然后可以在 understand-laravel.php 中进行配置

<?php
// ...
// config/understand-laravel.php
'log_filter' => \App\Logging\UnderstandLogFilter::class,

log_filter 配置值必须是一个可调用类型

• https://php.ac.cn/manual/en/function.is-callable.php
  或者来自服务容器的一个可调用依赖项
• https://laravel.net.cn/docs/9.x/container#the-make-method

建议的方式是创建一个可调用的类，因为匿名函数很难序列化（Laravel 配置缓存）

• https://php.ac.cn/manual/en/language.oop5.magic.php#object.invoke

日志过滤器接口必须如下所示：$callable($level, $message, $context)。过滤器的结果必须是一个布尔值

• TRUE，日志应该被忽略并且不发送到 Understand.io
• FALSE，日志应该发送到 Understand.io

ignored_logs 配置值比 log_filter 有更高的优先级。

要求

UTF-8

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

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

许可证

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