A convention is simply an agreement. Semantic conventions are the agreement about what to call things and what those names mean.

OpenTelemetry, often shortened to OTel, is an open-source project that gives software a standard way to produce telemetry. Telemetry is the stream of information a running program sends out about itself: what it is doing, how long things take, what went wrong. Developers and operations teams read this stream to understand and fix their systems.

Semantic conventions are a set of written rules inside the OpenTelemetry project. They say which names to use for pieces of telemetry, what each name means, what kind of value it holds, and what unit a number is measured in. The word semantic just means “about meaning”. The rules are not about how data is moved from place to place. They are about what the data says.

The three things a convention fixes

First, the name. If a web request has an HTTP method such as GET or POST, the convention says the field is called http.request.method. Not method, not verb, not HttpMethod. Second, the meaning and allowed values. The convention explains that this field holds the method of the request, written in capital letters, and lists the well-known values. Third, the shape and unit. If a measurement is a duration, the convention says it is a number of seconds, and tells you which kind of metric holds it.

Where the conventions live

The conventions are maintained by the OpenTelemetry community in a dedicated project called Semantic Conventions. They are written in a machine-readable form, and from that source the project produces the human-friendly documentation pages and the code constants that libraries use. You can read them in the Semantic Conventions section of the OpenTelemetry website. Each page covers one area, such as HTTP, databases, messaging or Kubernetes, and lists every name with its type, its description and an example.

What they are not

It helps to be clear about what semantic conventions are not. They are not a programming interface: you do not call them like a function. They are not a wire format: that job belongs to a separate piece called OTLP, the OpenTelemetry Protocol. And they are not enforced by the software. The tools will happily accept a field named banana. The conventions work only because people and libraries choose to follow them, much like spelling rules work because writers choose to follow the dictionary.

Every monitoring tool once spoke its own language. That made your data hard to combine, hard to move and hard to trust.

A short history of naming chaos

Before OpenTelemetry, there were many competing ways to collect traces and metrics. Two open-source projects, OpenTracing and OpenCensus, tried to standardize how code is instrumented. In 2019 they merged into OpenTelemetry, which is now a Cloud Native Computing Foundation project. The merge fixed the question of how to collect data. It did not automatically fix the question of what to call things.

Each vendor and each library author had their own habits. One Java library might label the HTTP method as http.method. A Go library might call it request_verb. A home-grown tool might send method. The backend, which is the system that stores and displays the data, sees three unrelated fields. A person who wants one graph of “all POST requests” must remember all three names and write three queries.

flowchart LR
subgraph Before["Before: every team invents names"]
A1["Service A sends http.method"] --> D1["Backend sees 3 unrelated fields"]
A2["Service B sends request_verb"] --> D1
A3["Service C sends method"] --> D1
end
subgraph After["After: shared conventions"]
B1["Service A sends http.request.method"] --> D2["Backend sees 1 field"]
B2["Service B sends http.request.method"] --> D2
B3["Service C sends http.request.method"] --> D2
end

Four kinds of pain

Big names agreeing on one dictionary

The agreement is not only theoretical. In 2023, Elastic donated its Elastic Common Schema, a long-used set of field names for logs and events, to the OpenTelemetry project, and the two efforts were merged into one body of conventions. Observability products from companies such as Datadog, Grafana Labs, Honeycomb, New Relic, Splunk, Dynatrace and Elastic can receive OpenTelemetry data, and many of them build screens that rely on the standard names. Jaeger, a tracing tool that began at Uber and is now a CNCF project, also works with OpenTelemetry data. When these tools share a vocabulary, your data becomes portable.

Before we read the conventions, we need five words: signal, trace, span, attribute and resource.

Signals: the kinds of data

A signal is one category of telemetry. OpenTelemetry has three main ones that are stable and widely used: traces, metrics and logs. A fourth, profiles, which describe where a program spends its processor time, is newer and still maturing. Each signal answers a different question, and the conventions cover all of them.

Traces and spans

A trace follows a single request, such as one click on the Buy button. The trace is made of spans. A span is one timed piece of work, like “handle the web request”, “ask the database a question” or “call the payment service”. Spans are arranged like a family tree: a parent span can have child spans. The span has a start time, an end time, a name, and a status that says whether it worked.

Every span also has a kind, which tells you its role in a conversation between two programs. There are five kinds. SERVER means the span is the receiving side of a call. CLIENT means it is the calling side. PRODUCER means it sent a message to a queue. CONSUMER means it received a message from a queue. INTERNAL means the work happened inside one program and did not cross a boundary. The conventions use the kind to decide which fields a span should carry.

Attributes: the labels

An attribute is a label stuck onto a piece of telemetry. It is a pair made of a key and a value, for example the key http.response.status_code with the value 200. Values can be text, true or false, whole numbers, decimal numbers, or lists of these. Attributes can be attached to spans, to metric data points, to log records and to resources. Almost everything in semantic conventions is, at its heart, a list of agreed attribute keys.

Resources: who is talking

A resource is a special bundle of attributes that describes the thing producing the telemetry, such as the service name, the server, the cloud region or the Kubernetes pod. Resource attributes are attached once and then apply to every signal that thing sends. The difference is simple. Span attributes describe what happened; resource attributes describe who it happened to.

flowchart LR
App["Your application code"] --> Lib["Instrumentation library"]
Lib --> SDK["OpenTelemetry SDK"]
SDK --> Exp["Exporter using OTLP"]
Exp --> Col["OpenTelemetry Collector"]
Col --> Back["Backend and dashboards"]
Conv["Semantic conventions: the shared dictionary"] -.-> Lib
Conv -.-> Col
Conv -.-> Back

Each entry in the conventions is like a small recipe card. Once you can read one card, you can read them all.

What one attribute entry says

Take the attribute http.response.status_code. Its entry tells you the key (the exact spelling), the type (a whole number), a plain-language description (the numeric status code the server sent back), one or more examples (200, 404, 503), and a requirement level that says how strongly the convention wants you to include it. Some entries also list a fixed set of allowed values, called an enumeration, such as the well-known HTTP methods.

Requirement levels

Not every attribute is equally important, so the conventions use four requirement levels. They work like the words on a form: required fields, fields required only in some cases, suggested fields and optional extras.

Opt-In is a quiet but important idea. Some details, such as the full text of a database query or the contents of HTTP headers, can reveal private data or add a lot of volume. The conventions describe them but keep them off by default, so you must choose to switch them on.

What a span entry says

A span convention goes beyond attributes. It also says how to name the span, which kind it should have, and how to set its status. For web servers, for instance, the convention says the span name is built from the HTTP method and the route, giving names like GET /users/{id}. Good span names are short and have a small number of possible values, so that you can group thousands of spans under the same name.

What a metric entry says

A metric convention lists the metric name, the instrument type (the kind of measuring device: a counter, an up-down counter, a histogram or a gauge), the unit, a description, and the attributes that may be attached to each data point. We look at these in detail in the metrics chapter.

Stability

Finally, each convention has a stability label that tells you how likely it is to change. The three working stages are Development, Release Candidate and Stable. We cover what they promise in a later chapter, because stability is what lets you build on the conventions with confidence.

Reading a convention page, line by line

The first visit to a convention page can feel crowded, so here is a calm way to read it. Start at the top, where a short paragraph says what the page covers and which signal it describes. Next, look for the stability note, because it tells you how much trust to place in everything below. Then scan the tables from left to right: key, type, description, examples and requirement level. Read the description column slowly, because it often hides the rule that matters, such as “this must be the route template, not the real path”.

Many pages also contain a column or note about cardinality or about sanitization. These notes are easy to skip and costly to ignore. A note that says “SHOULD have low cardinality” is a direct warning not to put raw identifiers in that field. A note about sanitization tells you that the library should replace sensitive parts of a value before it leaves your program.

Pay attention to attribute groups. A page for HTTP spans often says that it also includes the attributes of a network group or a URL group. This is the reuse we described earlier. You do not need to hunt through the other pages by hand, because the page lists the borrowed attributes in place. Finally, look at the deprecation notes. If a name is marked as replaced, the note names its successor, which saves you from guessing.

The first thing any tool needs to know about telemetry is where it came from. Resource conventions answer that.

Why resources come first

Imagine a pile of ten thousand spans arriving at your backend. Without knowing which service made each one, the pile is useless. Resource attributes are the return address. They let a backend group data by service, filter by environment, and tell the difference between the production checkout service and the test version running on someone’s laptop.

The most important resource attributes

How resource values get filled in

You rarely type these by hand. The SDK includes resource detectors, small helpers that look around the environment and fill in what they can find: the cloud metadata service gives the region, the operating system gives the host name, and the container runtime gives the container id. For the rest, two environment variables are the standard route. OTEL_SERVICE_NAME sets the service name, and OTEL_RESOURCE_ATTRIBUTES sets any other resource attributes as a list of key and value pairs.

In Kubernetes, the OpenTelemetry Collector has a helper called the k8s attributes processor. It looks up each pod that sends data and adds the pod, namespace and deployment names. This way application developers do not have to code any of it.

HTTP is the best-known convention, so it is the perfect way to see how names, kinds, statuses and attributes fit together.

Naming a span

A span name should answer “what kind of work is this?” in a few words, and it should have a small number of possible values. For a web server, the convention builds the name from the HTTP method and the route template: GET /users/{id}. Notice that the name holds the template, not the real path. If it held /users/48213, you would get a different name for every user, and no tool could group them. When the route is not known, the name falls back to just the method.

Choosing the span kind

For an HTTP call, the program that receives the request records a span of kind SERVER, and the program that sends it records a span of kind CLIENT. The two spans are linked in the same trace, and together they show how long the request took on the wire versus how long the server worked. Without the kind, a tool could not draw this picture correctly.

flowchart TD
S1["SERVER span: GET /checkout"] --> S2["INTERNAL span: validate cart"]
S1 --> S3["CLIENT span: POST to payment service"]
S3 --> S4["SERVER span in payment service: POST /charge"]
S4 --> S5["CLIENT span: query on payments database"]
S1 --> S6["PRODUCER span: publish order created message"]

The key HTTP attributes

Whether each attribute is Required, Conditionally Required or Recommended differs between client spans and server spans, so check the convention page for the side you are instrumenting.

Setting the status the right way

A span status is Unset, Ok or Error. The HTTP convention has a careful rule that surprises many people. On the server side, only status codes in the 500 range make the span an Error, because a 404 means the server did its job correctly by saying “not found”. On the client side, both 400-range and 500-range codes make the span an Error, because from the caller’s view the request did not get what it wanted. In both cases you should also set error.type to explain why.

How a server span is filled in, step by step

Database and messaging spans in practice

HTTP is only the beginning. A database call is recorded as a span of kind CLIENT, because your program is the caller and the database is the receiver. The convention builds the span name from the operation and the target, giving names such as SELECT orders. As with web routes, the name uses the general shape, not the specific values, so thousands of different order lookups all share one name. The attributes then say which database system is in use, which collection or table was touched, and, only if you allow it, the query text with its values removed.

Messaging brings two extra span kinds into play. When a program puts a message on a queue, it records a PRODUCER span. When another program picks that message up, it records a CONSUMER span. The span name follows the pattern of the operation followed by the queue or topic name, for example publish orders. The attributes name the messaging system, the destination and the operation type, such as publish, receive or process.

A subtle point is that the producer and the consumer rarely run at the same moment. The message may sit in a queue for seconds or hours. For this reason, the producer and consumer spans are often connected with a link rather than a strict parent and child relationship. A link is a pointer that says “this work is related to that other span” without claiming that one ran inside the other. The conventions explain when to use links and when to use a parent, so check the messaging page before you design a queue-based flow.

A metric is a number tracked over time. The conventions make sure that a number with the same name always means the same thing and uses the same unit.

The four measuring devices

OpenTelemetry metrics are recorded through instruments, and the convention for each metric tells you which one to use. A counter only goes up, like the number of requests served. An up-down counter goes up and down, like the number of requests being handled right now. A histogram records many measurements and sorts them into buckets, which lets you later work out averages and percentiles such as the 95th percentile. A gauge records a value at a moment, like the current temperature.

Common metrics

Stability varies across this list. The HTTP metrics are among the first to reach Stable, while others are still maturing, so confirm the current stage on the convention page before you rely on a name in an alert.

Rules for metric names and units

The conventions set several habits worth copying. Names use dots to separate namespaces, such as http.server.request.duration. The unit is not put in the name; it is stored separately in a field, so you never see a name like latency_ms. Units follow the Unified Code for Units of Measure, called UCUM. Seconds are written s, bytes By, and a plain ratio is written 1. For things you simply count, the unit is a word in curly brackets such as {request} or {connection}, which names what is being counted.

There is also a helpful split between usage and utilization. Usage is an absolute amount, like bytes of memory used. Utilization is a fraction between zero and one, like the share of memory used. Mixing them up is a classic way to build a chart that looks fine and means nothing.

Why low cardinality matters

Cardinality means the number of different values something can take. Every unique mix of attribute values on a metric becomes its own time series that the backend must store. Suppose a web service has 50 routes, 5 methods and 10 status codes. That is at most 50 times 5 times 10, or 2,500 series for one metric, which is manageable. Now add a user id attribute with one million different users. The count explodes to billions, and the monitoring bill and query speed suffer terribly.

That is why the metric conventions only allow attributes with a small, bounded set of values. The route template is allowed; the raw path is not. The status code is allowed; the user id is not. Detailed, high-cardinality facts belong on spans and logs, where each item is stored once.

Logs are the oldest form of telemetry. Conventions turn them from loose sentences into records that tools can sort, search and connect to traces.

The shape of a log record

A log record in OpenTelemetry has a fixed set of fields. It has a timestamp for when the event happened, a severity that says how serious it is, a body that holds the message, a set of attributes for extra labels, and the resource that says who wrote it. Most importantly, it can carry a trace id and a span id. When these two are filled in, you can click from a log line straight to the exact trace and span that produced it.

Severity levels

Different logging libraries use different words: “warning”, “warn”, “critical”, “fatal”. To make them comparable, OpenTelemetry defines a severity number from 1 to 24, split into six bands.

Exceptions

When code throws an error, the convention gives three standard attributes. exception.type holds the kind of error, exception.message holds its message, and exception.stacktrace holds the trail of function calls that led to it. Because these names are shared, a backend can group every “connection refused” error across all your languages into one view, even though a Java service and a Python service describe it in different native formats.

Events

An event is a named occurrence, such as “order placed” or “user logged in”. Events carry a name and attributes, and the conventions define well-known event names for some areas. Recording an event as a log record keeps it independent from any one span, while older guidance often attached events directly to spans. The project has been moving some event-style data toward log records, so check the current guidance for the area you use before you decide.

Structured beats free text

The biggest practical lesson is to put facts into attributes rather than burying them in sentences. A line such as “payment of 42 dollars failed for order 9912” is easy for a person but hard for a machine. A record with a short message and separate attributes for the order and the failure reason can be counted, filtered and graphed, and it respects the naming rules in the next chapters.

The conventions are not one big list. They are split into areas, called domains, one for each kind of technology your system touches.

Each domain groups the names for one technology: spans, metrics, logs and resources together. When you instrument a database, you open the database page and find everything you need in one place. Here is a tour of the domains you are most likely to meet.

Shared building blocks

Notice how the domains reuse each other. The HTTP convention does not invent its own way to name a server address; it borrows server.address and server.port from the shared network group. A database call over the network borrows the same pair. This reuse is deliberate. It means one query such as “show me everything talking to host X” works across HTTP, databases and messaging at once.

Domains also differ in maturity

Some domains, such as HTTP, have reached Stable. Others, such as databases, messaging and generative AI, have been moving through the stages and may include names that are still Development. The sensible habit is to check the stability label of each name you use, as we discuss in chapter 11.

Choosing which domain page to read

New users often ask which page to open first. A simple method works well. Start with the resource pages, because every service needs them. Next, open the page for the protocol that carries your traffic, such as HTTP or gRPC. Then open the page for each technology you call, such as your database or message broker. Finally, open the page for the platform you run on, such as a cloud provider, a serverless service or Kubernetes. Four groups, read in that order, cover almost every service.

Real systems usually mix several domains inside one request. A serverless function behind a web gateway uses the HTTP page, the function page and the cloud page together. A chat feature built on a language model uses the HTTP page for the call, and the generative AI page for the model name and the token counts. You do not have to pick only one. The shared building blocks make it natural to combine them, because the same attribute never appears with two different meanings.

The standard names cover a lot, but your business has facts nobody else has. The naming rules show how to add your own without causing a clash.

The grammar of a name

Attribute names follow a simple grammar. They are written in lowercase. Dots separate namespaces, which are groups that go from general to specific, like http then response then status_code. Inside one segment, if you need more than one word, you join them with an underscore, as in status_code. The name should describe what the value is, not how it is stored or how it might be used.

Adding your own attributes safely

When the standard list has no name for your fact, you create a custom attribute. The rule is to put it in a namespace you own. A company usually uses its reversed web address or its company name as the first segment, for example com.shopfast. or shopfast.. This guarantees no future standard name will collide with yours.

Two things are off limits. First, do not add new names inside a standard namespace, such as inventing http.cache_hit. If the OpenTelemetry project adds a similarly named attribute later with a different meaning, your data and the standard data will be mixed. Second, the otel. namespace is reserved for OpenTelemetry’s own use.

A short process for extending

Rules for values

Values have rules too. Fixed lists, such as the names of cloud providers, are written in lowercase and use the exact words from the convention. When an instrumentation meets a value outside a known list, it records a catch-all value, like _OTHER for an unknown HTTP method, instead of copying the raw text. This keeps the number of distinct values small, which protects you from the cardinality problem we met in chapter 7.

Lists and template keys

Attribute values are not always a single item. An attribute can hold a list, such as a list of text values. HTTP headers are a good example. Because a header may appear several times in one request, the convention stores its values as a list of text. The key itself follows a template, where one part is a placeholder that you fill in with the header name in lowercase. In this way one rule covers every possible header, and since headers are Opt-In, you list only the ones you choose to capture.

When you design your own attributes, borrow the same habits. Use a list when the thing really is a list, and avoid packing several values into one text with commas, because tools cannot search inside such a text reliably. Use a number when the value is a number, so that you can sum, average and compare it. Use true or false for a yes or no fact. Choosing the right type from the start saves a great deal of cleanup later.

A dictionary that changes without warning is a dangerous dictionary. This chapter explains how conventions evolve while keeping your dashboards alive.

The stability stages

Development used to be called Experimental, and you may still see the older word in documents. Names that are no longer recommended are marked Deprecated and point to their replacement.

A real migration: the HTTP renames

The HTTP convention is the best example of a name change. While it was maturing, its names were cleaned up and made consistent with the rest of the conventions. Before it became Stable in late 2023, many libraries were already emitting the old names.

If a library simply switched to the new names overnight, every dashboard and alert built on the old ones would go blank. To avoid this, instrumentation libraries offer an opt-in switch through the environment variable OTEL_SEMCONV_STABILITY_OPT_IN. Setting it to http makes the library emit only the new names. Setting it to http/dup makes it emit both old and new at the same time. Similar values exist for other areas, such as databases. If you set nothing, libraries that have not fully moved keep emitting the old names.

flowchart LR
P1["Phase 1: old names only"] --> P2["Phase 2: emit old and new together with http/dup"]
P2 --> P3["Phase 3: move dashboards and alerts to new names"]
P3 --> P4["Phase 4: emit new names only with http"]

Versions and schema URLs

The conventions are released in numbered versions, so that you can say “we follow version 1.x”. Each version is a snapshot of every name. Telemetry can announce which snapshot it follows through a schema URL, a web address stored on the resource or on the instrumentation scope. The address points to a schema file that lists the changes between versions, such as “attribute A was renamed to B”.

A tool that understands schemas can read the schema URL and translate data from one version to another. A backend or Collector can then turn older names into newer ones automatically, so the dashboards only need to understand one version. The Collector community has components aimed at schema translation, though how much you can rely on them depends on the feature and version, so test before you promise it to your team.

A migration plan you can follow

The conventions are just a document, so how do they end up shaping real data? Follow one name on its whole journey.

Step 1: the source of truth

The conventions begin as structured, machine-readable files kept in the project repository. Each file describes groups of attributes, spans and metrics with their types, requirement levels and stability. From these files, the project builds two things automatically: the documentation pages that people read, and ready-made code constants that libraries import. Because the same source feeds both, the docs and the code cannot drift apart.

OpenTelemetry also provides a tool called Weaver. It reads a collection of conventions, called a registry, and can check it, generate documentation and generate code from it. Companies can use it with their own custom registry layered on top of the standard one, so that internal names get the same documentation and checking as official ones.

Step 2: instrumentation sets the names

An instrumentation library is a package that watches a framework, such as a web server or a database driver, and creates telemetry for it automatically. Using the generated constants, the library writes the correct attribute names every time. This is why you rarely mistype a convention: you never type it, the library does.

Step 3: the SDK processes the data

The OpenTelemetry SDK is the engine inside your program that collects the telemetry. It does not check names against the conventions; it treats them as plain keys. But it does influence convention-related behavior. A sampler, which decides whether a trace is kept or thrown away, only sees the attributes that were present when the span began, so important sampling facts must be set at the start. The SDK also enforces limits, such as a default maximum of 128 attributes per span, set through variables like OTEL_ATTRIBUTE_COUNT_LIMIT.

Step 4: the Collector shapes the stream

The OpenTelemetry Collector is a separate program that receives data, processes it and forwards it. It is the best place to fix naming problems in one place. It can run next to each application as an agent, or as a central gateway that many services send to. Its processors can add missing resource attributes, rename old names to new ones, drop sensitive attributes and batch data for efficient delivery.

flowchart TD
Reg["Convention source files in YAML"] --> Docs["Documentation pages"]
Reg --> Const["Generated code constants"]
Const --> Inst["Instrumentation library"]
Inst --> Data["Spans, metrics and logs with standard names"]
Data --> SDK["SDK: samplers, processors, limits"]
SDK --> OTLP["OTLP export"]
OTLP --> Coll["Collector: detect resources, rename, filter, batch"]
Coll --> Store["Backend storage and dashboards"]

Step 5: the backend reads the names

At the end of the line, the backend stores the data and builds screens from it. Because it expects service.name, it can draw a map of services. Because it expects http.response.status_code, it can compute error rates. Features like automatic service maps and ready-made dashboards depend on the names being where they are supposed to be.

Context propagation: how services stay in one story

Conventions name the data, but something else carries a trace from one service to the next. That something is context propagation. When a service calls another service, it adds a small piece of information to the outgoing request. For HTTP, the widely used standard is the W3C Trace Context, which places the trace id and the parent span id in a header named traceparent. The receiving service reads the header and continues the same trace, so the spans from both services join into a single tree.

Propagation and conventions work as a pair. Propagation makes sure that the spans belong to the same trace. Conventions make sure that each span describes itself in the agreed words. If propagation breaks, you see separate, disconnected traces. If conventions are ignored, you see a connected trace in which each part uses a different language. You need both for the full picture, and when you debug a broken trace it helps to check which of the two has failed.

A related idea is baggage, a set of key and value pairs that travels along with the request through every service. Baggage is useful for carrying a few business facts, like a customer tier, to every hop. It is not stored automatically on spans, and everything in it travels over the network, so keep it small and never place secrets in it.

Standard names make data easy to use. They also make it easy to leak or overspend. Here is how to stay safe and affordable.

Protecting private data

Telemetry often travels to third-party systems and sits in storage for weeks, so it must not carry secrets. The conventions already warn about the risky spots. A full web address, url.full, can contain a username and password, or a secret token in the query string. Instrumentation is expected to remove credentials from addresses and to hide the values of well-known sensitive query parameters. Database query text can contain customer data, so conventions call for parameter values to be replaced with placeholders by default. HTTP headers are Opt-In for the same reason.

The Collector is a good last line of defense. Its attribute and transform processors can delete or rewrite attributes for every service in one place, so a single rule protects the entire company even if one team forgets.

Watching the quality of your telemetry

Treat telemetry as a product with its own health checks. Useful checks include: how many services have a real service.name rather than an “unknown_service” value, how many spans lack a status code on HTTP calls, and which attribute keys appear that are not in your registry. Tools such as Weaver can compare live telemetry against a registry and report differences, and the Collector reports its own metrics about data it receives, drops and fails to send. Review these on a dashboard just like application health.

Controlling cost

Most observability bills grow with volume and cardinality. The conventions help in four ways. Opt-In attributes are off by default, so you choose what to pay for. The low-cardinality rules for span names and metric attributes keep time series counts predictable. Standard names let you write one drop or filter rule that applies to all services. And the catch-all values like _OTHER prevent odd inputs from creating endless new values.

A governance checklist for teams

As the number of services grows, a little governance keeps the data healthy. It does not need to be heavy. A short checklist, reviewed every quarter, is often enough.

• Ownership: name one team that owns the company registry of custom attributes and answers questions about naming.
• Review: require a quick review for any new custom attribute, covering the name, type, unit and cardinality.
• Privacy: keep a list of attributes that may hold personal or secret data, with the rule for each: drop, hash or mask.
• Versions: record the convention version used by each service and plan upgrades together.
• Cost: review the top attributes by number of unique values every month, and fix the ones that grow without bound.
• Training: give each new engineer a one-page guide to the naming grammar and the standard dashboards.

It also helps to keep a small set of golden dashboards, such as request rate, error rate and duration by service, built only from standard names. If a service does not appear correctly on the golden dashboards, that is an immediate sign that its telemetry does not follow the conventions, and the owning team can fix it before an incident exposes the gap.

Standardization is powerful, but it is not free. An honest look at both sides helps you decide how strictly to follow the rules.

Trade-offs you will face

Teams that succeed with conventions tend to repeat a few good habits, and teams that struggle tend to repeat a few mistakes.

Patterns that work

Anti-patterns to avoid

Best practices at a glance

Common mistakes

Let us put everything together with a made-up shop, then look at how real organizations lean on the same ideas.

ShopFast: an illustrative story

ShopFast is an imaginary online store. Its shopper opens the site, the request enters an API gateway, and the checkout service handles it. Checkout calls a payment service, writes to an orders database and drops a message on a queue, from which a shipping service picks it up. Every service sends telemetry to a Collector, which forwards it to an observability backend.

flowchart LR
User["Shopper browser"] --> GW["API gateway"]
GW --> Chk["Checkout service"]
Chk --> Pay["Payment service"]
Chk --> DB["Orders database"]
Chk --> Q["Message queue"]
Q --> Ship["Shipping service"]
Chk -. telemetry .-> OC["OpenTelemetry Collector"]
Pay -. telemetry .-> OC
Ship -. telemetry .-> OC
OC --> BE["Observability backend"]

At peak, imagine ShopFast handles 12,000 requests per second across 40 services. One evening, the error alert for checkout fires. Because every service follows the conventions, the on-call engineer can follow a short, predictable path.

The whole investigation took minutes because the names lined up. Without conventions, each step would have needed someone to remember a team-specific spelling.

How real organizations use the same ideas

A second illustrative story: tidying up a growing company

Consider another imaginary firm, BookNest, with about 150 services written in four languages by a dozen teams. Over five years, each team chose its own names. The company runs two monitoring tools after an acquisition, and nobody can build a company-wide view of errors. Leadership decides to adopt OpenTelemetry and its semantic conventions.

The result is not magic, but it is measurable. The company builds one error dashboard instead of dozens, can compare the two monitoring tools on the same data, and cuts the time to find the owner of a failing service, because every span now carries a real service name and a version. This shape of plan, with a minimum standard, a central fix and a gradual move, is the one most large organizations follow.

Short answers to the questions people ask most often.

If you remember only a handful of ideas from this guide, make it these.