Search by

minhyung / monolog-openobserve

lostland

Monolog handler for OpenObserve

Package info

github.com/overworks/monolog-openobserve

pkg:composer/minhyung/monolog-openobserve

Statistics

Installs: 2 569

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

0.5.0 2026-11-12 05:49 UTC

This package is auto-updated.

Last update: 2026-11-12 05:51:48 UTC


README

CI Latest Version PHP Version Total Downloads License

Monolog handler for OpenObserve

Requirements

  • PHP 8.3 or later
  • the curl extension
  • Monolog 3

Installation

composer require minhyung/monolog-openobserve

Usage

use Minhyung\Monolog\OpenObserveHandler;
use Monolog\Logger;

$handler = new OpenObserveHandler(
	host: 'http://localhost:5080',
	organizationId: 'default',
	streamName: 'monolog',
	username: 'admin@yourdomain.com',
	password: 'yourpassword',
);

$logger = new Logger('app');
$logger->pushHandler($handler);

$logger->info('Hello OpenObserve!', ['foo' => 'bar']);

Builder

The builder offers the same options as fluent methods:

$handler = OpenObserveHandler::builder('http://localhost:5080', 'default', 'monolog')
    ->withCredentials('admin@yourdomain.com', 'yourpassword')
    ->withLevel(\Monolog\Level::Info)
    ->withTimeout(5.0)
    ->build();

The builder is mutable: each with...() call returns the same builder, and each build() creates an independent handler. withCredentials() must be called before building, otherwise build() throws LogicException.

All optional constructor arguments have matching builder methods: withIgnoreFailure(), withLevel(), withBubble(), withConnectTimeout(), and withTimeout(). Defaults are identical to the constructor: failures throw, level is Debug, bubbling is enabled, and connection and request timeouts are 2 and 5 seconds.

Handling failures

By default the handler throws when OpenObserve cannot be reached or rejects the request, including on an authentication failure such as 401 or when an HTTP success response reports rejected records in status[].failed. Set ignoreFailure: true to swallow those errors so that a logging problem never breaks the application:

$handler = new OpenObserveHandler(
	host: 'http://localhost:5080',
	organizationId: 'default',
	streamName: 'monolog',
	username: 'admin@yourdomain.com',
	password: 'yourpassword',
	ignoreFailure: true,
);

Swallowed failures disappear silently. To act on them instead, pass a closure as ignoreFailure. It is called in place of throwing, with the exception and the log records that could not be sent:

use Monolog\LogRecord;

$handler = new OpenObserveHandler(
	host: 'http://localhost:5080',
	organizationId: 'default',
	streamName: 'monolog',
	username: 'admin@yourdomain.com',
	password: 'yourpassword',
	ignoreFailure: function (\Throwable $e, array $records): void {
		error_log('OpenObserve logging failed: ' . $e->getMessage());
	},
);

$records is always a list of LogRecord objects — one for a single log call, or every record of a failed batch — so it can be handed straight to another handler to keep the logs that OpenObserve did not receive:

use Monolog\Handler\StreamHandler;

$file = new StreamHandler('/var/log/app/openobserve-failed.log');

$handler = new OpenObserveHandler(
	host: 'http://localhost:5080',
	organizationId: 'default',
	streamName: 'monolog',
	username: 'admin@yourdomain.com',
	password: 'yourpassword',
	ignoreFailure: fn (\Throwable $e, array $records) => $file->handleBatch($records),
);

The closure must not log back to this handler, as that would recurse. An exception thrown from the closure propagates to the caller, so it can also rethrow selectively.

Timeouts

Because a stalled or unreachable OpenObserve would otherwise block the application on every log call, the request is bounded by two timeouts: 2 seconds to connect and 5 seconds for the whole request. Adjust them — or set the request timeout to 0 to disable it — via the connectTimeout and timeout arguments:

$handler = new OpenObserveHandler(
	host: 'http://localhost:5080',
	organizationId: 'default',
	streamName: 'monolog',
	username: 'admin@yourdomain.com',
	password: 'yourpassword',
	connectTimeout: 2.0,
	timeout: 5.0,
);

Each log or batch is sent once, without automatic retries, so retries do not multiply the configured timeout. A timeout does not guarantee that the server has not already ingested the records; retrying may create duplicates.

Upgrading

0.5 changes the constructor arguments and failure handling. See CHANGELOG.md for the steps from 0.4 and from 0.3.