Automatic vs Manual Instrumentation

In this lesson, you will learn how to balance the "set-it-and-forget-it" efficiency of auto-instrumentation with the surgical precision of manual span control.

When implementing OpenTelemetry in Node.js, auto-instrumentation is your starting point. By using SDK packages that monkey-patch common modules (like http, pg, or express), you gain immediate visibility into incoming requests and database queries without writing custom logic. It is the perfect tool for capturing "system-level" health and basic connectivity across your service graph.

However, auto-instrumentation is often "blind" to your specific business logic. It knows that a controller received a request, but it doesn't know that a specific loop iteration is causing a bottleneck or that a complex async operation involves three distinct business phases.

When to switch to Manual Instrumentation

You should reach for manual instrumentation when you need contextual clarity. If a span represents a black box that doesn't explain what happened inside your application, it is time to wrap those operations manually.

Consider a scenario where you are processing a batch of payments:

const span = tracer.startSpan('process-payment-batch');
try {
  // Auto-instrumentation tracks the network call here
  await paymentService.charge(payload);
} catch (err) {
  span.setStatus({ code: SpanStatusCode.ERROR });
  throw err;
} finally {
  span.end();
}

By manually creating this span, you provide the observability backend with a semantic label ("process-payment-batch") that isn't derived from an HTTP path or a driver method. This allows you to group complex operations that span multiple function calls under a single, meaningful parent.

The Hybrid Approach

The most robust production systems utilize a hybrid approach:

1. Auto-instrumentation for the "plumbing" (HTTP, gRPC, DB drivers) to maintain a baseline of latency and error rates.
2. Manual instrumentation for high-value business transactions or long-running CPU-bound tasks that the generic libraries cannot interpret.

Don't over-instrument everything manually; it creates maintenance overhead and adds noise to your trace analysis. Instead, use manual spans to "annotate" the critical path of your services where understanding the intent is more valuable than just seeing the raw request duration.

Key Takeaway: Use auto-instrumentation to capture the infrastructure layer, but apply manual instrumentation to define the semantic meaning of your business processes.