Resouce Equality

Dash0 automatically clusters telemetry you send around resources, the identity of which is based on rules grounded in the OpenTelemetry semantic conventions.

Overview

At Dash0, we emphasize that telemetry without context is just data. A critical part of telemetry context is understanding which system the data originates from.

In OpenTelemetry, a resource represents an entity that generates telemetry, such as a Kubernetes pod, a service, or a Vercel function. Resources are defined by attributes, which serve as key-value pairs describing these entities.

However, in complex environments, multiple telemetry sources report on the same system, often with varying attributes. Dash0’s resource equality rules unify telemetry data across sources by defining when different telemetry records should be treated as coming from the same resource.

This document outlines the rules and best practices for resource equality in Dash0.

OpenTelemetry semantic conventions provide a rich and expanding vocabulary to specify which systems are described by your telemetry. To maintain consistency in telemetry metadata and enhance observability, we recommend following best practices for defining resource attributes. Our blog post on OpenTelemetry resource attributes provides insights into structuring service metadata, ensuring clarity, and leveraging semantic conventions for better troubleshooting.

Why Resource Equality Matters

Telemetry can become fragmented when:

  • Different telemetry sources provide partial or inconsistent resource attributes.
  • Logs, metrics, and traces come from various collection points (e.g., Kubernetes pods, log collectors, application code).
  • Cloud-based deployments introduce differing metadata for the same underlying service.

To maintain consistency, Dash0 merges related telemetry into a single resource using predefined equality rules.

Resource Equality Rules

To each piece of telemetry received, Dash0 assigns the dash0.resource.hash identifier by evaluating all resource attributes sorted deterministically.

Additionally, Dash0 assigns the dash0.resource.id identifier based on the following equality rules.

If two pieces of telemetry are given the same dash0.resource.id identifier, they are considered the same resource.

Step-by-Step Evaluation Process

Step 1: Kubernetes Pods

If k8s.pod.uid exists, resources with the same value are considered identical.
Otherwise, proceed to Step 2.

Step 2: Kubernetes Workloads (excluding Pods)

If any of the following UIDs exist, resources with the same value are considered identical:

  • k8s.cronjob.uid
  • k8s.job.uid
  • k8s.deployment.uid
  • k8s.replicaset.uid
  • k8s.daemonset.uid
  • k8s.statefulset.uid
    Otherwise, proceed to Step 3.

Step 3: Kubernetes Namespace-Level Resources

If k8s.namespace.uid exists, resources with the same value are considered identical.
Otherwise, if k8s.namespace.name exists, it is combined with k8s.cluster.uid (or a fallback value if missing) to determine identity.
Resources must not have workload-related attributes (k8s.pod.name, k8s.deployment.name, etc.).
Otherwise, proceed to Step 4.

Step 4: Kubernetes Node-Level Resources

If k8s.node.uid exists, resources with the same value are considered identical.
Otherwise, if k8s.node.name exists, it is combined with k8s.cluster.uid (or a fallback value if missing) to determine identity.
Resources must not have workload-related attributes.
Otherwise, proceed to Step 5.

Step 5: Kubernetes Cluster-Level Resources

If any of the following exist, resources with the same value are considered identical:

  • k8s.cluster.uid
  • aws.eks.cluster.arn
  • k8s.cluster.name
    Resources must not have workload-related or namespace attributes.
    Otherwise, proceed to Step 6.

Step 6: Non-Kubernetes Containers

If container.id exists, resources with the same value are considered identical.
Otherwise, fallback to container.name.
Otherwise, proceed to Step 7.

Step 7: Host-Level Resources

If host.id exists, resources with the same value are considered identical.
Otherwise, fallback to host.name.
Otherwise, proceed to Step 8.

Step 8: Vercel Deployments

If any of the following exist, resources are considered a vercel.deployment, but the deployment ID is not used in the hash:

  • vercel.deployment_id
  • vercel.deploymentId
  • vercel.sha
    Additionally, service.namespace, service.name, and service.instance.id (or fallbacks) are used to determine identity.
    Otherwise, proceed to Step 9.

Step 9: AWS ECS Tasks

If aws.ecs.task.arn match, resources are considered identical.
Otherwise, proceed to Step 10.

Step 10: Explicitly Defined Service Identity

If service.namespace, service.name, and service.instance.id match, resources are considered identical.
Otherwise, proceed to Step 11.

Step 11: Cloud Resource ID

If cloud.resource_id exists, resources with the same value are considered identical.
Otherwise, proceed to Step 12.

Step 12: AWS Log Grouping

If aws.log.group.names exists, it is combined with cloud.account.id (or a fallback) to determine identity.
Otherwise, proceed to Step 13.

Step 14: Cloud Account-Level Resources

If cloud.account.id exists, it is combined with:

  • cloud.provider (or a fallback)
  • cloud.platform (or a fallback)
    to determine identity.

If no rule applies, the resource remains ungrouped.

Summary

  • Resource equality ensures unified telemetry data across sources.
  • Dash0 applies identity-based, semantic convention-based, and service-based equality rules.
  • Coalesced resources prevent data fragmentation.
  • Users can override default rules using environment variables.

By enforcing resource equality, Dash0 ensures accurate, intuitive, and effective observability across distributed systems.

Last updated: March 23, 2025

PreviousKey Concepts

Operation Names

NextKey Concepts

Synthetic Metrics