@opentelemetry/instrumentation-kafkajs

What is @opentelemetry/instrumentation-kafkajs?

@opentelemetry/instrumentation-kafkajs is an OpenTelemetry instrumentation library for KafkaJS, a popular Kafka client for Node.js. This package allows you to automatically collect and report telemetry data such as traces and metrics from KafkaJS applications, helping you monitor and troubleshoot your Kafka-based systems.

What are @opentelemetry/instrumentation-kafkajs's main functionalities?

Automatic Tracing

This feature automatically captures and reports trace data for KafkaJS operations, such as producing and consuming messages. The code sample shows how to set up the NodeTracerProvider and register the KafkaJsInstrumentation to start collecting telemetry data.

const { NodeTracerProvider } = require('@opentelemetry/node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { KafkaJsInstrumentation } = require('@opentelemetry/instrumentation-kafkajs');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new KafkaJsInstrumentation(),
  ],
});

Custom Span Attributes

This feature allows you to add custom attributes to spans for more detailed telemetry data. The code sample demonstrates how to configure the KafkaJsInstrumentation with hooks to add custom attributes to spans for both producer and consumer operations.

const { KafkaJsInstrumentation } = require('@opentelemetry/instrumentation-kafkajs');

const instrumentation = new KafkaJsInstrumentation({
  producerHook: (span, topic, message) => {
    span.setAttribute('custom.attribute', 'value');
  },
  consumerHook: (span, topic, message) => {
    span.setAttribute('custom.attribute', 'value');
  }
});

Other packages similar to @opentelemetry/instrumentation-kafkajs

@opentelemetry/instrumentation-http

This package provides OpenTelemetry instrumentation for HTTP clients and servers. It automatically captures and reports telemetry data for HTTP requests and responses. Compared to @opentelemetry/instrumentation-kafkajs, it focuses on HTTP rather than KafkaJS.

@opentelemetry/instrumentation-express

This package offers OpenTelemetry instrumentation for Express.js applications. It captures and reports telemetry data for Express routes and middleware. While @opentelemetry/instrumentation-kafkajs is specific to KafkaJS, this package is tailored for Express.js.

@opentelemetry/instrumentation-graphql

This package provides OpenTelemetry instrumentation for GraphQL servers. It captures and reports telemetry data for GraphQL queries and mutations. Unlike @opentelemetry/instrumentation-kafkajs, which is for KafkaJS, this package is designed for GraphQL.

README

OpenTelemetry kafkajs Instrumentation for Node.js

This module provides automatic instrumentation for the kafkajs package, which may be loaded using the @opentelemetry/sdk-trace-node package and is included in the @opentelemetry/auto-instrumentations-node bundle.

If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-node bundle with @opentelemetry/sdk-node for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save @opentelemetry/instrumentation-kafkajs

Supported versions

• kafkajs versions >=0.1.0 <3

Usage

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { KafkaJsInstrumentation } = require('@opentelemetry/instrumentation-kafkajs');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new KafkaJsInstrumentation({
      // see below for available configuration
    }),
  ],
});

Instrumentation Options

You can set the following:

Options	Type	Description
producerHook	KafkaProducerCustomAttributeFunction	Function called before a producer message is sent. Allows for adding custom attributes to the span.
consumerHook	KafkaConsumerCustomAttributeFunction	Function called before a consumer message is processed. Allows for adding custom attributes to the span.

Semantic Conventions

This package uses @opentelemetry/semantic-conventions version 1.24+, which implements Semantic Convention Version 1.7.0

Attributes collected:

Attribute	Short Description
messaging.system	An identifier for the messaging system being used.
messaging.destination	The message destination name.
messaging.operation	A string identifying the kind of messaging operation.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.