How to structure a log

Summary

Logging arbitrary JSON objects often produces unstable messages and deeply nested data that complicate searching, aggregating, and debugging production incidents. Structured logging treats log output as real application data by establishing predictable, consistent schemas across services. Engineers should define stable event names using a domain.action pattern and capture dynamic dimensions with flattened, snake_case attributes formatted in dot notation. Attribute payloads must contain only primitive values or primitive arrays rather than arbitrary objects, utilizing low-cardinality result identifiers and explicit units for numeric measurements. Teams can enforce these structural conventions automatically with linting tools such as ESLint, while routing execution durations and timing measurements to tracing spans.

Context

Unstructured log messages with dynamic text and arbitrary nested JSON objects make logs difficult to query, filter, group, aggregate, and analyze during production incident debugging.

Approach / What changed

Adopt a standardized logging schema that utilizes stable domain.action event names, flattened dot-notation attribute keys, primitive values, explicit numeric units, and linting rules for automated enforcement.

Takeaways

• Event names should follow a stable domain.action pattern without dynamic strings in the message, placing dynamic variables into scoped attributes instead.
• Attributes must use flattened dot-notation keys with snake_case segments and restrict values to primitive types or arrays of primitives rather than raw nested objects.
• Numeric attributes should explicitly specify units within their key names, and execution duration measurements should be recorded in tracing spans rather than log attributes.

Related reading

• Sentry · May 7, 2026

  Fixing JavaScript observability, one library at a time

  JavaScript application performance monitoring tools rely on monkey-patching via require-in-the-middle and import-in-the-middle, which breaks with ECMAScript Modules, bundlers, and non-Node runtimes. To solve this, an initiative is replacing monkey-patching with Node's built-in diagnostics_channel TracingChannel API across server-side JavaScript libraries. Under this pattern, libraries publish structured events while monitoring vendors subscribe to them with zero overhead when unlistened. The author leveraged Claude Code workflows alongside direct maintainer communication to draft proposals, implement code, and manage reviews across 44 target packages. Ten libraries including mysql2, node-redis, ioredis, and unjs modules have merged support, while active efforts continue on shared OpenTelemetry mapper registries and remaining ecosystem packages.

  Abdelrahman Awad

• Sentry · Jun 5, 2026

  Errors, traces, logs, metrics: when to reach for what