In an OpenTelemetry SDK, what is a Resource, why does telemetry show up under a name like 'unknown_service' when it is not configured, and how do OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES and resource detectors interact?

## Identity versus event Every piece of telemetry has two kinds of context. **Span attributes** describe the individual operation: which route, which status, how many rows. **Resource attributes** describe the producing entity and are identical for the whole process lifetime: which service, which version, which instance, which host and container. Separating them is not cosmetic. The resource is emitted once per export batch — in OTLP, spans are nested under a resource block — so a hundred spans in a batch carry the identity once instead of a hundred times. It is also the natural key for grouping, routing and multi-tenant separation on the backend. ## The attributes that matter - **service.name** — required in practice; the primary grouping key everywhere. - **service.version** — makes 'did the new build do this?' answerable. - **service.namespace** — disambiguates identically named services across teams. - **service.instance.id** — distinguishes replicas; needed whenever per-instance behaviour matters. - **deployment environment** — the prod/staging separator. Note that its conventional key was renamed during stabilisation, so pin the convention version you target. - Infrastructure keys from detectors: host, OS, process, container, orchestrator pod/node, cloud provider and region. ## Where the values come from **Detectors** run at startup and read the ambient environment: process metadata, hostname, container id from the cgroup, orchestrator downward-API values, cloud instance metadata endpoints. They give you infrastructure identity for free. Two cautions: a detector that calls a metadata endpoint can add startup latency (and hang if that endpoint is unreachable in an unexpected environment), and detector sets differ across SDKs and distributions, so do not assume a key exists because it appeared in another language. **Environment variables** are the portable path. `OTEL_RESOURCE_ATTRIBUTES` takes a comma-separated `key=value` list, with values percent-encoded when they contain reserved characters. `OTEL_SERVICE_NAME` exists because service name is set so often, and it wins over any `service.name` supplied in the attributes list. **Programmatic** configuration composes on top, and is where you add values only the application knows — a build id, a feature-set label. When sources disagree, the general shape is: defaults and detectors first, then environment, then explicit programmatic customisation, with the dedicated service-name variable outranking the generic list. Exact precedence has varied slightly between SDK versions, so if two sources set the same key, set it in one place rather than reasoning about the winner. ## Why 'unknown_service' happens The specification says implementations must supply a fallback service name rather than emitting nothing, so a misconfigured deployment produces telemetry attributed to a placeholder. It is a diagnostic signal, not a bug: seeing it means no environment variable, no programmatic setting and no detector supplied a name — usually a container spec that forgot the variable, or an agent installed without configuration. Multiple unrelated services then merge into one blob, and dashboards filtered by service name silently show nothing. ## Practical rules - **Nothing per-request goes in the resource.** It is immutable and process-wide; a user or request id belongs in span attributes. - **Set the identity trio at deploy time** — service name, version, environment — from the same source of truth that stamps the build, so they cannot drift. - **Beware instance-id cardinality** in metrics. Per-instance series in an autoscaling fleet with short-lived replicas produce large numbers of series; that is a metrics-backend decision, and some pipelines deliberately drop instance id before storage. - **In orchestrated environments prefer downward-API injection** into the environment variable over relying on every SDK having the same detector. - Resource attributes are attached in the process, so if a collector later needs to enrich or override them, that is a pipeline concern, not an SDK one.