Monolog Ecs Formatter Laravel Package

Product Decisions This Supports

• Log schema standardization (build vs. buy): Decides whether we hand-roll an ECS-shaped Monolog formatter or adopt an existing one. The package is small in surface area (a formatter plus a Symfony bundle), MIT-licensed, and encodes ECS field naming conventions we would otherwise have to re-derive and maintain per service — a credible "buy/adopt, then vendor" candidate. v0.2.1 reinforces this: the maintainer is extending field coverage rather than churning APIs, so the "adopt, then vendor" bet still looks cheap to reverse.
• Observability roadmap sequencing: Informs whether log-schema work lands before or after an Elasticsearch/OpenSearch migration. The default copy mode — emitting ECS-aligned top-level fields while retaining legacy channel, level_name, level, and datetime — makes schema migration a non-breaking, reversible step, so it can be scheduled independently of dashboard rewrites.
• Mapping hygiene and cost control: Typed value objects for metrics, labels, text, tags, service, user, tracing, error, and now network are promoted to explicit top-level fields rather than dumped into a free-form context blob. That directly attacks mapping explosions and field-type conflicts, which are a recurring source of index bloat, reindexing work, and query breakage.
• Feature enablement: Unlocks cross-service queries and dashboards that depend on consistent service.*, user.*, trace.*, error.*, and now network.direction fields — a prerequisite for per-customer log filtering, trace-correlated debugging, and SLO/error-rate panels built on logs rather than APM. The new Network value object specifically enables traffic-direction analysis: distinguishing inbound request logs from outbound HTTP-client telemetry in a single index, which is the query shape behind dependency/fan-out dashboards and "which upstream is failing us" incident triage.
• ECS version alignment as a governance decision: v0.2.1 pins the NetworkDirection enum to ECS 8.11, which converts the previously open question ("how is ECS version drift handled?") into a concrete policy: the package version, not the runtime, is our ECS version pin. That is a clean, auditable contract, but it means adopting a new ECS field set requires a package bump — worth stating explicitly in the upgrade runbook.
• Use cases worth validating first: (1) multi-service Laravel/Symfony estates already shipping to Elasticsearch where each service invents its own context shape; (2) teams migrating dashboards incrementally and unwilling to freeze logging changes; (3) platform teams that want a typed logging contract enforced at the application layer instead of in the ingest pipeline; (4) teams that need to correlate inbound and outbound traffic per service without standing up distributed tracing first.
• Adoption risk as a decision input: Still 0 stars, 0 dependents, and no external validation. The v0.2.1 release is a second consecutive feature release with an external contributor, which is mild positive signal on maintenance cadence but not on production use. The PM decision remains not "adopt vs. reject" but "adopt with a vendor-and-pin posture" — budget a code review and a schema contract test, and treat upstream as a reference implementation rather than a supported dependency.

When to Consider This Package

Consider it when most of the following hold:

• We are on Monolog (Laravel or Symfony) and shipping logs into Elasticsearch/OpenSearch, or plan to within the next two quarters.
• We have more than one service and inconsistent log shapes are already costing us dashboard rework, mapping conflicts, or slow incident triage.
• We want ECS alignment incrementally, with existing dashboards continuing to work during the transition (copy mode is the deciding feature here).
• We need structured, queryable context — service identity, user, tracing/span IDs, error taxonomy, network direction — rather than stringly-typed context arrays.
• We want request/response telemetry correlation (inbound vs. outbound) without committing to full distributed tracing; the network.direction field gets us there with a log-schema change alone.
• We are comfortable vendoring or forking a small MIT package, pinning a version, and owning the tests around it.
• The team already has, or will add, a schema contract test (e.g., assert the emitted JSON matches expected ECS keys) so formatter changes cannot silently break dashboards.
• We accept that ECS version is pinned by the package (currently 8.11) and will treat upstream releases as the path to new ECS fields.

Look elsewhere when:

• We are not on Elastic/OpenSearch, or our pipeline is OpenTelemetry-first (Datadog, Honeycomb, Grafana/Loki with OTel semantic conventions). ECS alignment buys little there and OTel attribute conventions are the better target — note network.direction exists in both schemas, so the conceptual model transfers even if the field names do not.
• We need vendor support, an SLA, or a security-reviewable dependency with a track record — zero dependents and no adoption history make this unsuitable as a critical-path, unsupported dependency.
• Ingest-layer normalization is already handled by Fluent Bit, Vector, Logstash, or an Elastic ingest pipeline; duplicating schema logic in the app adds a second source of truth.
• We need full ECS coverage or log shipping/rotation concerns — coverage is growing feature by feature (network was just added), so gaps should be treated as roadmap unknowns rather than solved problems.
• The enum's closed set is a blocker: adding a new ECS direction value that isn't in the pinned 8.11 list requires an upstream change or a local patch, which is friction if we need to track ECS releases closely.
• Logging is an afterthought for the team and no one will own the formatter, the pinned version, or the upgrade path.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our services emit logs in inconsistent shapes, which forces us to maintain bespoke Elasticsearch mappings and rebuild dashboards whenever a service changes what it logs. This package standardizes log output on Elastic Common Schema — the industry-standard field naming — so logs from every service land in predictable, correctly-typed fields. Its key property is that it does both formats by default: new ECS fields are added while the existing fields our current dashboards rely on are preserved, so the migration is incremental and reversible rather than a flag-day rewrite. The latest release adds network direction (inbound/outbound), which lets us separate customer-facing request traffic from the outbound calls we make to dependencies in the same index — a capability we would otherwise need tracing infrastructure to get. It is MIT-licensed, small enough to vendor and own, and now pins its field set to a named ECS version (8.11), so schema changes are explicit and reviewable. The caveat is maturity: no adoption history, so we should adopt it as a pinned, internally-reviewed dependency, not a supported third-party platform — a low-cost bet with a clear exit (fork or replace with a few hundred lines of in-house code) if it stalls.

For engineering (the honest version):

• Drop-in Monolog formatter plus a Symfony bundle; Laravel usage is straightforward formatter wiring. Small, auditable surface — review it in an afternoon. v0.2.1 is additive only: no breaking changes, no deprecations, safe bump from 0.2.0.
• Typed value objects replace context dumping: metrics, labels, text, tags, service, user, tracing, error, and now Network map to top-level ECS fields, removing the field-type conflicts that plague our current indices. Network carries network.direction for outbound HTTP-client calls and inbound request logging.
• NetworkDirection is a closed-set enum pinned to ECS 8.11 (inbound, outbound, ingress, egress, internal, external, unknown). Two consequences: (a) we get compile-time safety and no free-text drift, and (b) new ECS values require a package bump or a local patch — decide now which, and record it in the runbook.
• Copy mode keeps channel, level_name, level, datetime at the top level, so no dashboard breaks on day one. Flip it off once dashboards are ported — that flag is our rollback.
• What we must still add ourselves: a schema contract test (golden JSON per log level, extended to cover network.direction on both inbound and outbound paths), a pinned tag or vendored copy, and an ECS-version-drift note that now reads "aligned to ECS 8.11 via package version" rather than "undefined."
• The release cadence (two feature releases, one external contributor) is encouraging but still not evidence of production use. Plan for upstream abandonment; the fork cost is low, and the typed-value-object modeling survives a later move to OTel-native logging even though the formatter itself becomes a thin adapter to replace.