opentelemetry-instrumentation-kafkajs

opentelemetry-instrumentation-kafkajs is an OpenTelemetry instrumentation plugin for kafkajs, the popular Node.js Kafka client. It patches producer and consumer calls to automatically create spans following OpenTelemetry’s messaging semantic conventions, with trace context propagated through Kafka message headers so consumers can link back to the producing span.

It is one of several instrumentation packages published from the opentelemetry-ext-js monorepo (alongside instrumentations for Sequelize, TypeORM, Elasticsearch, Express, Neo4j, and node-cache), and is registered with OpenTelemetry’s standard registerInstrumentations API alongside any other instrumentation.

What You Get

• Automatic span creation for kafkajs producer sends and consumer message/batch processing, no manual span code required
• Trace-context propagation across Kafka messages via a custom text-map propagator that writes/reads context from message headers
• producerHook and consumerHook callbacks for attaching custom span attributes based on message content
• OpenTelemetry messaging semantic-convention attributes (destination, operation, messaging system) applied automatically
• A moduleVersionAttributeName option to tag spans with the patched kafkajs version for debugging multi-version deployments

Common Use Cases

• Tracing a Kafka-based event pipeline end-to-end across producer and consumer services in a distributed tracing backend (Jaeger, Tempo, etc.)
• Correlating a consumer-side error with the exact producer call that emitted the offending message
• Adding custom business attributes (e.g. order ID, tenant ID) to Kafka spans via the producer/consumer hooks
• Auditing message flow latency between production and consumption in a microservices architecture

Under The Hood

Architecture: the package lives at packages/instrumentation-kafkajs inside the opentelemetry-ext-js Lerna/Yarn-workspaces monorepo, which hosts eight sibling instrumentation packages sharing common tooling. KafkaJsInstrumentation extends OpenTelemetry’s InstrumentationBase and uses InstrumentationNodeModuleDefinition to patch the kafkajs module’s Kafka.prototype.producer/consumer factories at require-time, wrapping the resulting Producer/Consumer instances’ send/run methods to open spans around each message send and each eachMessage/eachBatch callback. Tech Stack: TypeScript, built on @opentelemetry/api and @opentelemetry/instrumentation (the standard OpenTelemetry JS instrumentation base classes) plus @opentelemetry/semantic-conventions for standardized attribute names, with kafkajs as the instrumented peer dependency. Code Quality: tests run via mocha using @opentelemetry/contrib-test-utils (the shared OpenTelemetry contrib test harness) with an optional Jaeger-backed integration test script; the monorepo enforces a shared build/version-update pipeline across all instrumentation packages. API Design: the API follows the exact registration pattern used by every official OpenTelemetry instrumentation (registerInstrumentations + a config object), so it composes naturally with other instrumentations; the producerHook/consumerHook options are a thin, well-documented extension point, though the repository itself has been inactive since its last release, and users are pointed toward the equivalent instrumentation upstreamed into @opentelemetry/instrumentation-kafkajs for continued maintenance.