README

[[目录]]

概览

Audit包是一个开源的Composer包，用于Laravel应用程序，由其他Provisionesta包使用，以提供一致的日志语法，并添加对时间敏感事件数据库事务（即将发布）的支持。尽管这是为我们的包专门设计的，但您也可以将其用于自己的标准化日志。

此包由开源社区维护，不由任何公司维护。请自行承担风险，并创建合并请求来解决您遇到的任何错误。

问题陈述

当使用Laravel日志和Log::info('Message', ['key1' => 'value', 'key2' => 'value'])语法时，很容易出现日志格式不一致，从而导致各种日志消息和不同的上下文键。

Provisionesta\Audit\Log::create()方法提供一组预定义的上下文键，使我们能够改进外部日志平台中的索引和可搜索性，并确保所有事件都以一致的方式提供尽可能多的上下文数据。

有时您需要获取一个可以添加到变更日志或程序化操作的格式化数组，而不是尝试查看日志文件。每次创建日志条目时都会返回一个数组。

（即将发布）由于一些日志事件需要执行，此包添加了对audit_transactions数据库表的支持，允许您像管理后台作业队列一样集中管理，并根据您的应用程序和业务需求触发不同的操作和工作流程。

问题跟踪和错误报告

我们不维护功能请求路线图，但欢迎您贡献，我们乐意审查您的合并请求。

请创建问题来报告错误。

贡献

请参阅CONTRIBUTING.md了解如何贡献的更多信息。

维护者

贡献者致谢

• Jeff Martin

安装

需求

升级指南

查看变更日志以获取发布说明。

添加Composer包

composer require provisionesta/audit:^1.1

如果您正在为此包做出贡献，请参阅CONTRIBUTING.md了解如何配置具有符号链接的本地composer包的说明。

发布配置文件

这是可选的。如果将解析的日志条目作为变量返回，则使用自定义模式的配置文件。

php artisan vendor:publish --tag=audit

使用示例

基本用法

use Provisionesta\Audit\Log;

Log::create(
    event_ms: $event_ms,
    event_type: 'okta.api.post.success.ok',
    level: 'info',
    message: 'Success',
    metadata: [
        'okta_request_id' => 'REDACTED',
        'rate_limit_remaining' => $request->headers['x-rate-limit-remaining'],
        'uri' => 'users',
        'url' => 'https://dev-12345678.okta.com/api/v1/users?activate=true'
    ],
    method: __METHOD__
);

综合用法

您可以将此示例复制粘贴到代码中创建日志条目的任何位置。任何不相关的参数都可以删除，将被视为null。

use Provisionesta\Audit\Log;

Log::create(
    attribute_key: 'xxx',
    attribute_value_old: 'xxx',
    attribute_value_new: 'xxx',
    count_records: count($array),
    dump: false,
    dump_keys: [],
    duration_ms: $duration_ms,
    duration_ms_per_record: (int) ($duration_ms / count($records)),
    errors: [],
    event_ms: $event_ms,
    event_ms_per_record: (int) ($event_ms / count($records)),
    event_type: '{provider}.{entity}.{action}.xxx',
    level: 'info',
    log: true,
    message: '{What happened}',
    metadata: [],
    method: __METHOD__,
    occurred_at: $entity->created_at,
    parent_id: $parent->id,
    parent_type: 'App\\Models\\{Provider}\\Application',
    parent_reference_key: 'name',
    parent_reference_value: $entity->organization->name,
    record_id: $entity->id,
    record_type: 'App\\Models\\{Provider}\\{Entity}',
    record_provider_id: $entity->provider_id,
    record_reference_key: 'name',
    record_reference_value: $entity->name,
    tenant_id: $entity->provider_organization_id,
    tenant_type: 'App\\Models\\{Provider}\\Organization',
    transaction: false
);

示例输出

[YYYY-MM-DD HH:II:SS] local.DEBUG: ApiClient::post Success {"event_type":"okta.api.post.success.ok","method":"Provisionesta\\Okta\\ApiClient::post","event_ms":627,"metadata":{"okta_request_id":"REDACTED","rate_limit_remaining":"16","uri":"users","url":"https://dev-12345678.okta.com/api/v1/users?activate=true"}"}

{
    "event_type": "okta.api.post.success.ok",
    "method": "Provisionesta\\Okta\\ApiClient::post",
    "event_ms": 627,
    "metadata": {
        "okta_request_id": "REDACTED",
        "rate_limit_remaining": "16",
        "uri": "users",
        "url": "https://dev-12345678.okta.com/api/v1/users?activate=true"
    }
}

日志参数定义

 with the fully-qualified method name (the "noun") so you can keep
 the message focused on the "verb" language.</td>

高级用法

后台任务日志条目

如果您正在运行后台任务并且想要将元数据添加到日志和事务中，您可以添加 job_* 参数。所有这些值（除 job_timestamp 外）都是自由格式字符串，您可以根据需要标准化。

use Provisionesta\Audit\Log;

Log::create(
    // ...
    job_batch: '{string}',
    job_id: '{string}',
    job_platform: '{string}',
    job_pipeline_id: '{string}',
    job_timestamp: now()->getTimestamp(),
    job_transaction_id: '{string}',
    // ...
);

跳过日志创建

您可以指定 log 和 transaction 参数的真/假布尔值。默认情况下，log 为 true，transaction 为 false。

解析和格式化的模式始终以数组的形式返回。

响应模式

此包的一个优点是具有可预测键的格式化数组。

作为创建事务的替代方案，您也可以返回一个格式化的数组，包含所有提供的键及其值（或其默认值）。如果您只需要一个数组用于自己的变更日志或其他用途，这将非常有用。您还可以禁用日志创建，并像使用数据传输对象（DTO）一样使用它。

只需定义一个变量以获取返回的数组。

use Provisionesta\Audit\Log;

// Create a log entry with no returned array
Log::create(
    // ...
    log: true
    // ...
);

// Define a variable with the returned array
$schema = Log::create(
    // ...
    log: true
    // ...
);

// Append the return array to an existing array of records that are not created in system logs
foreach($records as $record) {
    // ...

    $changelog[] = Log::create(
        // ...
        log: false
        // ...
    );
}

无配置的示例响应数组

use Provisionesta\Audit\Log;

$event_ms = now();

$result = Log::create(
    event_ms: $event_ms,
    event_type: "okta.api.post.success.ok",
    level: "info",
    message: "Success",
    metadata: [
        "okta_request_id" => "REDACTED",
        "rate_limit_remaining" => "199",
        "uri" => "users",
        "url" => "https://dev-12345678.okta.com/api/v1/users?activate=true"
    ],
    method: "Provisionesta\Okta\ApiClient::get"
);

dd($result);

// [
//     "datetime" => "2024-03-02T18:51:10+00:00",
//     "event_type" => "okta.api.post.success.ok",
//     "level" => "info",
//     "message" => "Success",
//     "method" => "Provisionesta\Okta\ApiClient::get",
//     "attribute_key" => null,
//     "attribute_value_old" => null,
//     "attribute_value_new" => null,
//     "count_records" => null,
//     "duration_ms" => null,
//     "duration_ms_per_record" => null,
//     "errors" => [],
//     "event_ms" => 4,
//     "event_ms_per_record" => null,
//     "job_batch" => null,
//     "job_id" => null,
//     "job_platform" => null,
//     "job_pipeline_id" => null,
//     "job_timestamp" => null,
//     "job_transaction_id" => null,
//     "metadata" => [
//       "okta_request_id" => "REDACTED",
//       "rate_limit_remaining" => "199",
//       "uri" => "users",
//       "url" => "https://dev-12345678.okta.com/api/v1/users?activate=true",
//     ],
//     "occurred_at" => null,
//     "parent_id" => null,
//     "parent_type" => null,
//     "parent_provider_id" => null,
//     "parent_reference_key" => null,
//     "parent_reference_value" => null,
//     "record_id" => null,
//     "record_type" => null,
//     "record_provider_id" => null,
//     "record_reference_key" => null,
//     "record_reference_value" => null,
//     "tenant_id" => null,
//     "tenant_type" => null,
// ]

在响应数组中指定键

模式中存在大量参数键。为了避免使用Laravel Collections的transform方法处理结果数组，您可以简单地将要包含的键数组传递给dump_keys数组。

use Provisionesta\Audit\Log;

$result = Log::create(
    // ...
    dump_keys: [
        'event_type',
        'message',
        'attribute_key',
        'attribute_value_old',
        'attribute_value_new',
        'record_id',
        'record_type',
        'record_provider_id',
        'record_reference_key',
        'record_reference_value'
    ],
);

dd($result);

// [
//     "datetime" => "2024-03-02T18:53:35+00:00",
//     "event_type" => "okta.api.post.success.ok",
//     "message" => "Success",
//     "attribute_key" => null,
//     "attribute_value_old" => null,
//     "attribute_value_new" => null,
//     "record_id" => null,
//     "record_type" => null,
//     "record_provider_id" => null,
//     "record_reference_key" => null,
//     "record_reference_value" => null,
// ]

在响应数组中指定自定义静态字符串

如果您需要向数组中添加自定义静态字符串，它们可以在dump_strings数组中指定。字符串将返回到数组末尾。

use Provisionesta\Audit\Log;

$result = Log::create(
    // ...
    dump_keys: [
        'event_type',
        'message',
        'attribute_key',
        'attribute_value_old',
        'attribute_value_new',
        'record_id',
        'record_type',
        'record_provider_id',
        'record_reference_key',
        'record_reference_value'
    ],
    dump_strings: [
        'custom_key' => 'my_value',
        'another_key' => 'my_value',
    ],
    // ...
);

dd($result);

// [
//     "datetime" => "2024-03-02T18:54:55+00:00",
//     "event_type" => "okta.api.post.success.ok",
//     "message" => "Success",
//     "attribute_key" => null,
//     "attribute_value_old" => null,
//     "attribute_value_new" => null,
//     "record_id" => null,
//     "record_type" => null,
//     "record_provider_id" => null,
//     "record_reference_key" => null,
//     "record_reference_value" => null,
//     "custom_key" => "my_value",
//     "another_key" => "my_value",
// ]

响应数组中的自定义日期时间格式

datetime始终返回为数组的第一个键（表列）。您可以使用支持的PHP日期时间格式字符来自定义格式。默认情况下，我们使用c来表示ISO 8601格式（YYYY-MM-DDTHH:II:SS+00:00）。您可能想将其简化为Y-m-d或Y-m-d H:i。

use Provisionesta\Audit\Log;

$result = Log::create(
    // ...
    dump_date: 'c',
    dump_keys: [
        'event_type',
        'message',
        'attribute_key',
        'attribute_value_old',
        'attribute_value_new',
        'record_id',
        'record_type',
        'record_provider_id',
        'record_reference_key',
        'record_reference_value'
    ],
    dump_strings: [
        'custom_key' => 'my_value',
        'another_key' => 'my_value',
    ],
    // ...
);

dd($result);

// [
//     "datetime" => "2024-03-02",
//     "event_type" => "okta.api.post.success.ok",
//     // ....
// ]

响应数组的标准化配置

提示：您需要发布配置文件，以便它在config/audit.php中显示。如果不发布，它将使用vendor/provisionesta/audit目录中的默认配置，该配置无法修改。

管理代码库中的简化模式可能会很困难。

您可以在config/audit.php文件中为每个用例定义标准化的简化模式。default键是一个占位符，可以自定义，并且如果需要，您可以添加额外的数组以处理每种类型的资源（例如okta_user）。

定义模式后，只需将dump_config键设置为其在config/audit.php中定义的相同键。

use Provisionesta\Audit\Log;

$result = Log::create(
    // ...
    dump_config: 'okta_user'
    // ...
);

// config/audit.php

return [
    'dump' => [
        'default' => [
            'date' => 'c'
            'strings' => [
                'custom_key' => 'my_value'
            ],
            'keys' => [
                'event_type',
                'message',
                'record_id',
                'record_type',
                'record_provider_id',
                'record_reference_key',
                'record_reference_value'
            ],
        ],
        'okta_user' => [
            'date' => 'c',
            'strings' => [
                'custom_key' => 'my_value'
            ],
            'keys' => [
                'event_type',
                'message',
                'attribute_key',
                'attribute_value_old',
                'attribute_value_new',
                'record_id',
                'record_type',
                'record_provider_id',
                'record_reference_key',
                'record_reference_value'
            ]
        ]
    ]
];

响应数组的实际示例

use Provisionesta\Audit\Log;

$result = Log::create(
    attribute_key: $attribute,
    attribute_value_old: $manifest_record[$attribute],
    attribute_value_new: $api_record[$attribute],
    duration_ms: $this->duration_ms,
    event_type: $this->event_type . '.datadumper.manifest.attribute.changed.' . $attribute,
    level: 'info',
    log: true
    message: Str::title($attribute) . ' Attribute Value Changed',
    method: __METHOD__,
    record_provider_id: $manifest_record['provider_id'],
    record_reference_key: $this->reference_key,
    record_reference_value: $manifest_record[$this->reference_key] ?? null,
    transaction: true
);

dd($result);

// [
//     'datetime' => 'YYYY-MM-DDTHH:II:SS+00:00',
//     'event_type' => 'okta.user.sync.datadumper.manifest.attribute.changed.manager',
//     'message' => 'Manager Attribute Value Changed',
//     'attribute_key' => 'manager',
//     'attribute_value_old' => 'klibby',
//     'attribute_value_new' => 'dmurphy',
//     'record_id' => null,
//     'record_type' => 'okta_user',
//     'record_provider_id' => '00u1b2c3d4e5f6g7h8i9',
//     'record_reference_key' => 'handle',
//     'record_reference_value' => 'jpardella'
//     'custom_key' => 'my_value',
// ]