danopia:opentelemetry

This Meteor package hooks up OpenTelemetry (and OTLP-JSON) within a Meteor app. It should help with reporting distributed traces to modern APM products from your existing Meteor app. DDP methods and subscriptions will be instrumented between the client and the server programs.

For a basic introduction to this package and some historical background on Meteor 2, see my blog post:

• Tracing Meteor applications with OpenTelemetry

For Meteor 2.x Apps

The last release of this package to target Meteor 2.x is 0.6.2.

I recommend migrating your apps to Meteor 3.

For information about using this library with Meteor 2.x, check out the archived README.

For Meteor 3.x Apps

Since mid-2024, Meteor 3.0 is officially out and resolves Meteor's technical incompatibilities with existing APM libraries. So the need for this library is partially replaced by the Meteor 3 update.

However, this library also provides several OpenTelemetry integrations and APIs which are still useful in Meteor 3. This includes client-to-server trace propagation thru DDP methods and subscriptions, Meteor Mongo instrumentation on the server, and telemetry submission over the existing DDP connection.

Maintanence and updates shall continue (at a casual cadence).

NodeJS Instrumentation setup

The server tracer is easily set up from importing it at the top of your server entrypoint:

1import 'meteor/danopia:opentelemetry';

If you'd like to benefit from the standard NodeJS instrumentations such as HTTP and gRPC, install and register them directly. This way you choose your dependencies and how they are configured.

For the full instrumentation suite, install the meta package:

meteor npm i --save @opentelemetry/auto-instrumentations-node @opentelemetry/instrumentation

Now you just need to configure the instrumentations. For example, this server file disables fs and also skips HTTP healthchecks:

1import 'meteor/danopia:opentelemetry';
2
3import { registerInstrumentations } from '@opentelemetry/instrumentation';
4import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
5
6registerInstrumentations({
7  instrumentations: [
8    getNodeAutoInstrumentations({
9      '@opentelemetry/instrumentation-http': {
10        ignoreIncomingRequestHook(req) {
11          if (req.url == '/healthz' || req.url == '/readyz') return true;
12          if (req.url?.startsWith('/sockjs/')) return true;
13          return false;
14        },
15      },
16      '@opentelemetry/instrumentation-fs': {
17        enabled: false,
18      },
19    }),
20  ],
21});

Browser Setup

Optionally, you can import this package from your client entrypoint to gather in-browser telemetry including client-to-server DDP tracing.

This package will submit OpenTelemetry payloads over Meteor's existing DDP connection, using your application server as a proxy, instead of having every browser talking directly to your otelcol endpoint and thus needing CORS configuration.

Example snippit for your client.ts file:

1// Set up an OpenTelemetry provider using DDP submission and tracing
2// (required to have client-to-server DDP tracing)
3import 'meteor/danopia:opentelemetry';
4
5// Register additional browser-side instrumentations
6// (optional)
7import { registerInstrumentations } from '@opentelemetry/instrumentation';
8import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';
9registerInstrumentations({
10  instrumentations: [
11    new UserInteractionInstrumentation(),
12  ],
13});

Example settings.json

OTLP environment variables are tolerated; for example, these variables will enable tracing:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4218
OTEL_SERVICE_NAME=

You can also enable this library and supply configuration via Meteor settings:

1{
2  "packages": {
3    "danopia:opentelemetry": {
4      "enabled": true,
5      "serverResourceAttributes": {
6        "service.name": "my-app",
7        "deployment.environment": "local"
8      },
9      "clientResourceAttributes": {
10        "service.name": "my-app-browser",
11        "deployment.environment": "local"
12      }
13    }
14  }
15}

Note that OpenTelemetry defines a number of environment variables such as OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_RESOURCE_ATTRIBUTES. Since meteor-opentelemetry submits traces thru DDP, OpenTelemetry wants to treat client and server data similarly. So it might be desirable to set resource attributes via Meteor settings:

1{
2  "packages": {
3    "danopia:opentelemetry": {
4      "enabled": true,
5      "serverResourceAttributes": {
6        "service.name": "my-app",
7        "deployment.environment": "local"
8      },
9      "clientResourceAttributes": {
10        "service.name": "my-app-browser",
11        "deployment.environment": "local"
12      }
13    }
14  }
15}