Laravel Open Observe Laravel Package

Getting Started

Install the package via Composer:

composer require <vendor>/laravel-openobserve

The package ships a openobserve driver for Laravel 11/12/13, so the fastest first use case is to point Laravel's existing logging at OpenObserve instead of a local file. Open config/logging.php and add a channel using the new driver:

'channels' => [
    'openobserve' => [
        'driver'       => 'openobserve',
        'url'          => env('OPENOBSERVE_URL'),
        'organization' => env('OPENOBSERVE_ORG'),
        'stream'       => env('OPENOBSERVE_STREAM', 'laravel'),
        'username'     => env('OPENOBSERVE_USER'),
        'password'     => env('OPENOBSERVE_PASSWORD'),
        'level'        => env('LOG_LEVEL', 'debug'),
        'bubble'       => true,
        'verify'       => true,
    ],
],

Set LOG_CHANNEL=openobserve (or add it to the stack channel) and you're logging to OpenObserve.

Where to look first:

1. The openobserve channel config block — it's the entire surface area you'll interact with day-to-day.
2. The openobserve:test-connection Artisan command — run it immediately after configuring to validate credentials, URL, and stream before trusting your logs in an incident.
3. OpenObserveConnectionTester — the reusable class behind the command, useful when you outgrow config-file-driven checks.

php artisan openobserve:test-connection

First use case: ship application logs to OpenObserve for a single non-critical channel first (e.g. a console-style stack member), confirm delivery, then promote it to the default channel.

Implementation Patterns

Stack it rather than replace it. Keep the local single/daily channel and add OpenObserve to a stack. You get a durable local trail and remote search without losing logs if the endpoint is briefly unreachable:

'stack' => [
    'driver'   => 'stack',
    'channels' => ['daily', 'openobserve'],
],

Multi-environment setups. Because base URL, org, stream, auth, and level are all configurable per channel, the common pattern is one channel per environment or per tenant, each in config/logging.php but all reading from env(). Avoid hardcoding stream — deriving it from APP_ENV or the host lets staging and production data stay separated in one OpenObserve instance.

Custom driver for non-standard wiring. If you need runtime config (per-tenant credentials resolved from a database, or a channel built outside config/logging.php), register the custom driver with CreateOpenObserveLogger:

'channels' => [
    'openobserve_tenant' => [
        'driver' => 'custom',
        'via'    => CreateOpenObserveLogger::class,
        // config resolved at runtime
    ],
],

This is the extension point to reach for when tenancy, dynamic secrets, or feature-flagged logging is involved.

Background/batch contexts. The reusable OpenObserveConnectionTester can be injected into jobs and health checks — a solid pattern is a scheduled job that runs the connection test and alerts on failure, rather than discovering broken logging during an incident. For high-volume paths, prefer the batched delivery (_multi endpoint) so the driver packs multiple entries per request; single delivery (_json) is the safer default for low-volume or latency-sensitive channels.

Prefer standard Log:: facade usage in application code — don't call the driver directly. Contextual logging (Log::withContext([...])) is your friend for adding request IDs and user IDs that make the OpenObserve UI searchable.

Gotchas and Tips

Verify responses are on by default. Response verification is enabled unless opted out. It's the right default — you'll hear about misconfiguration via exceptions instead of silent loss — but it means a dead OpenObserve endpoint can surface as app-level log failures. In production, either keep bubble => true with a resilient stack, or intentionally set bubble => false so logging never takes down a request. Decide deliberately rather than inheriting the default.

bubble semantics. When bubbling is enabled, log exceptions propagate to the stack; with it off, failures are swallowed. In a stack channel, a bubbling failure can short-circuit delivery to sibling channels depending on order — put the critical local channel first if you're unsure.

Level filtering happens client-side. Setting level => 'debug' sends everything; a misconfigured level is the most common cause of "my logs aren't in OpenObserve." Verify both the Laravel channel level and any server-side stream ingest filtering.

Auth format matters. Basic auth (username/password) is only one of the supported options; if your org uses a different token scheme, check the package README for the exact key names — passing an API token into password without the right auth mode is a classic footgun. Don't commit credentials; use env vars.

Debugging connection issues. Start with the Artisan command in debug mode:

php artisan openobserve:test-connection --debug

The command supports passing a custom config, stream, and debug flag, so you can test a candidate channel before wiring it into config/logging.php — invaluable when you're iterating on org/stream names. Confirm the stream name actually exists (or is auto-creatable) in OpenObserve; a 404 on the stream is common and easy to mistake for an auth failure.

Endpoint selection (_json vs _multi). Single vs batched delivery is chosen by the package, but understanding it helps when debugging ordering and throughput. If you need strict one-entry-per-request behavior (e.g. for latency-sensitive apps), verify which endpoint you're hitting via the debug command.

Laravel Boost guidelines. The package ships AI guidelines via Laravel Boost — if you use Boost, run the guidelines sync so your AI assistant generates correct channel config instead of inventing keys:

php artisan boost:install

Testing tip. In tests, set LOG_CHANNEL to null or a testing channel rather than stubbing HTTP; the driver's verification will otherwise make real network calls and poison unit tests. Consider a testing channel that uses single with level => 'emergency' to suppress output.

Extension point. For anything beyond config-file usage, inject OpenObserveConnectionTester into a health-check controller or scheduled command; it gives you a single, package-maintained way to assert connectivity without duplicating HTTP logic.