Riemann Client Php Laravel Package

Technical Evaluation

What the package is. trademachines/riemann-client-php is a thin PHP client for Riemann, a Clojure-based event stream processor used to aggregate, filter, and route monitoring events (typically to Graphite, InfluxDB, PagerDuty, Slack). The client's job is narrow: encode Event/Message structs as Protobuf, open a TCP socket to Riemann's default port 5555, and write them. There is no Laravel service provider, config, facade, or queue integration implied by the package name.

Adoption signals are effectively zero. Score 0, no stars recorded, zero dependents. This is not a "small but healthy" package — it is an unvetted third-party artifact with no observable downstream usage to learn from. Treat it as code you would be adopting and owning, not code you would be consuming.

Architecture fit. Riemann is a push-based, Protobuf-over-TCP system. That maps poorly onto typical Laravel request lifecycles unless deliberately wrapped:

The package almost certainly predates Laravel's modern package conventions. Expect to write the service provider, config file, connection lifecycle, and reconnect logic yourself.

Integration feasibility. Two hard dependencies must be verified before any estimate is credible:

1. Protobuf runtime. Most PHP Riemann clients require google/protobuf (Composer) and/or the protobuf C extension, plus message classes generated by an older protoc. Protobuf's PHP API changed across 3.x → 4.x; generated classes from a 2017-era protoc frequently fail to load on modern runtimes.
2. PHP version floor. If the package targets PHP 7.x, it will install on Laravel 10/11 (PHP 8.1+) but is untested there — typed property, deprecation, and Stringable/ReturnTypeWillChange issues are likely in transitive code.

Technical risk register.

Key questions for the vendor/platform team.

• Is Riemann still an actively operated system here, or a legacy leftover? Who owns the Clojure stream config?
• Which Protobuf runtime is available in our base images (extension vs. Composer library), and at what version?
• What is the required delivery guarantee — best-effort telemetry, or audit-relevant business events? (Riemann TCP gives at-most-once with no ack; it is not a message queue.)
• Can we fork this into an internal namespace and own it, or is there a policy blocker?
• What is the fallback if Riemann is unavailable — drop, buffer to disk, or write to logs?

Verdict. Low strategic value, low technical readiness. Only pursue if Riemann is already a first-class part of the platform and the ask is "let PHP apps publish to it." Otherwise this is a solution looking for a problem, and StatsD/OpenTelemetry/Prometheus push would be a better-targeted investment.

Integration Approach

Stack fit. The package assumes a plain PHP process with a persistent socket. Laravel's execution models each stress that assumption differently:

• PHP-FPM / per-request: a new TCP connect + handshake per request is unacceptable. Buffer events in a singleton and flush on terminate(), or push to a queue.
• Queue workers (Horizon): long-lived processes, so a persistent connection is viable — but stale sockets after Riemann restarts must be detected and re-established.
• Octane/Swoole: connection reuse across requests raises concurrency-safety questions the package almost certainly does not answer. Assume it is not safe until proven otherwise.

Recommended shape. Do not let application code touch the vendor client directly. Introduce a one-method internal contract:

MetricsEmitter::emit(string $service, array $attributes, float $value = 1.0)

Back it with two implementations: a null/no-op (default, for local and CI) and a Riemann adapter that wraps the package. This contains the adoption risk to a single class, makes the vendor package swappable for StatsD or OTLP later, and lets you defer the Riemann decision without blocking feature work.

Migration path. There is no migration — nothing to migrate from in this package. The sequencing is greenfield:

1. Spike (1–2 days): install in a scratch Laravel 11 app on the target base image; prove Protobuf compatibility and a successful event into a local Riemann container. This is a go/no-go gate, and I'd put ~50% odds on it failing on Protobuf alone.
2. Fork and internalize: copy into app/Support/Riemann or an internal Composer package under our VCS. Pinning to a GitHub SHA of an unmaintained repo is not a durable dependency.
3. Adapter + no-op default: ship the contract and null implementation first; wire the Riemann adapter behind a config flag so nothing depends on it in lower environments.
4. One service, one metric: pilot on a single non-critical signal with a clear success criterion.
5. Expand: only after a month of stable operation.

Compatibility checklist before sequencing.

• Composer constraints vs. Laravel 10/11 and PHP 8.2/8.3.
• Protobuf extension present in base image; google/protobuf major version resolved.
• Riemann server version and whether it accepts plaintext TCP only (TLS is not standard — implies network-level trust).
• Egress rules from every pod/node to riemann:5555.

Sequencing note. Steps 1 and 2 are time-boxed and independently valuable — the spike result is a decision deliverable even if the answer is "no." Do not sequence application instrumentation work behind this; use the no-op emitter so product delivery is decoupled from the observability decision.

Operational Impact

Maintenance. The realistic steady state is that we maintain this, indefinitely. No upstream security patches, no PHP 8.4/9 readiness, no Protobuf compatibility work. Budget a small but permanent tax: a few days per year for runtime upgrades, plus a fork to track. Weigh that against the ~2–3 days to hand-roll an equivalent encoder, which removes the Protobuf dependency entirely.

Support. No vendor, no SLA, no issue triage. Internal support means whoever forked it. Escalation path for "metrics stopped flowing" terminates at our own on-call, not a maintainer. Document the fork owner explicitly in the service catalog.

Scaling characteristics.

• One TCP connection per PHP process; a 20-pod × 10-worker fleet yields ~200 sockets to a single Riemann instance. Riemann handles this, but it is a centralized, largely single-process system — horizontal scaling requires deliberate clustering work.
• No client-side batching in most naive clients means event volume tracks request volume 1:1. A traffic spike becomes a socket-write spike precisely when the system is already under stress. This is the classic observability-induced outage.
• Events are in-memory until flushed; a pod eviction or OOM silently loses buffered telemetry.

Failure modes to design for.

The non-negotiable design principle: emitting telemetry must never be able to fail a user request. Every failure mode above should degrade to a counter increment, not an exception.

Ramp-up. Two distinct skill gaps, neither small:

• Riemann/Clojure — the actual work of routing and alerting lives in riemann.config, a Clojure DSL. That is a platform-team skill, not an application-team one. If no one on staff writes Clojure today, the package is the easy part and the streams config is the real cost.
• Protobuf toolchain — regenerating message classes requires protoc and familiarity with the PHP runtime's quirks. Low frequency, high friction; a classic thing to get wrong during a PHP upgrade.

Bottom line for operations. This package adds a hard, unsupported dependency to the request path in exchange for a capability most estates already get from StatsD, OpenTelemetry, or Prometheus pushgateway with far better tooling and hiring pools. Recommended posture: do not adopt unless Riemann is already an owned, operated platform component — and even then, fork it behind an internal interface with a no-op default, so the blast radius is one class and the exit is a config change.