Naming Things

Three teams. Three services. Three names for the same thing.
When the data arrives, it speaks three dialects.

orders — team a

telemetry emitted

statusCode = 200

with shared naming

http.response.status_code = 200

payment — team b

telemetry emitted

response_status = "200"

with shared naming

http.response.status_code = 200

inventory — team c

telemetry emitted

http_code = 200

with shared naming

http.response.status_code = 200

An incident: 500 errors are spiking across all three services.
You need to find every request that returned a 500. Try querying for them.

query builder

Team A statusCode = 500 match

Team B statusCode = 500 no match

Team C statusCode = 500 no match

Only 1 of 3 services found. Team B calls it response_status. Team C calls it http_code.

Team A response_status = "500" no match

Team B response_status = "500" match

Team C response_status = "500" no match

Query 2 of 3. Still missing Team C.

Team A http_code = 500 no match

Team B http_code = 500 no match

Team C http_code = 500 match

Three queries to answer one question. During an outage, this costs minutes you don't have.

3 queries for 1 answer. Every name is different. Every type is different.

Why is querying across services so hard?

one name — one query — all services

Team A http.response.status_code = 500 match

Team B http.response.status_code = 500 match

Team C http.response.status_code = 500 match

One query. All three services. Same name, same type, same meaning.

Team D joins. They need to record the HTTP request method.
Following the same naming pattern (dotted namespaces), what should they call it?

These shared naming rules are called semantic conventions.

When everyone speaks the same language, one query finds everything.