Skip to content

logging.md

Latest commit

 

History

History
98 lines (75 loc) · 6.07 KB

logging.md

File metadata and controls

98 lines (75 loc) · 6.07 KB
Raw

Logging

firefly/observability decides what a log line looks like, on top of Laravel's own logging.php (which still decides where lines go): every record on the configured channels carries the correlation id, the request id and — with tracing on — the trace and span ids; and firefly.logging.structured.format turns those channels' lines into JSON, ECS or Logstash documents without replacing a single handler.

Log correlation

Two Monolog processors are pushed onto each configured channel's real Monolog logger, the same way Laravel attaches its own ContextLogProcessor — from Application::boot() by LogChannelWiringPass (the guarantee: it runs whoever resolved log first, and it is where a bad firefly.logging.structured.* key refuses the boot) and, earlier, by ObservabilityWiringProvider's afterResolving('log') hook, so a line written before the wiring passes run already carries the ids; both go through one idempotent LogChannelWiring:

  • CorrelationIdLogProcessor — extra.correlation_id from Context firefly.correlation_id (CorrelationIdFilter), the id problem+json and the X-Correlation-Id header carry.
  • TraceContextLogProcessor — extra.trace_id / extra.span_id from the current span when the tracer has one (a line written inside a command handler or an event listener names that span), else from the request's ids TracingFilter published in Context; plus extra.correlation_id and extra.request_id (RequestContextFilter). Nothing is added for an id that is not known — a plain-text line with tracing off looks exactly as it did.

Structured logging

// config/firefly.php
'logging' => [
    'structured' => [
        'format' => env('FIREFLY_LOG_FORMAT', ''),   // '' | json | ecs | logstash
        // 'channels' => ['stack', 'stderr'],       // default: the logging.default channel
    ],
],

StructuredLogging sets the formatter on every handler of the listed channels that implements Monolog's FormattableHandlerInterface (and on a GroupHandler — the wrapper an ignore_exceptions stack puts its members in — which forwards it without declaring the interface) — a daily file stays a daily file, a stack keeps its members (a stack's Monolog logger holds its members' handler instances, so formatting the stack formats the members) — and pushes ServiceContextLogProcessor (extra.service_name = tracing.service-name or app.name, extra.service_environment = app.env). An unknown format, or a listed channel logging.channels does not define, is a ConfigurationException at boot — Laravel would otherwise hand the typo a throw-away emergency logger while the channel you actually write to silently kept plain text without a single id. Listing a member as well as its stack, in either order, changes nothing.

json — Monolog's JsonFormatter

{"message":"disk almost full","context":{"free":"3%"},"level":300,"level_name":"WARNING","channel":"stack","datetime":"2026-09-20T10:11:12.345678+00:00","extra":{"correlation_id":"4b6f…","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","request_id":"9c1e…","service_name":"ledger","service_environment":"production"}}

ecs — Elastic Common Schema 8 (EcsFormatter, first-party)

{"@timestamp":"2026-09-20T10:11:12.345678+00:00","log.level":"warning","message":"disk almost full","ecs.version":"8.11.0","log":{"logger":"stack"},"service":{"name":"ledger","environment":"production"},"trace":{"id":"4bf92f3577b34da6a3ce929d0e0e4736"},"span":{"id":"00f067aa0ba902b7"},"labels":{"correlation_id":"4b6f…","request_id":"9c1e…"},"context":{"free":"3%"}}

The four framework ids and the two service fields are lifted into their ECS homes; whatever else a caller or a processor added stays under context/extra (nested, so an application's message or error key can never collide with an ECS field). A Throwable under context.exception — Laravel's own convention — becomes error.{type,message,stack_trace}. Levels are lowercase, as ECS logging libraries write them.

logstash — Monolog's LogstashFormatter

{"@timestamp":"2026-09-20T10:11:12.345678+00:00","@version":1,"host":"web-1","message":"disk almost full","type":"ledger","channel":"stack","level":"WARNING","monolog_level":300,"fields":{"correlation_id":"4b6f…","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","request_id":"9c1e…","service_name":"ledger","service_environment":"production"},"context":{"free":"3%"}}

type is the service name; the framework's extra fields sit under fields, the call's context under context.

Runtime log levels

POST /actuator/loggers/{name} (see Actuator) still changes a channel's level at runtime; the format is a boot-time decision.

Configuration (firefly.logging.*, kebab-case)

Key Default Meaning
firefly.logging.structured.format '' '' | json | ecs | logstash.
firefly.logging.structured.channels [] Channel names to format (and to carry the id processors); empty means logging.default; a name not defined under logging.channels refuses to boot.
firefly.observability.tracing.service-name '' Shared with tracing: the service.name on every line; empty falls back to app.name.

Laravel comparison

Concern Plain Laravel LaraFly
Ids on a log line Context dumped into extra verbatim (firefly.correlation_id, …) normalised correlation_id, request_id, trace_id, span_id fields
JSON logs a formatter per channel in logging.php, hand-picked one key, applied to the channels' existing handlers
ECS elastic/ecs-logging first-party EcsFormatter, no extra dependency

Known-latent

  • gelf and logfmt are not offered; Monolog has a GelfMessageFormatter, and a channel can still set it through Laravel's own formatter key.
  • The processors are attached per channel, at resolution time. A channel created after boot through Log::build() gets neither the ids nor the formatter.