Instrument Your Node.js Socket.io Apps with OpenTelemetry Like a PRO

Today we released a first-of-its-kind OpenTelemetry auto instrumentation plugin. An OpenTelemetry Socket.io Instrumentation for Node.js.

What makes this instrumentation different?

Well, first, it’s the first full OpenTelemetry instrumentation for Socket.io ever written.
Second, there are no OpenTelemetry specs for Socket.io or WebSocket; usually, at Aspecto, we try to make our instrumentation as close to the specs as possible, but in this case, we had to improvise.

This is what we chose to do

It seemed reasonable to categorized Socket.io under the messaging specs since we have a producer (emit) a receiver (on) and a message.

Having looked at how other messaging systems with unique characteristics like Kafka do it, we added some custom attributes to the Socket.io traces:
messaging.socket.io.event_name with the event name
messaging.socket.io.rooms with an array of socket.io rooms
messaging.socket.io.namespace with the namespace

So what do you need to do?

You can follow one of these options, depending on your current stack and needs:

1. Using the Aspecto SDK – Socket.io is included in the Aspecto OpenTelemetry Package – @aspecto/opentelemetry – which means you only need to follow the Aspecto SDK installation docs.

2. Installing OpenTelemetry yourself – keep on reading.

Note: If you’re using a different OpenTelemetry distribution (e.g., vendor, @opentelemetry/auto-instrumentations-node, etc) – visit the relevant docs and search for instructions on adding additional instrumentations libraries.

Install OpenTelemetry Socket.io instrumentation in your app

Now for the fun stuff. If you already have an app with Socket.io installed – great! If not, create a Node.js Socket.io app (need one? We got you).

Once you have you an Socket.io installed in our app, let’s instrument it.

npm install \
 @opentelemetry/core \
 @opentelemetry/sdk-trace-node \
 @opentelemetry/instrumentation \
 @opentelemetry/sdk-trace-base

Then install our OpenTelemetry Socket.io instrumentation.

npm install opentelemetry-instrumentation-socket.io

Now, this is the most essential part. Since the plugin patches Socket.io, you must initialize it before any module requires it, so we’re going to put our initialization code at the top of the `index.ts` file.

First, let’s import the files. It should look something like this:

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { SocketIoInstrumentation } from "opentelemetry-instrumentation-socket.io"; 
import { ConsoleSpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";

And to the exciting part, register our Socket.io instrumentation:

const provider = new NodeTracerProvider();
registerInstrumentations({
 instrumentations: [new SocketIoInstrumentation()],
});

And we are done!

The complete initialization code should look like this:

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { SocketIoInstrumentation } from "opentelemetry-instrumentation-socket.io";
import { ConsoleSpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
const provider = new NodeTracerProvider();
registerInstrumentations({
 instrumentations: [new SocketIoInstrumentation()],
});
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

Now you can run the app and see the traces in the console thanks to the ConsoleSpanExporter.

Here’s is an example trace from stocker.

{
 traceId: ‘e05c479e3d3c7980a1290ef8a8c1d669’,
 parentId: undefined,
 name: ‘/[AAPL] send’,
 id: ‘327a29bf1d58469c’,
 kind: 3,
 timestamp: 1622705582441890,
 duration: 428,
 attributes: {
 ‘messaging.system’: ‘socket.io’,
 ‘messaging.destination_kind’: ‘topic’,
 ‘messaging.socket.io.event_name’: ‘price-update’,
 ‘messaging.socket.io.rooms’: [ ‘AAPL’ ],
 ‘messaging.socket.io.namespace’: ‘/’,
 ‘messaging.destination’: ‘/’
 },
 status: { code: 0 },
 events: []
}

You can find the source code on GitHub.

Isn’t that cool?

Here’s how we visualize Socket.io traces in the Aspecto platform.  

Check out our other awesome instrumentations made with ❤️.

Free OpenTelemetry Resources

Here are some more free resources to help you with your OpenTelemetry journey:

1. The OpenTelemetry Bootcamp – A free, vendor-neutral, 6 episode video series that will take you from zero to mastering OpenTelemetry (including running in production, security, sampling, collector and much more).
2. A quick intro guide to OpenTelemetry.

Feel free to reach out to us with any feedback ✌️