Structured Events vs Text Logs

Text logs describe what the program did. Structured events record a stable fact about a workflow. Both are useful, but they optimize for different questions.

A text log is a good fit for local diagnosis: startup messages, unexpected branches, library output, and stack traces. Its free-form message preserves context for a person reading a narrow time range. A structured event is a better fit when the same question must be answered repeatedly across many requests: failure rate by route, cost by model, activation by source, or retries by queue.

The query difference

Suppose an application writes invoice sync failed for team_123 in 940ms. A search can find that sentence, but a chart must first extract the team, duration, and outcome. With structured fields, the query can operate directly:

SELECT
  error_type,
  COUNT(*) AS failures,
  approx_percentile_cont(duration_ms, 0.95) AS p95_duration_ms
FROM billing_syncs
WHERE status = 'failed'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY error_type
ORDER BY failures DESC;

The event contract makes field types and categories explicit. It also prevents small wording changes from breaking a saved query.

Use both without duplicating everything

Keep detailed, short-lived diagnostic logs where engineers investigate incidents. Emit a smaller set of durable structured events at workflow boundaries. Link the two with a request ID, trace ID, job ID, or other safe correlation value. Do not copy full stack traces or request bodies into every analytics event.

An event is not automatically better because it is JSON. A bag of changing keys and arbitrary strings is still difficult to analyze. The value comes from a deliberate contract: stable name, documented fields, controlled categories, and an owner who reviews changes.

A practical selection rule

Choose a structured event when you expect to aggregate, compare, alert, or build a dashboard from the data. Choose a text log when the main use is reading detailed context during a specific investigation. If you need both, emit one compact event and one diagnostic record that share a correlation identifier.

Read designing an event schema before adding a high-volume event, then use the structured logging guide to instrument and verify it.