Instrument an App with OpenTelemetry

By Khimananda Oli | Last reviewed: August 2026

You cannot fix latency issues or debug microservice failures if you lack visibility into request flows. To instrument an app with OpenTelemetry, you must integrate the SDK to capture traces, metrics, and logs, then export them via OTLP to a backend like Jaeger or Grafana Tempo. This process replaces vendor-locked agents with a unified, open standard that works across languages and cloud providers. For teams managing complex architectures, understanding this workflow is as critical as mastering observability vs monitoring fundamentals.

How do you instrument an app with OpenTelemetry using auto-instrumentation?

Auto-instrumentation is the fastest path to baseline visibility. It hooks into framework libraries (Express, Django, Spring Boot, Gin) at runtime, capturing HTTP requests, database queries, and outbound calls without modifying source code. In 2026, most stable SDKs support zero-code attachment via CLI agents or environment-based loaders.

Node.js Auto-Instrumentation Setup

For Node.js applications, use the @opentelemetry/auto-instrumentations-node package. This meta-package bundles stable instrumentations for common libraries. Initialize it before your application code runs to ensure all modules are patched correctly.

<!-- tracing.js -->
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4317', // Collector gRPC endpoint
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.error('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Run your application with the require flag to load instrumentation before app initialization:

node --require ./tracing.js server.js

Python Auto-Instrumentation Setup

Python uses a CLI agent approach. Install the core packages and specific library instrumentations, then run your app through the opentelemetry-instrument wrapper. This avoids import-order issues common in Python monkey-patching.

# Install dependencies
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

# Run with auto-instrumentation
export OTEL_SERVICE_NAME=payment-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
opentelemetry-instrument python app.py

A common mistake in production is forgetting graceful shutdown handling. Without flushing buffers on SIGTERM, you lose the last batch of spans during deployments or scaling events. Always implement signal handlers or rely on managed runtime hooks provided by platforms like AWS Lambda or Kubernetes.

When should you add manual spans to OpenTelemetry traces?

Auto-instrumentation captures infrastructure boundaries, but it misses business context. You need manual spans to track domain-specific operations like "validate-coupon", "calculate-shipping", or "fraud-check". These custom spans turn generic flame graphs into actionable debugging tools that map directly to user journeys.

Creating Manual Spans Safely

Always obtain the tracer from the global provider rather than creating instances directly. Use exception-safe patterns to ensure spans close even when errors occur. Unclosed spans leak memory and corrupt trace duration calculations.

const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('checkout-service');

async function processOrder(order) {
  return tracer.startActiveSpan('process-order', async (span) => {
    try {
      span.setAttribute('order.id', order.id);
      span.setAttribute('order.total', order.total);
      
      await validateInventory(order.items);
      const discount = await applyDiscount(order.code);
      
      span.setAttribute('discount.applied', discount.amount);
      return await saveOrder(order);
    } catch (error) {
      span.recordException(error);
      span.setStatus({ code: 2, message: error.message }); // ERROR status
      throw error;
    } finally {
      span.end(); // Always close the span
    }
  });
}

For detailed patterns on correlating these traces with other signals, refer to our guide on distributed tracing with OpenTelemetry and Jaeger. Proper span naming conventions matter: use lowercase-hyphenated names (validate-inventory) over camelCase to maintain consistency across polyglot services.

How do you configure OTLP exporters for production environments?

The OpenTelemetry Protocol (OTLP) is the native wire format for sending telemetry. Production configurations should always route through an OpenTelemetry Collector rather than exporting directly to backends. The Collector handles batching, compression, retry logic, and credential management centrally, preventing each service instance from overwhelming your observability platform.

Environment-Based Configuration

Use environment variables for exporter configuration to keep credentials out of code. The OTel SDK respects standard variable names across all languages, making deployment manifests consistent.

# Kubernetes Deployment Environment Variables
env:
  - name: OTEL_SERVICE_NAME
    value: "payment-api"
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: "http://otel-collector.monitoring:4317"
  - name: OTEL_EXPORTER_OTLP_COMPRESSION
    value: "gzip"
  - name: OTEL_TRACES_SAMPLER
    value: "parentbased_tracealways"
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: "deployment.environment=production,cloud.region=ap-south-1"

In Nepal-based deployments where cross-border latency to AWS Mumbai or Singapore regions can exceed 80ms, placing a local Collector agent as a DaemonSet reduces export latency and prevents timeout-related data loss. This pattern also simplifies compliance auditing since sensitive data can be redacted at the Collector level before leaving your infrastructure boundary.

What are the performance costs of OpenTelemetry instrumentation?

Instrumentation adds CPU overhead, memory allocation, and network egress. In benchmarked production workloads, well-configured OpenTelemetry typically consumes 2–5% additional CPU and 20–50MB RSS memory per service instance. Unconfigured defaults can spike this to 15%+ due to synchronous exports or excessive attribute cardinality.

Critical Optimization Checklist

• Enable sampling: Never run 100% sampling in production. Use ParentBasedTraceIdRatio at 1–10% for high-throughput services.
• Bound attribute cardinality: Avoid user IDs, emails, or timestamps as span attributes. These explode index sizes in backends like Elasticsearch or ClickHouse.
• Use async exporters: Synchronous exporters block request threads. Always configure BatchSpanProcessor with appropriate queue limits.
• Disable unused signals: If you only need traces, disable metrics and logs instrumentation to reduce GC pressure.
• Monitor the SDK itself: Export internal OTel metrics (otel.sdk.exported.spans, otel.sdk.dropped.spans) to detect pipeline backpressure before data loss occurs.

Teams adopting AI-powered log analysis often find that clean, well-structured OpenTelemetry data dramatically improves anomaly detection accuracy compared to raw unstructured logs. Investing in proper instrumentation pays compounding returns when you layer automation on top.

Next Steps for Production Observability

To successfully instrument an app with OpenTelemetry, start with auto-instrumentation in staging, validate span completeness against known user flows, then progressively add manual spans for business-critical paths. Deploy the Collector as a sidecar or DaemonSet before going live, and establish sampling budgets aligned with your observability spend. Treat telemetry configuration as infrastructure code — version it, review it, and test it in CI pipelines just like application logic. If your team needs help designing a compliant, cost-effective observability stack tailored to your architecture, reach out to discuss your specific requirements.