README

简介

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

快速开始

1. 将包添加到您的项目中

composer require understand/understand-laravel

1. 将 ServiceProvider 添加到 config/app.php 文件中的 providers 数组

Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider::class,

1. 在您的 .env 文件中设置 Understanding.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 错误跟踪 - Understanding.io JavaScript 库

如何发送事件/日志

Laravel 日志

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

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

PHP/Laravel 异常

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

以下额外信息将被收集

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

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

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

如何异步发送数据

异步处理程序

默认情况下，每个日志事件都会在事件发生后直接发送到 Understanding.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 文件，并将 \UnderstandExceptionLogger::log($e) 这行代码放在 report 方法内部。

  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 许可协议