sameoldnick / laravel-open-observe

v2.1.0 2026-11-06 19:02 UTC

Requires

• php: ^8.4
• illuminate/contracts: ^12.0||^13.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/fortify: ^1.37
• laravel/pint: ^1.30
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Nick Hamnett

• laravel
• openobserve
• SameOldNick
• laravel-open-observe

Published on Packagist.org on 2026-11-06 19:02 UTC

README

A Laravel package for sending application logs to OpenObserve.

Table of Contents

• Requirements
• Installation
• Configuration
  • Configuration options
  • Response verification and failures
  • Exception reporting
• Usage
• Testing the connection
  • Programmatic usage
• Laravel Boost
• Development
• Security
• License

Requirements

• PHP 8.4 or later
• Laravel 12, or 13

Installation

You can install the package via Composer:

composer require sameoldnick/laravel-open-observe

The package loads its configuration automatically. To publish a copy of the configuration file to your application, run:

php artisan vendor:publish --tag=openobserve-config

This publishes config/openobserve.php, which you can customize for exception reporting and other package settings.

Configuration

Add a new logging channel to config/logging.php:

return [
    // ...
    'channels' => [
        // ...
        'openobserve' => [
            'driver' => 'openobserve',
            'name' => env('OPENOBSERVE_LOGGER_NAME', 'openobserve'),
            'base_url' => env('OPENOBSERVE_URL', ''),
            'organization' => env('OPENOBSERVE_ORGANIZATION', 'default'),
            'stream' => env('OPENOBSERVE_STREAM', ''),
            'auth' => [
                // Alternatively, paste the Authorization header value from an ingest token.
                // When set, 'token' takes precedence over the username and password.
                // 'token' => env('OPENOBSERVE_TOKEN'),
                'username' => env('OPENOBSERVE_USERNAME'),
                'password' => env('OPENOBSERVE_PASSWORD'),
            ],
            'http_options' => [
                'timeout' => env('OPENOBSERVE_HTTP_TIMEOUT', 5),
                'connect_timeout' => env('OPENOBSERVE_HTTP_CONNECT_TIMEOUT', 5),
                'verify_response' => env('OPENOBSERVE_VERIFY_RESPONSE', true),
            ],
            'level' => env('OPENOBSERVE_LOG_LEVEL', 'debug'),
            'bubble' => true,
        ],
    ]
];

The package registers the openobserve logging driver. If you prefer Laravel's custom driver, you can still use 'driver' => 'custom' with 'via' => \SameOldNick\OpenObserve\Factories\CreateOpenObserveLogger::class.

The following environment variables can be set in your .env file to configure the logger:

# OpenObserve logging configuration. If you want to forward logs to OpenObserve, set the URI and credentials below.
#OPENOBSERVE_LOGGER_NAME=openobserve
#OPENOBSERVE_URL=https://logs.openobserve.com
#OPENOBSERVE_ORGANIZATION=default
#OPENOBSERVE_STREAM=your-stream
#OPENOBSERVE_USERNAME=your-username
#OPENOBSERVE_PASSWORD=your-password
#OPENOBSERVE_TOKEN="Basic <base64-encoded-username:password>"
#OPENOBSERVE_HTTP_TIMEOUT=5
#OPENOBSERVE_HTTP_CONNECT_TIMEOUT=5

Configuration options

Option	Required	Description
base_url	Yes	The base URL of your OpenObserve instance, such as https://openobserve.example.com.
organization	Yes	The OpenObserve organization used in the API path.
stream	Yes	The default stream that log entries are written to.
auth.username / auth.password	No	Basic authentication credentials. Authentication is omitted when both are empty.
auth.token	No	Full Authorization header value (including the scheme), such as the one copied from an ingest token. Takes precedence over auth.username and auth.password.
http_options	No	Options passed to Laravel's HTTP client, such as timeout and connect_timeout.
http_options.verify_response	No	Verifies the OpenObserve response body. Defaults to true.
name	No	The logger name included in each log record. Defaults to openobserve.
level	No	The minimum Monolog level to send. Defaults to debug.
bubble	No	Whether records may bubble to subsequent Monolog handlers. Defaults to true.

Single log entries are sent to /api/{organization}/{stream}/_json; batched entries use /api/{organization}/{stream}/_multi.

Using an ingest token

OpenObserve presents ingest tokens as a complete Authorization header value, such as Basic dXNlcjpwYXNzd29yZA==. Paste that value into auth.token (or OPENOBSERVE_TOKEN) instead of decoding it into a username and password:

'auth' => [
    'token' => env('OPENOBSERVE_TOKEN'),
],

The value is used verbatim as the Authorization header, so include the scheme (Basic , Bearer , and so on). When auth.token is set, auth.username and auth.password are ignored.

Response verification and failures

With verify_response enabled, a response containing a non-2xx code or any failed entries throws a RuntimeException. HTTP and connection failures also throw, regardless of verify_response. Disable response verification only if you want to ignore OpenObserve body-level failures while still surfacing transport errors.

Exception reporting

To report Laravel exceptions to OpenObserve, register ReportsException in bootstrap/app.php:

use Illuminate\Foundation\Configuration\Exceptions;
use SameOldNick\OpenObserve\Handlers\ReportsException;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->report(
            ReportsException::create(config('openobserve.exceptions')),
        );
    })
    ->create();

The reporter uses the exceptions settings in config/openobserve.php and sends entries to the configured stream, which defaults to exceptions. You can disable exception reporting with OPENOBSERVE_EXCEPTIONS_ENABLED=false or filter exceptions with the should_report option.

Usage

The Log facade or the logs() helper can be used to send messages to OpenObserve:

use Illuminate\Support\Facades\Log;

Log::channel('openobserve')->info('This is a test log message.');
logs('openobserve')->info('Testing connection to OpenObserve.');

If OpenObserve is the default logging channel, you can log messages without specifying the channel:

use Illuminate\Support\Facades\Log;

Log::info('This is a test log message.');
logs()->info('Testing connection to OpenObserve.');
logger()->info('Testing connection to OpenObserve.');

To send logs to OpenObserve alongside another channel, add it to your stack channel:

'stack' => [
    'driver' => 'stack',
    'channels' => ['single', 'openobserve'],
    'ignore_exceptions' => false,
],

Testing the connection

You can verify connectivity and authentication with:

php artisan openobserve:test-connection

The command sends a test entry to the configured stream. Available options:

# Use a different logging channel configuration
php artisan openobserve:test-connection --config-key=logging.channels.openobserve

# Send the test entry to a specific stream
php artisan openobserve:test-connection --stream=my-stream

# Print request and response details
php artisan openobserve:test-connection --debug

Note: --debug prints request headers, including authentication credentials, and response details. Avoid capturing its output in shared or persistent logs.

Programmatic usage

The connection test is available as a console-independent runner, so it can also be used from jobs or other services:

use SameOldNick\OpenObserve\Support\OpenObserveConnectionTester;

$result = app(OpenObserveConnectionTester::class)->test(
    config: config('logging.channels.openobserve'),
);

if (! $result->successful) {
    throw new RuntimeException($result->message, previous: $result->exception);
}

The result exposes successful, message, stream, response, and exception.

Laravel Boost

This package ships Boost AI guidelines in resources/boost/guidelines/core.blade.php. They are installed automatically when an application runs php artisan boost:install.

Development

composer install
composer test
composer lint
composer format

Security

Please review SECURITY.md for the vulnerability reporting policy.

License

This package is open-sourced software licensed under the MIT license.