aedes-otel-instrumentation

OpenTelemetry Aedes Instrumentation

⚠️ Experimental ⚠️

This library provides automatic tracing instrumentation for Aedes and mqtt-packet. It follows OTel guidelines.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save aedes-otel-instrumentation

Supported Versions

• Aedes:

  • no support for Aedes 0.x yet as it requires some changes in the library, see issue

• MQTT-packet

  • [>=8.0.0]
  • it might work with older versions but it was not tested

Usage

OpenTelemetry Aedes Instrumentation allows the user to automatically collect trace data from Aedes. It can also collect distributed traces from MQTT clients that use mqtt-packet library and the MqttPacketInstrumentation. Other MQTT client libraries can be supported by adding the OpenTelemetry context to the MQTT packet, as described here.

To load the instrumentation, specify it in the instrumentations options of the OTel NodeSDK.

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { Resource } from '@opentelemetry/resources'
import {
  PeriodicExportingMetricReader,
  ConsoleMetricExporter,
} from '@opentelemetry/sdk-metrics'
import { NodeSDK } from '@opentelemetry/sdk-node'
import {
  BatchSpanProcessor,
  ConsoleSpanExporter,
} from '@opentelemetry/sdk-trace-base'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { getNodeMqttAutoInstrumentations } from 'aedes-otel-instrumentation'

const traceExporter = new ConsoleSpanExporter()
const metricExporter = new ConsoleMetricExporter()
const metricReader = new PeriodicExportingMetricReader({
  exporter: metricExporter,
})

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'test service',
    [SemanticResourceAttributes.SERVICE_VERSION]:
      process.env.npm_package_version,
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV,
  }),
  traceExporter,
  metricReader,
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': {
        enabled: false,
      },
    }),
    getNodeMqttAutoInstrumentations({
      '@opentelemetry/instrumentation-mqtt-packet': {
        enabled: true,
      },
      '@opentelemetry/instrumentation-aedes': {
        enabled: true,
        publishHook: (span, info) => {
          console.log('publishHook', span)
        },
        consumeHook: (span, info) => {
          console.log('consumeHook', span)
        },
        consumeEndHook: (span, info) => {
          console.log('consumeEndHook', span)
        },
      },
    }),
  ],
  spanProcessor: new BatchSpanProcessor(traceExporter),
})

sdk.start()

process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .catch((error) => console.error('Error terminating tracing', error))
})

Check the example folder for more details.

Open Telemetry Specifications

• Messaging semantic conventions
• Context in MQTT packet

Spans

Name	Aedes method	Description
mqtt.connect	handleConnect	A client is connected
{topic} publish	handlePublish	A client published a message
{topic} receive	handleSubscribe & `Aedes.subscribe``	A client received a message

TODO

• Create span during subscription to track the subscription processing
• Make span ending more accurate based on packet QoS
• Support context in non JSON packet payload (e.g. binary)
• When reaching stable state consider adding this project to OpenTelemetry ecosystem.

License

MIT - See LICENSE for more information.

Changelog

0.2.0 (2023-10-09)

Features

• patch new aedes.wrapDeliveryFunc to correctly modify delivery function (44cbaef)

Bug Fixes

• introduce middleware in aedes to patch delivery function at init or runtime (d790cad)
• make broker URL retrieval method safer (12482fd)
• solve review issues (5d83cf2)
• update aedes patched types (ad3c224)

Test added

• add script and config to run aedes tests with intrumentation lib (0f7170a)
• duplicate and patch original aedes tests (52e9685)

Chores

• remove unused lib (2520e36)