Skip to content

Latest commit

 

History

History
131 lines (103 loc) · 4.64 KB

README.md

File metadata and controls

131 lines (103 loc) · 4.64 KB
Raw

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

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.