networksforchange:opentelemetry

This Meteor package hooks up OpenTelemetry (and OTLP-JSON) within a Meteor app. The tracer is customized for Meteor 2's quirky and incompatible way of executing async code. It should help with reporting traces to modern APM products from your existing Meteor app.

What about Meteor 3?

Meteor 3 is already available as a pre-release and should resolve Meteor's 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.

Warning I'm not sure yet how I'll handle compatibility with Meteor 3.
Rest assured I am looking to migrate my own apps, but am not yet sure how this package will migrate.

NodeJS Instrumentation setup

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

(Note that some auto-instrumentations don't hook up right, and might lack span parents, or might not register at all)

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

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

Typing

Create the file opentelemtry.d.ts in your project with the following content:

1type TraceableFunction<T> = (span: import('@opentelemetry/api').Span) => T
2type TraceableAsyncFunction<T> = (span: import('@opentelemetry/api').Span) => Promise<T>;
3type NotAsyncFunction<T> = T extends TraceableAsyncFunction<any> ? never : T;
4
5declare module 'meteor/networksforchange:opentelemetry' {
6
7    export function traceAsyncFunc<T extends TraceableAsyncFunction<R>, R>(spanName: string, func: T): ReturnType<T>;
8    export function traceFunc<T extends TraceableFunction<R>, R>(spanName: string, func: NotAsyncFunction<T>): ReturnType<T>;
9    export function tracedInterval<T>(func: (span: import('@opentelemetry/api').Span) => Promise<T>, delayMs: number): number;
10    export function tracedTimeout<T>(func: (span: import('@opentelemetry/api').Span) => Promise<T>, delayMs: number): number;
11
12}

Note Check the file package.d.ts for the latest typings.

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/networksforchange: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    "networksforchange: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    "networksforchange: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}

Test package locally

Go to the project you want to test this package with and run:

mkdir packages
cd pakcages
ln -s /path/to/meteor-opentelemetry networksforchange:opentelemetry

Then add the package to your project:

meteor add networksforchange:opentelemetry