minhyung / monolog-openobserve
Monolog handler for OpenObserve
Requires
- php: >=8.3
- ext-curl: *
- monolog/monolog: ^3.0
Requires (Dev)
- fakerphp/faker: ^1.24
- phpunit/phpunit: ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Monolog handler for OpenObserve
Requirements
- PHP 8.3 or later
- the
curlextension - 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.