Improving observability with logging microformats in event-driven systems

Traditional approaches to observability often focus heavily on resource metrics – CPU utilisation, memory usage and other system-level indicators. While these metrics are easy to implement, they lack context. If you’re 99% CPU optimised, is that because you’re serving requests at 1,000 per second? In that case, the context would suggest that you’re doing pretty well. But if it was one request a second and you were pulling 99% CPU utilisation, that would be a different problem!

Resource metrics don’t tell you if your system is behaving correctly or as expected. They require additional context to be meaningful.

The problem with log-based metrics

Many teams attempt to derive metrics from logs – which we call ‘log metrics’. However, these approaches have significant drawbacks:

• Brittle implementation: Log lines can change with middleware updates or code refactoring, breaking the metrics derived from them
• No clear intent: Development contributors may not realise that their log lines are being used for metrics which can lead to partial or incorrect implementations
• Maintenance overhead: When a log format changes even slightly, metrics stop counting correctly, leading to busy work troubleshooting why dashboards don’t reconcile

Introducing microformats

Logging microformats were developed to signal intent between those who write log messages and those who use these messages to observe system behaviours – typically different people and likely different teams. When developers see a microformat, they understand that something important is happening downstream and changing it could impact results.

Microformats exist in addition to the full structured log message which includes other important attributes such as service name, environment and timestamp.

Example microformat structure

Here is an example of a format used to express what we call a ‘statement’. A statement contains attributes about a process or unit of work – which is emitted only once per process/unit of work:

Let’s break down the components:

• @type: In CURIE (Compact URI) format, indicates the intent of the microformat. Current types include:
  • Statement (attributes)
  • StatementCounter (metric + attributes)
  • StatementGauge (metric + attributes)
• @id: A compact URL (CURIE) that identifies the namespace context – product, service/bounded context and specific code context
• isInNamespace: A code or metric context that helps filter log events for aggregation and/or the creation of log metrics. Often based on Domain Driven Design (DDD) naming conventions
• with-...: Pattern used to represent high cardinality attributes (many possible values), good for filtering but risky for grouping
• by-...: Represents low cardinality attributes (limited number of possible values) which are suitable for filtering and/or grouping by

This distinction between high and low cardinality dimensions is important for performance reasons. When building dashboards, some widgets aren’t performant for high-cardinality dimensions, so having this signal helps determine how to use the dimension in visualisations.

Microformat metric examples

A metric log message includes additional properties – hasCount for the StatementCounter or hasValue for the StatementGauge type. Here are examples:

StatementCounter example

StatementGauge example

Benefits of microformats

1. Clear intent

Unlike regular logging where the purpose might be ambiguous, microformats establish a clear intent. This makes it much less likely that someone will accidentally break a metric by changing a log line.

2. Simplified metrics collection

Deriving metrics from structured logs can be easier than implementing a dedicated metrics system like StatsD which requires additional network configuration and infrastructure.

3. Consistent language

Microformats help converge on a language for dashboards that can be shared across technical and product teams. This builds a consistent vocabulary for all contributors in the organisation.

4. Implementation flexibility

Because the format is standardised, you can easily implement it in middleware or common libraries. This ensures all services consistently emit observable data without requiring individual developers to remember the correct format.

From microformats to wide events

The concept of microformats evolved from exploring ‘wide events’ – a powerful pattern for observability. A statement type is the equivalent of a wide event in a log format – which could be used with tools like DuckDB to aggregate for further analysis.

Wide events have two key concepts:

• One event per unit of work: A unit of work might be processing one request or one asynchronous event
• Collect everything: Wide events are ‘wide’ because they collect all relevant information about the unit of work

Wide events help solve the problem of ‘unknown unknowns’ in observability. When dashboards don’t reconcile and events are missing, wide events provide the additional context needed to identify correlations and troubleshoot issues.

For wide events implementation, we’re following the pattern described in “A Practitioner’s Guide to Wide Events”.

Practical implementation

Implementing microformats can be done through existing logging frameworks. For example, using the AWS Power Tools Logger, you can enrich logs with context that follows the microformat pattern.

The real power comes when this is automated through middleware, making it a cross-cutting concern that developers don’t need to handle manually. This improves testing and ensures consistent observability across your system.

While these examples use CloudWatch, the microformat approach is ‘impedance free’ if you want to change observability backends. You could easily adapt it to work with other observability platforms by adding appropriate tagging mechanisms.

Microformats provide a structured, intentional approach to logging that bridges the gap between technical and product metrics. By establishing clear patterns for observability, teams can build more reliable systems and reduce the cognitive load required to understand system behaviour.

The best compliment for a well-designed observability system? When other teams start using your dashboards to identify problems in their own systems. That’s when you know you’ve built something valuable.