README

Repository

ami-praha/ai-logger
Description: A Laravel package providing a logging channel that sends log messages to an external webhook.

Overview

This package adds a custom Laravel logging channel called ai-logger. When used, it sends log messages (and context data) as JSON payloads to a configured webhook URL.

Installation

Require the package via Composer:

composer require ami-praha/ai-logger:"0.0.*"

No further configuration file publishing is necessary.

Configuration

Environment Variable

Set the webhook URL in your application's .env file:

AI_LOGGER_WEBHOOK_URL="http://ai-logger.test/api/receive"
AI_LOGGER_SOURCE_CODE="EXAMPLEAPP"
AI_LOGGER_SOURCE_NAME="Example App"
AI_LOGGER_SOURCE_URL="http://example-app.test"
AI_LOGGER_SOURCE_GIT_PROJECT_OWNER="EXP"
AI_LOGGER_SOURCE_GIT_PROJECT_NAME="example_app"
AI_LOGGER_SOURCE_JIRA_PROJECT_CODE="EXPAPP"
AI_LOGGER_SOURCE_JIRA_PARENT_PROJECT_KEY="EXPAPP-123"

Configuring Logging Channel

In Laravel's config/logging.php, add a new channel ai-logger. Also if you are using a stack channel and want to automatically send any logs to ai-logger (recommended), add it to stack.channels array:

// config/logging.php
return [
    'default' => env('LOG_CHANNEL', 'stack'),

    'channels' => [
        // other channels...

        'stack' => [
            'driver' => 'stack',
            'channels' => ['single', 'slack', 'ai-logger'],
        ],

        'ai-logger' => [
            'driver' => 'ai-logger',
            'webhookUrl' => env('AI_LOGGER_WEBHOOK_URL'),
            'sourceCode' => env('AI_LOGGER_SOURCE_CODE'),
            'sourceName' => env('AI_LOGGER_SOURCE_NAME'),
            'sourceUrl' => env('AI_LOGGER_SOURCE_URL'),
            'sourceGitProjectOwner' => env('AI_LOGGER_SOURCE_GIT_PROJECT_OWNER'),
            'sourceGitProjectName' => env('AI_LOGGER_SOURCE_GIT_PROJECT_NAME'),
            'sourceJiraProjectCode' => env('AI_LOGGER_SOURCE_JIRA_PROJECT_CODE'),
            'sourceJiraParentProjectKey' => env('AI_LOGGER_SOURCE_JIRA_PARENT_PROJECT_KEY'),
            'codeSnippets' => env('AI_LOGGER_CODE_SNIPPETS', true), // optional, see "Exceptions" below
            'level' => 'warning',
        ],
    ],
];

Usage

To log using AI Logger, specify the ai-logger channel in your code:

use Illuminate\Support\Facades\Log;

Log::channel('ai-logger')->info('Hello from AI Logger', ['extra_data' => 'test']);

// Other log levels work similarly
Log::channel('ai-logger')->error('Something went wrong.', [
    'exception' => 'Some exception info',
]);

This will send the log message, context data and log level as a JSON payload to the configured webhook URL. The time the log was written is sent as debug_data.logged_at (ISO 8601 with microseconds), and data of Laravel's Context (or of any Monolog processor of the channel) as debug_data.extra.

Exceptions

An exception logged as context.exception (as Laravel's exception handler does) is sent with its type, message, code, file, line and stack trace, and also with:

previous – the exception that caused it, nested the same way (each with type, message, code, file, line and its own previous), up to 5 levels deep.
snippets – the code around the line the exception and its causes were thrown on and around the lines of the first stack frames, for up to 4 locations in the application's own files (never vendor/ or node_modules/). Each one is file, line and code, the numbered lines with the line itself marked by >. Set codeSnippets to false not to send any code.

The stack trace is cut to its first 100 frames; trace_omitted_frames then says how many were left out.

Anything else logged as context.exception is sent as it is.

Console and queue context

Logs written from artisan commands and queued jobs describe where they came from instead of a fake request:

debug_data.command – the console command line, e.g. artisan reports:send --month=9. Values of secret-looking options (--password=…, --api-token …, --*secret*, --*key*, …) are replaced with ***.
debug_data.queue_job – the queued job being run: name (job class), queue, connection, attempt, max_tries and uuid. It is also sent for jobs run synchronously during an HTTP request.
In console, debug_data.url, debug_data.method and the ip / user_agent of user_tracking_data are left out, since Laravel only fakes them from APP_URL.
performance_data.execution_time of a log written during a queued job is measured from the start of the job, not of the worker.

Testing the connection

To check that the app can actually send logs to AI Logger, run:

php artisan ai-logger:test

The command sends a test error through the ai-logger channel (choose another one with --channel=…) and tells whether AI Logger received it. If it did not, the command says why: the channel is not defined or does not use the ai-logger driver, its level is above error, the config is incomplete, the webhook URL cannot be reached or redirects, or AI Logger rejected the log (with its validation errors). It also warns when the default log channel does not send to the ai-logger channel, since then the errors the app logs itself never reach AI Logger.

The exit code is 0 when AI Logger received the test error and 1 otherwise, so the command can be used in deploy scripts.

The test error is a real log in AI Logger. Its context holds ai_logger_test: true, and its message and context are the same every time, so all test errors of an app are grouped into one issue. The first test of an app opens that issue, which can send alerts like any new issue.

When the app logs, failed deliveries are not shown anywhere but in storage/logs/ai_logger_critical.log.

Requirements

PHP: ^8.2
Laravel: ^10.0 | ^11.0 | ^12.0 | ^13.0

Contributing

Contributions are welcome!

Fork and create a feature branch.
Submit your changes through a Pull Request.
Provide a clear description of your updates.

For bugs or feature requests, please create an issue on GitHub.

License

Licensed under the MIT License.

Thank you for using AI Logger! If you have questions, open an issue on GitHub or contact the maintainer.

ami-praha / ai-logger

Package info

Security

Statistics