A trace can be technically complete and still fail the people who need it. The spans arrive, the backend stores them, and the service map renders. Yet the map contains names such as unknown_service, api, and backend. During an incident, nobody knows which team owns what, whether two names describe the same service, or whether one name hides several different systems.
This is not a cosmetic naming problem. Service identity affects how engineers search telemetry, build dashboards, assign alerts, compare releases, and understand dependencies. If service identity is inconsistent, every later layer of observability inherits that confusion.
Service identity is operational data
OpenTelemetry defines a service as a logical component that produces telemetry. Its service resource conventions use service.namespace, service.name, service.instance.id, and service.version to describe that component and its running instances.
The distinction matters:
service.namespacegroups related services.service.nameidentifies the logical service.service.instance.iddistinguishes one running instance from another.service.versionidentifies the deployed version.deployment.environment.nameidentifies environments such as production, staging, test, or development.
The OpenTelemetry specification says that service.name must be the same across horizontally scaled instances. It also says that the combination of namespace, name, and instance identifier must uniquely identify an instance. These rules provide a stable foundation for traces, metrics, logs, and service maps. See the official OpenTelemetry service semantic conventions.
Why vague names become expensive
When a team leaves service.name unset, an OpenTelemetry SDK must fall back to a value beginning with unknown_service. That is safer than inventing an identity, but it is a warning that operational context is missing.
Generic names create several practical failures:
- An alert points to “backend,” but several teams run a backend.
- A dashboard combines production and staging data because the environment attribute is missing.
- A deployment comparison is impossible because
service.versionwas never recorded. - A service map splits one service into several nodes because different teams used different spellings.
- Logs and traces cannot be joined reliably because they use different service identities.
These problems are especially painful for lean teams. When the same engineers support several services, they need telemetry to reduce coordination work, not create more of it. A clear identity model makes incident response faster without requiring another observability product.
Identity also connects the rest of the telemetry architecture. It helps teams isolate pressure in an OpenTelemetry Collector pipeline, understand producers and consumers joined by Span Links, and assign metric growth to the correct owner when enforcing a cardinality budget.
Use a small identity contract
A service identity standard should be short enough that teams can follow it. Start with a required contract for every production workload.
1. Give every logical service one durable name
Choose a name that survives scaling, restarts, and routine deployments. Do not include pod names, host names, version numbers, or environments in service.name. Those facts belong in other attributes.
A useful name describes the capability or component, for example payments-api, identity-worker, or merchant-portal. Avoid names such as app, api, and server unless they are genuinely unique within the namespace.
2. Use namespaces deliberately
service.namespace can separate systems, products, or ownership domains. A payments platform might use payments as the namespace, with services named authorization, settlement, and reconciliation.
Do not treat the namespace as a place to copy the environment. OpenTelemetry states that deployment.environment.name does not change service uniqueness. Production and staging versions of the same logical service remain the same service identity, observed in different environments. The official deployment attribute registry documents this distinction.
3. Record the deployed version
service.version can hold a semantic version, build identifier, or commit hash. The important requirement is consistency. When an incident begins soon after a deployment, version data helps teams compare affected and unaffected instances.
4. Keep instance identity unique
service.instance.id represents one running instance. A Kubernetes pod UID, cloud instance identifier, or generated UUID may work, depending on the runtime. Do not reuse one static identifier across replicas. Doing so makes separate instances appear to be one source.
Configure identity close to deployment
Application code is not always the best place to define deployment-specific resource attributes. Environment variables, deployment manifests, Helm values, or platform templates can make identity consistent across languages.
OpenTelemetry supports OTEL_SERVICE_NAME as a standard environment variable for the service name. Other resource attributes can be supplied through OTEL_RESOURCE_ATTRIBUTES. For example:
OTEL_SERVICE_NAME=authorization
OTEL_RESOURCE_ATTRIBUTES=service.namespace=payments,service.version=2026.09.13,deployment.environment.name=production
Treat this as an example, not a universal deployment recipe. Each language SDK and distribution should be checked for its supported configuration and precedence rules. The OpenTelemetry Resource SDK specification explains how resources are created and merged.
Enforce the contract before production
Documentation alone will drift. Add lightweight checks at three points.
In delivery pipelines
Reject production manifests that omit the required service name, namespace, version, or environment. Validate names against a simple pattern and block placeholders such as unknown_service, test, and default.
At the Collector
Use Collector processors carefully to add attributes that are truly known at the collection layer. Avoid rewriting a service name based on guesswork. A Collector may enrich telemetry with platform context, but identity should remain predictable and reviewable.
In the backend
Create a quality dashboard or scheduled query that finds:
- missing or fallback service names;
- one service name used across unrelated namespaces;
- unexpected environment values;
- production telemetry without a version;
- rapid growth in new service names.
This is observability for the observability system. The goal is not perfect metadata. The goal is finding identity failures before they slow down an incident.
Plan semantic convention changes
OpenTelemetry semantic conventions have different stability levels. Stable conventions carry stronger compatibility guarantees, while development, alpha, beta, and release candidate conventions can still evolve. The project’s semantic convention group documentation explains these levels.
Do not enable every new attribute simply because it exists. Record which semantic convention version your instrumentation uses, test changes in a non-production environment, and compare dashboards and queries before rollout. Where a migration option emits both older and newer conventions, use it only for a controlled period because duplicate attributes and metrics can increase cost and confusion.
A practical review checklist
- List every production service name currently reporting telemetry.
- Find fallback, generic, duplicated, and misspelled names.
- Define the approved namespace and naming pattern.
- Separate service identity from environment, version, and instance identity.
- Add validation to deployment templates and pipelines.
- Monitor identity quality in the observability backend.
- Assign an owner for approving changes to the identity contract.
Start with identity before buying more tooling
Reliable observability depends on knowing what produced the data. A disciplined service identity contract improves service maps, deployment analysis, alert routing, incident ownership, and cross-signal correlation. It is a small platform decision with wide operational value.
For teams building or modernizing observability across African digital infrastructure, this is also a practical cost-control measure. Better metadata helps teams reuse dashboards, reduce duplicated investigation, and make more value from the telemetry they already collect.
Observability Africa welcomes organizations that want to support independent community education, practical research, and engineering resources while respecting editorial independence. Teams that need a structured review of telemetry quality, service identity, and operational readiness can also request an independent observability audit.