Event Name Taxonomy

An on-call engineer wants to count payment failures across 60 services. One logs "payment failed for order 91823", another "Payment declined", a third "PAY_ERR 402". Counting them needs a regular expression per team, and the alert works until someone rewrites a message. Structured logging fixes the format; it does not fix the vocabulary. An event name taxonomy supplies the vocabulary: a constant name for each kind of thing that happens, chosen from a short list the organisation agrees.

A record then has an event field with a value like payment.charge.failed, plus typed fields for everything variable (order_id, amount, error.code). The name says what happened; the fields say to whom and how much.

Why it matters

Dashboards and alerts are queries, and a query needs a stable handle. Free-text messages change with every refactor and every translation, and the handle disappears silently: the dashboard reads zero and nothing reports an error. A constant name makes the handle explicit, so changing it becomes a visible, reviewable act. It also gives the data a shape: with domain.noun.verb, you can ask for everything in the payment domain, all failures across domains, or one step of a flow.

There is a cost control too. If an event name includes a variable (an order id), each value becomes a distinct name, the index cardinality grows with the data, and "count by event" returns a million rows.

Implementation patterns

• A naming rule: domain.noun.verb in lower case, past tense for outcomes (order.payment.failed, trip.driver.assigned). Short enough to type.
• A catalogue in code or a registry, owned by the platform team, with the event name, owner, required fields and a one-line description. Adding an event is a pull request; this is what makes the list short.
• A logging library API that takes the event name as a constant and refuses string concatenation, so developers cannot put a variable in it. A lint rule or a type (an enum) enforces this.
• Mandatory fields per event class, checked in CI by a schema test that emits each event with sample data.
• Align with an existing standard where one fits: Elastic Common Schema defines event.category, event.action and event.outcome fields, which can be adopted as the vocabulary rather than invented.
• A pipeline guard: an alert when the distinct event names from a single service exceed a bound, for example 500, which catches interpolation that slipped through.

Industry example

A delivery marketplace in the mould of Swiggy has hundreds of services and the same business events (order placed, restaurant accepted, rider assigned) are logged by many of them. An archetypal platform team publishes a catalogue of about 300 events and generates the logging helpers from it. The first benefit teams report is that an order's journey can be assembled with one filter on order_id and a sort on event time. This is described as an archetype, not as any company's documented practice.

Failure scenarios

• Interpolated names produce unbounded cardinality and break grouping.
• Too many events: a catalogue of 5,000 names is not a vocabulary, and teams invent their own next to it.
• Too coarse: one error event for everything defeats the purpose; the failure mode cannot be separated from the name.
• Renaming without a transition: the old name disappears and alerts read zero. Dual-emit for a release cycle or two and compare counts.
• Names that encode the service: checkout-service.error ties the vocabulary to the deployment topology, so a service split breaks every query.

Trade-offs

When not to use it

Debug logging that exists for a developer's investigation does not need a catalogue entry; it is not a contract with anything. A single service with one team and two dashboards gets most of the benefit from a naming convention in the README. The catalogue pays when more than one team's queries depend on another team's events.

Interview question

Q: Fifty dashboards break whenever a team rewrites its log messages. How do you stop that happening?

What a strong answer covers: constants for event names, variable data in typed fields; a catalogue with ownership; library enforcement and CI schema tests; migration by dual emit and count comparison; a cardinality guard on distinct names; and the limits of governance (keeping the list short enough that people use it).

Quick check

Quiz: What is wrong with "order " + id + " failed" as an event name? Every order becomes a separate event type, so grouping and alerts stop working.

Flashcard: What goes in the event name and what goes in fields? — Constant meaning in the name; variable data in typed fields.