Auto-instrumentation and manual spans: the 80/20 of OTel

Auto-instrumentation tells you “this HTTP request took 800 ms and made 5 DB queries.” Manual instrumentation tells you “the slow part was the fraud-check loop, which fanned out to 12 calls on the rules engine, of which 3 timed out.” Both are necessary. Neither alone is enough.

Auto-instrumentation: the 70-80% you get for free

Most production traffic flows through a small set of frameworks — HTTP servers, HTTP clients, database drivers, message queue clients — that OTel’s contrib libraries instrument out of the box.

Java: The OTel Java Agent (-javaagent JAR) rewrites bytecode at JVM startup and instruments ~200 libraries automatically — no code changes required. Add one -javaagent flag to the JVM arguments, set OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_ENDPOINT env vars, and every HTTP request, JDBC query, and Kafka message is traced.

Python: opentelemetry-instrument wraps the process and monkey-patches common libraries (Flask, Django, FastAPI, SQLAlchemy, Redis, Celery, etc.).

Node.js: @opentelemetry/sdk-node plus a set of instrumentations (express, http, pg, redis, kafkajs) registered before any other require hook framework methods automatically.

Go: Auto-instrumentation is less mature because Go has no monkey-patching. eBPF-based auto-instrumentation (using uprobes) is the emerging approach; the Go OTel contrib libraries require explicit middleware setup per framework.

The 70-80% is the easy part: HTTP routes, DB queries, cache calls, queue interactions. Auto-instrumentation tells you what happened. Manual instrumentation tells you why.

Manual instrumentation: the value bridge

The remaining 20-30% — business-specific spans, custom attributes, and cross-cutting concerns — is where the real diagnostic value lives, because it is where the business questions live.

Pattern: open a span around a business operation, attach attributes that describe the operation, emit span events for noteworthy moments.

const span = tracer.startSpan("fraud.check", {
  attributes: {
    "customer.segment": customer.segment,
    "order.value_cents": order.valueCents,
    "feature_flag.fraud_model": flags.fraudModel,
  },
});

try {
  for (const rule of rules) {
    const result = await rules.engine.evaluate(rule, order);
    span.addEvent("rule.evaluated", {
      "rule.id": rule.id,
      "rule.result": result.outcome,
      "rule.latency_ms": result.latencyMs,
    });
  }
} catch (err) {
  span.recordException(err);
  span.setStatus({ code: SpanStatusCode.ERROR });
} finally {
  span.end();
}

This span tells you customer segment, order value, the feature flag state of the fraud model, and the result of every rule evaluation — data that auto-instrumentation cannot see because it does not know your business domain.

The platform wrapper pattern

Manual instrumentation is the same pattern in every service, so platform teams publish a thin helper library that wraps the OTel API with org-specific conventions:

• Typed business attributes — pre-defined attribute names for common concepts (customer segment, feature flag state, batch size) so teams cannot misspell them.
• Redaction helpers — strip PII before attaching to spans (email → hash, SSN → masked).
• Span event helpers — typed helpers for common events (cache miss, retry, fallback).
• Resource pre-configuration — service name, version, and deployment environment from a standardised env var set.

New services import the wrapper; CI lint rejects raw OTel SDK usage in new code (to prevent ungoverned attribute naming). Override hooks let teams add service-specific attributes without modifying the wrapper.