A Comprehensive Guide to OpenTelemetry Service Definitions

What Are Service-Level Attributes?

The OTel Semantic Conventions enhance system visibility by defining four key service-level attributes that describe services generating telemetry data. They are shown in the table below, supplemented by an Edge Delta recommended custom attribute, service.technology. 

These attributes ensure consistency, enable correlation across services, and support advanced observability use cases. For instance, a team that is A/B testing different versions of an e-commerce payment service can use the service.version attribute to accurately identify all log data generated from both versions — and to compare performance and user behavior across deployments.

If you choose to include the optional service.namespace attribute, you’ll be able to link components of an application with other resources — such as network devices and storage arrays. This creates a clearer picture of all affected components, which is essential for troubleshooting service behavior.

Attribute Explanations

In this section, we’ll walk through the four service-level attributes in greater detail. For each attribute, we’ve noted a general purpose, example use case, recommended best practice, and overall benefit. We’ve also noted whether an attribute is required or recommended, and labeled each attribute with either “stable,” “in development,” or “for reference” to indicate if the semantic convention has been fully implemented in OTel.

OTel Service Definition Example

Below is an example OTel-based service definition for a .NET order-service within an e-commerce platform, shown in JSON format. This service processes customer orders in a production environment on an EC2 instance, alongside other services like frontend-proxy (NGINX) and product-cache (Redis).

JSON Format:

{
  "resource": {
    "application.name": "ecommerce-platform",
    "service.name": "order-service",
    "service.namespace": "ecommerce",
    "service.version": "1.0.0",
    "service.instance.id": "i-0abcd1234efgh5678",
    "service.technology": "dotnet",
    "environment": "Production",
    "telemetry.sdk.language": "dotnet",
    "telemetry.sdk.name": "serilog",
    "telemetry.sdk.version": "4.1.1"
  }
}

Context:

• The order-service is part of the ecommerce-platform application, grouped under the ecommerce namespace.
• It runs on .NET, with service.technology: "dotnet" clarifying the stack.
• The service.instance.id is an EC2 instance ID (i-0abcd1234efgh5678), demonstrating a non-Kubernetes deployment scenario.
• This setup reflects a typical e-commerce architecture, ensuring relevance to a broad audience.

With this service definition in place, telemetry data can be grouped together by any combination of these fields for more precise enrichment and optimization. For instance, the service.namespace attribute can be used to extract metrics and patterns from all logs originating solely from the "ecommerce" namespace, which provides a more granular view into the workflows running within it.

Benefits of OTel Standardization Over Custom Naming

OTel Semantic Conventions offer significant advantages over custom naming conventions, particularly for organizations seeking interoperable observability at scale. Below are some key benefits:

• Interoperability Across Tools:

• OTel Standardization: Ensures telemetry data is portable across observability backends (such as Jaeger, Prometheus, New Relic, or Datadog), which helps teams avoid vendor lock-in.
  
• Custom Naming: Makes data less portable and requires proprietary mappings, which increases integration costs and complexity.

• Consistency and Scalability:

• OTel Standardization: Attributes like service.name and service.namespace facilitate consistency across teams and services, which simplifies monitoring in large systems.
  
• Custom Naming: Leads to inconsistencies (e.g., app1, service2) that can cause confusion, friction, and data fragmentation.

• Cost Savings:

• OTel Standardization: OTel’s open-source nature eliminates licensing costs associated with proprietary telemetry solutions.

• Custom Naming: Involves significant manual processing overhead. It also increases cardinality for unnecessary metrics and logs, thereby inflating downstream data volumes.  

• Future-Proofing:

• OTel Standardization: OpenTelemetry is actively maintained by a large community, which helps ensure compatibility with emerging technologies and standards.
  
• Custom Naming: Custom solutions risk obsolescence as tools evolve and require costly reworks.

• Enhanced Debugging and Insights:

• OTel Standardization: Attributes like service.version, service.instance.id, and service.technology enable precise debugging (e.g., identifying a faulty instance, version, or technology-specific issue).
  
• Custom Naming: Lacks granularity, hindering root-cause analysis.

Wrapping Up

OTel Semantic Conventions enable organizations to implement scalable, interoperable, and cost-effective observability strategies. These standards ensure consistent telemetry across services, streamline debugging, and future-proof systems by reducing complexity and eliminating vendor lock-in. 

If you’re interested in learning more about accelerating OTel adoption with Edge Delta, get hands-on in our free-to-use playground environment, or schedule a demo with an expert to see how we can support your team’s unique needs.