Resource Detection

The "Which Service Is This?" Problem

After deploying OpenTelemetry across 12 microservices running in Kubernetes, I opened Jaeger and saw:

Service: unknown_service:node
Service: unknown_service:node
Service: unknown_service:node
... (12 identical entries)

Every service had the same name. I couldn't tell which spans belonged to which service. Traces were useless.

The problem? I forgot to configure resources—the metadata that identifies your service.

What Are Resources?

Resources are attributes that describe your service:

• Service name: order-service

• Service version: 1.2.3

• Deployment environment: production

• Cloud provider: AWS

• Region: us-east-1

• Container ID: abc123

• Kubernetes pod: order-service-7d9f8-xkj2p

These attributes are attached to every span and metric from your service.

Basic Resource Configuration

import { NodeSDK } from '@opentelemetry/sdk-node';
import { Resource } from '@opentelemetry/resources';
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
  ATTR_DEPLOYMENT_ENVIRONMENT,
} from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: 'order-service',
    [ATTR_SERVICE_VERSION]: '1.2.3',
    [ATTR_DEPLOYMENT_ENVIRONMENT]: 'production',
  }),
  // ... other config
});

sdk.start();

Now in Jaeger:

✅ Service: order-service (v1.2.3) [production]

Automatic Resource Detection

OpenTelemetry can automatically detect resources from your environment:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { Resource } from '@opentelemetry/resources';
import { 
  envDetector,
  hostDetector,
  osDetector,
  processDetector,
  serviceInstanceIdDetectorSync,
} from '@opentelemetry/resources';
import { awsEc2Detector, awsEksDetector } from '@opentelemetry/resource-detector-aws';
import { containerDetector } from '@opentelemetry/resource-detector-container';
import { gcpDetector } from '@opentelemetry/resource-detector-gcp';

const sdk = new NodeSDK({
  resource: Resource.default().merge(
    new Resource({
      // Manual overrides
      [ATTR_SERVICE_NAME]: 'order-service',
      [ATTR_SERVICE_VERSION]: process.env.APP_VERSION || '1.0.0',
    })
  ),
  resourceDetectors: [
    envDetector,              // From environment variables
    hostDetector,             // Hostname
    osDetector,               // OS info
    processDetector,          // Process info
    serviceInstanceIdDetectorSync, // Unique instance ID
    containerDetector,        // Docker/container info
    awsEc2Detector,           // AWS EC2 metadata
    awsEksDetector,           // AWS EKS metadata
    gcpDetector,              // Google Cloud metadata
  ],
  // ... other config
});

sdk.start();

Environment Variable Detection

Set environment variables and OTel picks them up automatically:

export OTEL_SERVICE_NAME=order-service
export OTEL_SERVICE_VERSION=1.2.3
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,team=platform

import { envDetector } from '@opentelemetry/resources';

const sdk = new NodeSDK({
  resourceDetectors: [envDetector],
});

Resulting resource attributes:

{
  "service.name": "order-service",
  "service.version": "1.2.3",
  "deployment.environment": "production",
  "team": "platform"
}

Cloud Provider Detection

AWS EC2

import { awsEc2Detector } from '@opentelemetry/resource-detector-aws';

const sdk = new NodeSDK({
  resourceDetectors: [awsEc2Detector],
});

Automatically detects:

{
  "cloud.provider": "aws",
  "cloud.platform": "aws_ec2",
  "cloud.region": "us-east-1",
  "cloud.availability_zone": "us-east-1a",
  "cloud.account.id": "123456789012",
  "host.id": "i-1234567890abcdef0",
  "host.type": "t3.medium",
  "host.image.id": "ami-0abcdef1234567890"
}

AWS EKS (Kubernetes on AWS)

import { awsEksDetector } from '@opentelemetry/resource-detector-aws';

const sdk = new NodeSDK({
  resourceDetectors: [awsEksDetector],
});

Detects:

{
  "cloud.provider": "aws",
  "cloud.platform": "aws_eks",
  "k8s.cluster.name": "production-cluster",
  "container.id": "abc123...",
  "container.name": "order-service",
  "container.image.name": "myregistry/order-service",
  "container.image.tag": "v1.2.3"
}

Google Cloud

import { gcpDetector } from '@opentelemetry/resource-detector-gcp';

const sdk = new NodeSDK({
  resourceDetectors: [gcpDetector],
});

Kubernetes Detection

For Kubernetes deployments, inject metadata via downward API:

deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
spec:
  template:
    metadata:
      labels:
        app: order-service
        version: v1.2.3
    spec:
      containers:
      - name: order-service
        image: myregistry/order-service:v1.2.3
        env:
        # Inject pod metadata
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: POD_UID
          valueFrom:
            fieldRef:
              fieldPath: metadata.uid
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        
        # OTel configuration
        - name: OTEL_SERVICE_NAME
          value: "order-service"
        - name: OTEL_SERVICE_VERSION
          value: "v1.2.3"
        - name: OTEL_RESOURCE_ATTRIBUTES
          value: "k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.pod.uid=$(POD_UID),k8s.node.name=$(NODE_NAME)"

In your application:

import { envDetector } from '@opentelemetry/resources';

const sdk = new NodeSDK({
  resourceDetectors: [envDetector],
});

Result:

{
  "service.name": "order-service",
  "service.version": "v1.2.3",
  "k8s.pod.name": "order-service-7d9f8-xkj2p",
  "k8s.namespace.name": "production",
  "k8s.pod.uid": "abc-123-def-456",
  "k8s.node.name": "node-1.us-east-1.compute.internal"
}

Custom Resource Detectors

Create your own detector for application-specific metadata:

import { Detector, Resource, ResourceDetectionConfig } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
import * as fs from 'fs';

class GitInfoDetector implements Detector {
  async detect(config?: ResourceDetectionConfig): Promise<Resource> {
    try {
      // Read git commit from file (written by CI/CD)
      const gitCommit = fs.readFileSync('.git-commit', 'utf8').trim();
      const gitBranch = fs.readFileSync('.git-branch', 'utf8').trim();
      
      return new Resource({
        'git.commit.sha': gitCommit,
        'git.branch': gitBranch,
        'build.time': process.env.BUILD_TIME || new Date().toISOString(),
      });
    } catch (error) {
      // If files don't exist, return empty resource
      return Resource.empty();
    }
  }
}

class TeamInfoDetector implements Detector {
  async detect(config?: ResourceDetectionConfig): Promise<Resource> {
    return new Resource({
      'team.name': 'platform',
      'team.slack': '#platform-alerts',
      'team.oncall': 'https://oncall.example.com/platform',
    });
  }
}

// Use custom detectors
const sdk = new NodeSDK({
  resourceDetectors: [
    envDetector,
    new GitInfoDetector(),
    new TeamInfoDetector(),
  ],
});

Resource Attributes in Practice

Filtering by Environment

In Jaeger, filter traces by environment:

deployment.environment=production
service.version=1.2.3

Alerting by Team

In Prometheus alerts:

alert: HighErrorRate
expr: rate(errors_total{team_name="platform"}[5m]) > 0.05
annotations:
  summary: "High error rate in {{ $labels.service_name }}"
  oncall: "{{ $labels.team_oncall }}"
  slack: "{{ $labels.team_slack }}"

Deployment Tracking

Correlate deployments with metrics:

# Errors per version
sum by (service_version) (rate(errors_total[5m]))

# Compare v1.2.2 vs v1.2.3
rate(errors_total{service_version="v1.2.3"}[5m])

When error rate spikes after deploying v1.2.3 → rollback to v1.2.2!

Production Resource Configuration

Here's my production setup:

Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci --production

# Copy application
COPY . .

# Write git info (from build args)
ARG GIT_COMMIT
ARG GIT_BRANCH
ARG BUILD_TIME
RUN echo -n "$GIT_COMMIT" > .git-commit && \
    echo -n "$GIT_BRANCH" > .git-branch && \
    echo -n "$BUILD_TIME" > .build-time

CMD ["node", "--require", "./dist/instrumentation.js", "dist/server.js"]

CI/CD (GitHub Actions):

- name: Build Docker image
  run: |
    docker build \
      --build-arg GIT_COMMIT=${{ github.sha }} \
      --build-arg GIT_BRANCH=${{ github.ref_name }} \
      --build-arg BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
      -t myregistry/order-service:${{ github.sha }} \
      .

Kubernetes Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  labels:
    app: order-service
    team: platform
spec:
  template:
    spec:
      containers:
      - name: order-service
        image: myregistry/order-service:abc123
        env:
        - name: OTEL_SERVICE_NAME
          value: "order-service"
        - name: OTEL_SERVICE_VERSION
          value: "v1.2.3"
        - name: OTEL_RESOURCE_ATTRIBUTES
          value: "team.name=platform,team.slack=#platform,deployment.environment=production,k8s.namespace.name=$(NAMESPACE)"
        - name: NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace

Application Code:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { Resource } from '@opentelemetry/resources';
import { envDetector, hostDetector, processDetector } from '@opentelemetry/resources';
import * as fs from 'fs';

class AppResourceDetector implements Detector {
  async detect(): Promise<Resource> {
    try {
      return new Resource({
        'git.commit.sha': fs.readFileSync('.git-commit', 'utf8').trim(),
        'git.branch': fs.readFileSync('.git-branch', 'utf8').trim(),
        'build.time': fs.readFileSync('.build-time', 'utf8').trim(),
      });
    } catch {
      return Resource.empty();
    }
  }
}

const sdk = new NodeSDK({
  resourceDetectors: [
    envDetector,
    hostDetector,
    processDetector,
    new AppResourceDetector(),
  ],
});

sdk.start();

Final Resource Attributes:

{
  "service.name": "order-service",
  "service.version": "v1.2.3",
  "service.instance.id": "order-service-7d9f8-xkj2p",
  "deployment.environment": "production",
  "team.name": "platform",
  "team.slack": "#platform",
  "k8s.namespace.name": "production",
  "k8s.pod.name": "order-service-7d9f8-xkj2p",
  "host.name": "node-1.us-east-1.compute.internal",
  "process.pid": 1,
  "process.executable.name": "node",
  "process.runtime.name": "nodejs",
  "process.runtime.version": "18.17.0",
  "git.commit.sha": "abc123def456",
  "git.branch": "main",
  "build.time": "2026-01-08T10:30:00Z"
}

Debugging Resource Detection

Enable debug logging:

import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';

// Enable debug logging
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);

const sdk = new NodeSDK({
  resourceDetectors: [envDetector, hostDetector],
});

sdk.start();

Output:

@opentelemetry/resources Resource detected: {
  "service.name": "order-service",
  "host.name": "localhost",
  ...
}

Best Practices

1. Always set service.name - it's the most important attribute

2. Include service.version - for deployment tracking

3. Add team information - for alerting and ownership

4. Use semantic conventions - follow OpenTelemetry standards

5. Automate resource detection - use detectors, don't hardcode

6. Test in staging - verify attributes are correct

7. Keep cardinality low - avoid unique IDs in resource attributes

Common Mistakes

❌ Using high-cardinality values:

// BAD: Every instance has unique ID
new Resource({
  'request.id': generateUniqueId(), // NO!
})

✅ Use low-cardinality values:

// GOOD: Consistent across requests
new Resource({
  'service.instance.id': process.env.POD_NAME,
})

❌ Forgetting to set resources:

// BAD: Default to "unknown_service"
const sdk = new NodeSDK({});

✅ Always configure resources:

// GOOD: Clear service identification
const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: 'order-service',
  }),
});

What's Next

Continue to Custom Exporters to learn:

• Sending telemetry to multiple backends

• Custom exporter implementation

• Cloud provider integrations

• Export batching and retry logic

---

Previous: ← Sampling Strategies | Next: Custom Exporters →

Resources are your service's identity card.