Registry / devops / grpc-interceptor-opentracing

grpc-interceptor-opentracing

library1.3.1jsnpmunverified

grpc-interceptor-opentracing is an OpenTracing interceptor for gRPC Node.js servers that automatically creates and propagates spans for each gRPC call. Version 1.3.1 (stable) uses the experimental gRPC interceptor API from @grpc/grpc-js. It chains spans on existing contexts and reports them on call completion. Requires the opentracing package (v0.14) and an OpenTracing-compatible tracer like Jaeger. Unlike manual instrumentation, it provides automatic tracing with minimal configuration. The library is ESM-only and intended for use with the experimental server interceptor pattern (gRPC >=1.24).

devops

npm install grpc-interceptor-opentracing

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-INTERCEPTOR-O

grpc-interceptor-opentracing

devopsjavascriptv1.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

opentracing

✓ import opentracing from 'grpc-interceptor-opentracing';

✗ const opentracing = require('grpc-interceptor-opentracing');

Package exports a default function that returns an interceptor. CommonJS require fails because the package is ESM-only.

opentracing

✓ const opentracing = require('grpc-interceptor-opentracing').default;

✗ const opentracing = require('grpc-interceptor-opentracing');

If using CommonJS with dynamic import or bundler that supports ESM, you must access the .default property. Direct require returns the module object.

OpentracingInterceptorOptions

✓ import type { OpentracingInterceptorOptions } from 'grpc-interceptor-opentracing';

TypeScript users may need to import the options interface for type safety. Not exported in all versions; check typings.

Creates a gRPC server with automatic OpenTracing spans via the interceptor. Requires @grpc/grpc-js and opentracing.

import grpc from '@grpc/grpc-js'; import opentracing from 'grpc-interceptor-opentracing'; import Tracer from 'opentracing'; // or your tracer implementation const tracer = new Tracer(); // e.g., initJaegerTracer from 'jaeger-client' const options = { tracer }; const server = new grpc.Server(); server.use(opentracing(options)); // Add your services and start server as usual server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => { console.log('gRPC server with OpenTracing started'); });

Debug

Known issues

breakingRequires gRPC experimental interceptor API (gRPC >=1.24). Not compatible with older gRPC versions.

fix

Upgrade to @grpc/grpc-js >=1.24 or use the @grpc/proto-loader interceptor alternative.

affects: <1.24

gotchaThe interceptor only works on server-side calls, not client-side.

fix

For client-side tracing, use a separate instrumented client or apply the interceptor on the client side.

affects: ALL

deprecatedgRPC Node.js experimental interceptor API is deprecated in favor of the new async-intercept API. This library may stop working in future gRPC versions.

fix

Consider migrating to opentracing instrumentation using the new gRPC API, such as @opentracing/instrumentation-grpc.

affects: >=1.24

gotchaIf no tracer is provided in options, the global tracer from opentracing is used. If no global tracer is set, an error may occur.

fix

Always provide a tracer instance, or ensure a global tracer has been initialized before using the interceptor.

affects: ALL

gotchaThe library assumes the gRPC call context already has an active span. If no parent span exists, a root span is created.

fix

If you need no new root spans, ensure your application passes an active span context.

affects: ALL

Errors

Common errors & fixes

Error: Cannot find module 'grpc-interceptor-opentracing'

Missing package installation or wrong import path.

fix

Run 'npm install grpc-interceptor-opentracing' and use import/require correctly.

TypeError: opentracing is not a function

Using CommonJS require without accessing .default. Package is ESM-only.

fix

Use import statement: 'import opentracing from "grpc-interceptor-opentracing";' or in CommonJS: 'const opentracing = require("grpc-interceptor-opentracing").default;'

Error: No tracer provided and no global tracer registered

No tracer option passed and no global opentracing tracer instance.

fix

Either pass a tracer in options: 'opentracing({ tracer })' or initialize a global tracer via opentracing.initGlobalTracer().

TypeError: server.use is not a function

gRPC version <1.24 or using old gRPC API (grpc library instead of @grpc/grpc-js).

fix

Upgrade to @grpc/grpc-js >=1.24 which supports server.use() experimental interceptor.

Upgrade

Version history

1.3.1latest on npm

Audit

Dependencies

opentracingrequiredRequired peer dependency for the OpenTracing API (global tracer or custom tracer)

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/edvardchen/node-grpc-experimental-server-interceptors ↗

packagegrpc-interceptor-opentracing ↗

homepagehttps://github.com/edvardchen/node-grpc-experimental-server-interceptors/tree/master/packages/grpc-interceptor-opentracing#readme ↗