Riemann Logger Laravel Package

Technical Evaluation

Architecture fit. trademachines/riemann-logger is a convenience wrapper over trademachines/riemann-client-php, which means its architectural role is narrow: translate application log records into Riemann events and ship them over TCP (or UDP) to a Riemann server. In a Laravel context the correct seam is Monolog — Laravel's Log facade resolves to a Monolog Logger, and custom destinations are normally implemented as a Monolog HandlerInterface exposed through a named channel in config/logging.php. A TPM should confirm which of these the package actually provides: (a) a Monolog handler, (b) a Laravel service provider plus a riemann channel driver, or (c) a standalone PSR-3 logger that bypasses Laravel's Log facade entirely. Option (c) is the least attractive because it fragments the logging pipeline and complicates correlation IDs, context propagation, and per-channel level configuration. The broader architectural question is whether Riemann is a strategic fit at all: it is a Clojure/JVM event stream processor with a relatively small and shrinking ecosystem compared to OpenTelemetry, Prometheus, or a Loki/ELK stack. Adopting this package is effectively a bet on operating a Riemann server, not just on a Composer dependency.

Integration feasibility. Mechanically this is easy: composer require, verify Packagist availability and version constraints against the project's PHP and Laravel versions, publish config if a service provider exists, add a channel. The real feasibility gate is dependency resolution — the wrapper's composer.json must permit the Laravel, Monolog (2.x vs 3.x is a genuine breaking boundary), and riemann-client-php versions in use. The protobuf layer is the second gate: Riemann's wire protocol is Protocol Buffers, so the client will pull in either the google/protobuf runtime or a pure-PHP encoder; the former may require the protobuf C extension for acceptable performance. Feasibility is therefore high in a greenfield or non-critical logging path and low in a legacy app with pinned Monolog versions.

Technical risk. This is the dominant concern and it is severe on supply-chain grounds alone: zero stars, zero dependents, a score of 0, and a single-vendor origin indicate essentially no external validation. There is no signal of community review, no evidence of other production users, and unknown commit recency, license, and issue responsiveness. The transitive dependency (riemann-client-php) carries the same profile. Operationally, the design implies synchronous network I/O from the request or queue-worker path to a TCP endpoint, which converts a logging call into a failure domain — exactly the opposite of what a logging library should do. Combined with the requirement to run and configure a Riemann server (its config is Clojure code), the total risk surface is much larger than the package's one-line description suggests.

Key questions.

• What is the license, last commit date, and open-issue count on both this package and riemann-client-php?
• Does it ship a Laravel service provider with package auto-discovery, and does it expose a Monolog handler or a full PSR-3 logger?
• What are the PHP, Laravel, and Monolog version constraints in composer.json?
• Is transport TCP, UDP, or both, and is batching/buffering supported?
• What happens when Riemann is unreachable — exception, silent drop, or blocking retry? What are the default socket timeout and connect timeout?
• Is the protobuf encoder pure-PHP or does it require the protobuf extension?
• Does it preserve Monolog context/extra fields and PSR-3 placeholders into Riemann event attributes?
• Who owns this internally if the upstream vendor stops responding?

Integration Approach

Stack fit. The package fits a Laravel stack only if the organization has already committed to Riemann as its event/metrics backbone. If Riemann is not already in the platform, this package should not be the reason to adopt it. If Riemann is present, the integration should be scoped to a dedicated riemann log channel used for structured operational events (deployments, job failures, business counters) rather than as the primary application log sink — file/stderr logging should remain the source of truth for debugging.

Migration path. Because the package's API surface is unknown and its longevity is doubtful, the integration must be wrapped. Define an internal interface (e.g., EventEmitter::emit(string $service, array $attributes, float $ttl)) with a RiemannEventEmitter implementation that delegates to this package and a NullEventEmitter/LogEventEmitter fallback. Application code depends only on the interface. This makes the package replaceable in an afternoon — either by a hand-rolled Monolog handler against riemann-client-php directly or by an entirely different backend. The wrapper is roughly 100 lines and is the single highest-value risk mitigation available here; writing it directly against the client library, skipping the wrapper package, is a legitimate and arguably preferable alternative given the adoption signals.

Compatibility. Validate against the specific matrix in use: Laravel major version, Monolog 2 vs 3, PHP 8.1/8.2/8.3, and whether the runtime image has the protobuf extension and sockets support. Test both the success path and the "Riemann is down" path in a scratch application before any broader commitment. Confirm the package does not assume a global singleton or a specific container binding that conflicts with Octane or multi-tenant setups.

Sequencing.

1. Vendor due diligence: license, maintenance status, security advisory history, and a read of the full source (it is small enough to audit in under an hour).
2. Decide build-vs-adopt: if the package is a thin, unmaintained wrapper, forking it into a private repository or reimplementing the handler is likely cheaper than the governance overhead of depending on it.
3. Spike in a non-production environment against a real Riemann instance; measure per-event latency and behavior under Riemann outage.
4. Introduce the internal EventEmitter abstraction and wire the package behind it.
5. Shadow-mode in staging with production-like log volume; compare event delivery completeness against expectations.
6. Canary in production on a single low-risk service or queue worker, with an explicit kill switch (config flag to swap in the null emitter).

Operational Impact

Maintenance. Assume you will own this code. With zero dependents and no visible community, upstream fixes for new Laravel or Monolog majors are unlikely to arrive on a schedule you control. Plan to pin an exact version, fork to a private VCS if it becomes load-bearing, and budget a small but recurring maintenance allowance for compatibility bumps. The wrapper dependency (riemann-client-php) must be tracked as well — a break there is a break here.

Support. There is effectively no external support channel. Troubleshooting will be internal, and the debugging path runs through three layers (Laravel → Monolog → wrapper → client → protobuf → TCP → Riemann → Clojure config). Team members will need at least working familiarity with Riemann's event model (service, state, metric, tags, TTL) and its Clojure configuration to diagnose dropped or malformed events. Document the event schema and naming conventions early; inconsistent service names are the most common long-term operational debt in Riemann deployments.

Scaling. Synchronous per-record TCP emission does not scale with log volume. At even modest throughput this adds measurable latency to every logged request and multiplies connection churn. Mitigations: restrict the channel to low-frequency structured events, enable UDP if the client supports it (accepting lossiness), run a buffered/batching handler, or move emission to queued jobs so the web request path never blocks on the network. Also size the Riemann server itself — it is a JVM process with its own memory and index requirements, and it is a separate operational burden from the Laravel application.

Failure modes.

• Riemann unavailable: the critical question. If the handler throws, logging becomes an availability risk; if it silently drops, observability becomes a silent gap. Either way, an explicit, configurable policy is required, and the emitter must never be allowed to fail a user request.
• Socket timeouts / DNS resolution: blocking the request or queue worker; enforce sub-second connect and write timeouts.
• Serialization errors: unencodable context values (objects, closures, resources) in Monolog context can break protobuf encoding; sanitize context before emission.
• Buffer growth: if any internal buffering exists without a bound, prolonged Riemann downtime causes memory growth in long-lived workers (queue consumers, Octane).
• Silent schema drift: events land but with wrong service names or missing attributes, producing dashboards that quietly under-report.
• Dependency breakage on upgrade: a Laravel or Monolog bump resolves to an incompatible constraint and forces an emergency fork.

Ramp-up. Engineering ramp is moderate: the package API itself is trivial, but productive operation requires understanding Riemann's data model and Clojure-based configuration, which is uncommon skillset territory. Budget for a short internal enablement session covering event schema conventions, dashboard/alert wiring in Riemann, and the runbook for "events stopped arriving." Because the abstraction layer isolates the package, only one or two engineers need deep familiarity; the rest of the team interacts with the internal EventEmitter interface.

Recommendation. Do not adopt as a direct, hard dependency. Either (a) implement a small in-house Monolog handler against riemann-client-php behind an internal interface, or (b) if this package is used, fork it privately, wrap it, and treat it as owned code. The package's convenience value is real but small; its adoption and maintenance signals make it unsuitable as an unexamined dependency in a production Laravel system.