🚨 OpenTelemetry Error Guide: missing 'service.name' resource — Fix 'unknown_service'

Overview

When an OpenTelemetry SDK exports telemetry without a service.name resource attribute, the SDK logs a warning and falls back to a default name. Backends then group all such telemetry under one meaningless service:

2026-07-09T12:04:18.771Z	warn	OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES are not set; resource is missing the required service.name attribute, defaulting to "unknown_service"

Per the OpenTelemetry resource semantic conventions, service.name is required. If it is absent, SDKs default it to unknown_service (often unknown_service:<process>), and every unnamed workload collapses into the same bucket in your backend.

Symptoms

• Traces, metrics, and logs appear under unknown_service (or unknown_service:java, etc.).
• Multiple distinct workloads are indistinguishable because they share the default name.
• Service maps and dependency graphs are broken or collapsed.
• SDK startup logs warn that service.name is missing.
• Alerts and dashboards keyed on service.name match nothing or match everything.

Common Root Causes

• No OTEL_SERVICE_NAME set — the simplest and most common cause.
• service.name not in OTEL_RESOURCE_ATTRIBUTES — resource attributes set but the key omitted.
• Resource not passed to the provider — manual SDK setup that never attaches a Resource with service.name.
• Env var not propagated — set in the shell but missing in the container/pod spec.
• Overwritten by a processor — a Collector resource processor deletes or blanks the attribute.
• Auto-instrumentation without config — an agent attached but never given a service name.

Diagnostic Workflow

Set the service name the canonical way. OTEL_SERVICE_NAME takes precedence and is the least error-prone:

export OTEL_SERVICE_NAME="checkout-api"
# or, with more resource attributes at once:
export OTEL_RESOURCE_ATTRIBUTES="service.name=checkout-api,service.namespace=shop,service.version=1.4.2,deployment.environment=production"

In Kubernetes, inject these from the pod spec so every replica is labeled consistently:

env:
  - name: OTEL_SERVICE_NAME
    value: "checkout-api"
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: "service.namespace=shop,deployment.environment=production"

As a safety net, have the Collector enforce or backfill service.name for anything arriving unnamed, using the resource processor:

processors:
  resource:
    attributes:
      - key: service.name
        value: "unnamed-fallback"
        action: insert     # insert only if absent; does not overwrite

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlp]

Verify what the SDK actually emitted by inspecting the resource with the debug exporter:

journalctl -u otelcol-contrib --since '10 min ago' | grep -iA5 'Resource attributes'

Example Root Cause Analysis

A Java service used the OpenTelemetry auto-instrumentation agent via -javaagent, but the deployment set no service name — neither OTEL_SERVICE_NAME nor a service.name entry in OTEL_RESOURCE_ATTRIBUTES. Every trace exported with service.name=unknown_service:java. Because three different Java apps in the namespace all lacked the setting, they merged into one unknown_service:java node, making the service map useless.

The fix set OTEL_SERVICE_NAME per Deployment (checkout-api, catalog-api, payments-api) directly in each pod spec, so each workload emitted a distinct, correct resource. To catch future omissions, the gateway Collector added a resource processor with action: insert on service.name (fallback unnamed-fallback) and an alert on any telemetry still carrying that fallback. The service map immediately split back into three correctly named services.

Prevention Best Practices

• Always set OTEL_SERVICE_NAME (or service.name in OTEL_RESOURCE_ATTRIBUTES) for every workload.
• Inject the value from the deployment manifest, not a baked-in default, so replicas stay consistent.
• Include richer resource attributes (service.namespace, service.version, deployment.environment) for filtering.
• Add a Collector resource processor with action: insert as a fallback so nothing is truly anonymous.
• Alert on any telemetry arriving as unknown_service or the fallback name.
• Never let a resource processor use action: upsert/update on service.name unless you intend to overwrite it.

Quick Command Reference

# Confirm the service name is set for the process
env | grep -E 'OTEL_SERVICE_NAME|OTEL_RESOURCE_ATTRIBUTES'

# In Kubernetes, check the injected env
kubectl set env deploy/checkout-api --list | grep OTEL

# Inspect the resource actually emitted
journalctl -u otelcol-contrib | grep -iA5 'Resource attributes'

# Find telemetry still landing under unknown_service (backend query varies)
journalctl -u otelcol-contrib | grep -i 'unknown_service'

Conclusion

A missing service.name is a small omission with an outsized effect: it collapses distinct workloads into unknown_service and breaks every view keyed on service identity. The fix is simple and durable — set OTEL_SERVICE_NAME from each deployment’s spec, enrich with namespace/version/environment, and add a Collector resource fallback plus an alert so nothing ships anonymous. With identity attached at the source, your traces, metrics, and service maps become meaningful again.