Riemann Logger Laravel Package

Getting Started

trademachines/riemann-logger is a thin PSR-3-ish logger that turns log records into Riemann events via trademachines/riemann-client-php. Riemann is an event stream processor, not a log store — you're feeding it short-lived state/metric events that streams index, alert on, and forward. Treat this package as a metrics/alerting side-channel, not a replacement for your file/stdout log stack.

Minimal steps:

1. composer require trademachines/riemann-logger (this should pull in trademachines/riemann-client-php; if not, require it explicitly).
2. Confirm a Riemann endpoint is reachable — default is TCP/UDP 5555: nc -zv riemann.internal 5555.
3. Read src/ before writing a line of config. With 0 stars and 0 dependents there is effectively no documentation, no changelog, and no third-party usage to crib from. You need to know exactly:
   • the logger's constructor signature (almost certainly a Riemann\Client instance plus options),
   • whether it implements Psr\Log\LoggerInterface or only a subset,
   • how it maps PSR-3 levels onto Riemann state values,
   • which event fields it populates (service, host, description, tags, attributes) and which it lets you override.
4. First use case: make a single, low-risk call site emit an event and watch it land in Riemann before wiring it anywhere else.

use Riemann\Client;
use Riemann\Transport\TcpSocket;

$client = new Client(new TcpSocket('riemann.internal', 5555));
$logger = new \TradeMachines\RiemannLogger\Logger($client); // verify class name in src/

$logger->info('order.sync.completed', ['count' => 42]);

Then in riemann-client or the Riemann dashboard, confirm the event arrived and note its service/state/description shape — that shape is what every stream you write will match on.

Implementation Patterns

Wire it through Monolog, not directly. In a Laravel app the sane integration is as a log channel, not scattered new Logger(...) calls. Register a custom channel in a service provider:

Log::extend('riemann', function ($app, array $config) {
    $client = new Client(new TcpSocket($config['host'], $config['port']));
    return new \Monolog\Logger('riemann', [
        new RiemannHandler(new RiemannLogger($client)),
    ]);
});

Keep this channel off the default stack. Use it via Log::channel('riemann')->info(...) at deliberate call sites (job completion, queue depth, payment failures), or attach it alongside your normal channel only for error and above.

Map levels to states explicitly. Riemann streams branch on state (ok, warning, critical, unknown). PSR-3's eight levels don't map cleanly. Decide once — e.g. debug/info → ok, notice/warning → warning, error/critical/alert/emergency → critical — and either configure it or wrap the logger in a small adapter you control. Do not leave this to the package default without reading it.

Use tags and attributes for queryable dimensions. Riemann tags are indexed and cheap to filter on; attributes are arbitrary key/value. Push your trace/correlation ID, environment, and tenant into tags so a stream can group by them:

$logger->error('payment.failed', [
    'tags'  => ['env:' . app()->environment(), 'trace:' . $traceId],
    'attrs' => ['order_id' => $order->id],
]);

Split transports by purpose. TCP for anything you'd page on (delivery matters, and you accept the latency); UDP for high-volume debug/metric noise where dropped packets are fine. Construct two clients/logger instances if you need both.

Isolate failures. The logger should never be able to take down a request. Wrap the client in a decorator that catches transport exceptions, or configure a short connect timeout on the socket so a dead Riemann host costs you milliseconds, not seconds.

Test by faking the client. Because the logger takes a client, you can inject a mock and assert on the Riemann\Event objects it emits — level→state mapping, tag propagation, description templating. This is the cheapest way to lock down behaviour the package doesn't document.

Gotchas and Tips

• Logging must not throw. A synchronous TCP client to a monitoring host in the request path is a new failure domain. If the package doesn't swallow connection errors, your try/catch decorator is mandatory, not optional.
• Beware recursion. Don't route the package's own transport-level errors back through the same logger, and don't log Riemann failures to Riemann. Send those to your normal stack.
• PSR-3 context interpolation is not guaranteed. {placeholder} substitution and exception handling are common gaps in small loggers — verify against src/ rather than assuming.
• Event volume and cardinality. Every record becomes an event. Riemann indexes on service; if service includes a user ID, order ID, or full message string you'll blow up index cardinality and slow every stream. Keep service low-cardinality and push identifiers into tags/attributes/description.
• Time semantics. Riemann events carry a time (Unix seconds, float). Confirm the logger sets it; if it defaults to zero, streams that rely on :time will behave strangely.
• Riemann's 16KB message limit (TCP) — long exception messages or big context arrays can silently truncate or error at the transport layer. Truncate descriptions yourself.
• The package is unmaintained in practice (no stars, no dependents, no visible activity). Pin the version, vendor-review the source, and be prepared to fork. The surface area is small — if it's missing a method you need, subclassing or a ~50-line replacement directly on riemann-client-php is a reasonable escape hatch.
• Extension points to look for: a settable default service/host, a tags/attributes accessor, and whether the log call accepts an options array at all. If any are missing, add them in your own adapter rather than patching the vendor tree.