Lexicon
Semantic conventions
OpenTelemetry semantic conventions give telemetry a shared vocabulary. What they cover, how they keep attribute names consistent, and where migrations bite.
Definition
Semantic conventions are OpenTelemetry's standard vocabulary: the agreed names, types, and values for the attributes that describe telemetry. They cover what a service is called, how an HTTP request is annotated, how a database call is described, and hundreds of other details that would otherwise vary by team and by tool.
What it means in observability
Telemetry is only as useful as its metadata, and metadata is only as useful as its consistency. If one service records http.response.status\_code and another records statusCode, every query, dashboard, and alert has to know about both spellings forever. Semantic conventions solve this at the source. When every SDK, instrumentation library, and Collector uses the same names, telemetry from different languages and teams lines up automatically, and cross service questions get answered with one query instead of a union of special cases.
How it works in practice
The conventions are organized in three broad layers. Resource conventions describe the emitter: service name, version, deployment environment, host, cloud provider, and Kubernetes context. Signal conventions describe events, with attribute sets for HTTP, databases, messaging, RPC, and more, applied to spans, metrics, and log records. Stability levels mark each convention as stable or experimental, signaling how safe it is to build dashboards and alerts on top of it. Instrumentation libraries apply the conventions automatically, which is why most teams get well named telemetry without ever reading the specification.
Where it gets hard
The conventions evolve, and migrations are real work. The HTTP conventions were renamed on the road to stability, so estates instrumented at different times emit different attribute names for the same concept, and dashboards need to handle both spellings during the transition. Custom attributes are the other discipline problem. The specification cannot name everything, and without internal conventions for your own attributes, the consistency wins stop at the boundary of the standard.
Where Tsuga fits
Semantic conventions are Tsuga's internal data model, not a format to be translated on arrival. Attributes keep their standard names from ingestion through query, so anything written against the conventions, whether a dashboard, monitor, or runbook, works as documented and stays portable.
Related terms
- Kubernetes monitoringKubernetes monitoring is observability applied to Kubernetes clusters: the nodes, workloads, pods, and containers that run modern applications, plus the control plane that orchestrates them.
- MetricA metric is a named numeric measurement tracked over time, request counts, memory usage, response latency, carrying a type, a unit, and attributes that slice it into series.
- OpenTelemetryOpenTelemetry is an open source framework for generating, collecting, and exporting telemetry: the logs, metrics, and traces that describe how software behaves in production.
- OTLPOTLP is the OpenTelemetry Protocol, the standard wire format for sending logs, metrics, and traces between the components of an OpenTelemetry pipeline.
- SDKAn SDK, or software development kit, is a set of libraries and tools for building against a platform or standard.
- SpanA span is a single timed operation inside a trace: an HTTP request, a database call, a queue publish, or an internal step worth measuring.
- Vendor lock-inVendor lock-in is the accumulation of switching costs that makes leaving a platform impractical regardless of how the relationship is going: proprietary instrumentation, captive data, workflows that exist in only one tool, and contracts priced to reward staying.