Registry / devops / zipkin-instrumentation-grpc

zipkin-instrumentation-grpc

JSON →
library0.0.8jsnpmunverified

Interceptor for instrumenting gRPC calls with Zipkin distributed tracing. Version 0.0.8 is the latest and only stable release. It provides explicit manual instrumentation hooks for client and server sides, supporting both Node.js and Go gRPC servers. Unlike automatic wrappers, this library requires developers to call methods like beforeClientDoGrpcCall, uponServerRecvGrpcCall, uponServerFinishRespond, and afterGrpcCallFinish manually. It depends on zipkin, zipkin-context-cls, and optionally zipkin-transport-http. It uses a global variable ZIPKIN_GRPC_INTCP to hold the interceptor instance. The library is part of the official OpenZipkin JavaScript project.

devopstesting
npm install zipkin-instrumentation-grpc
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · ZIPKIN-INSTRUMENTA
Z
zipkin-instrumentation-grpc
devopsjavascriptv0.0.8
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.

zipkin-instrumentation-grpc
✓ const ZipkinGrpcInterceptor = require('zipkin-instrumentation-grpc'); const interceptor = new ZipkinGrpcInterceptor(tracer);
✗ import ZipkinGrpcInterceptor from 'zipkin-instrumentation-grpc'
Package uses CommonJS and does not export a default. Use require() and call as constructor with tracer argument.
global.ZIPKIN_GRPC_INTCP
✓ global.ZIPKIN_GRPC_INTCP = new (require('zipkin-instrumentation-grpc'))(tracer);
✗ const ZIPKIN_GRPC_INTCP = new (require('zipkin-instrumentation-grpc'))(tracer);
The library expects the interceptor to be stored on global.ZIPKIN_GRPC_INTCP for its methods to be accessible.
CLSContext
✓ const CLSContext = require('zipkin-context-cls'); const ctxImpl = new CLSContext('zipkin');
✗ import { CLSContext } from 'zipkin-context-cls';
zipkin-context-cls is CommonJS. Must require() and instantiate with context name.

Shows how to initialize Zipkin tracer, create the gRPC interceptor, and use its client/server lifecycle methods for manual distributed tracing.

const CLSContext = require('zipkin-context-cls'); const {Tracer, BatchRecorder} = require('zipkin'); const {HttpLogger} = require('zipkin-transport-http'); const zipkinBaseUrl = process.env.ZIPKIN_BASE_URL || 'http://localhost:9411'; const recorder = new BatchRecorder({ logger: new HttpLogger({ endpoint: `${zipkinBaseUrl}/api/v1/spans` }) }); const ctxImpl = new CLSContext('zipkin'); const tracer = new Tracer({ctxImpl, recorder}); global.ZIPKIN_GRPC_INTCP = new (require('zipkin-instrumentation-grpc'))(tracer); // Client side const metadata = global.ZIPKIN_GRPC_INTCP.beforeClientDoGrpcCall({ serviceName: 'my-service', remoteGrpcServiceName: 'sayHello', xB3Sampled: '1' }); client.sayHello({name: 'World'}, metadata, (err, res) => { global.ZIPKIN_GRPC_INTCP.afterGrpcCallFinish(); }); // Server side function handleSayHello(call, callback) { const metadata = global.ZIPKIN_GRPC_INTCP.uponServerRecvGrpcCall({ serviceName: 'my-service', grpcMetadataFromIncomingCtx: call.metadata }); callback(null, {message: 'Hello ' + call.request.name}); global.ZIPKIN_GRPC_INTCP.uponServerFinishRespond(); }
Debug
Known issues
gotchaLibrary relies on global.ZIPKIN_GRPC_INTCP. If you use multiple tracers or packages with similar globals, you may experience conflicts.
fix
Ensure only one instance is stored globally, or refactor to avoid global state.
affects: >=0.0.0
gotchaManual lifecycle management is error-prone: missing afterGrpcCallFinish or uponServerFinishRespond will break tracing.
fix
Always call the corresponding finish method in a finally block or after the call completes.
affects: >=0.0.0
deprecatedUses zipkin-context-cls which is deprecated in favor of zipkin-context-node or native async hooks.
fix
Consider migrating to a more modern context propagation library.
affects: >=0.0.0
breakingLibrary is designed only for gRPC v1 (grpc package), not grpc-js (>=1.24) or @grpc/grpc-js.
fix
Use grpc package version <1.24 or manually adapt the metadata handling.
affects: >=0.0.0
gotchaxB3Sampled must be a string ('1' or '0'), not a boolean. Passing true/false will be ignored.
fix
Always pass the string '1' for sampling.
affects: >=0.0.0
Errors
Common errors & fixes
TypeError: require(...) is not a constructor
Using import or incorrect require pattern for CommonJS module.
fix
Use: const ZipkinGrpcInterceptor = require('zipkin-instrumentation-grpc'); const interceptor = new ZipkinGrpcInterceptor(tracer);
Cannot read property 'beforeClientDoGrpcCall' of undefined
Forgetting to assign the interceptor to global.ZIPKIN_GRPC_INTCP.
fix
Set: global.ZIPKIN_GRPC_INTCP = new (require('zipkin-instrumentation-grpc'))(tracer);
TypeError: tracer is not a constructor
Passing an already-instantiated tracer as class instead of instance.
fix
Pass the Tracer instance, not the class: const tracer = new Tracer({...}); new ZipkinGrpcInterceptor(tracer);
Error: No record found for x-b3-traceid
XB3 headers not passed correctly or missing on server side.
fix
Ensure grpcMetadataFromIncomingCtx is set to call.metadata from the gRPC server call object.
Upgrade
Version history
0.0.8latest on npm
Audit
Dependencies
zipkinrequiredCore Zipkin tracer and recorder classes
zipkin-context-clsrequiredContinuation-local storage context for Node.js async tracking
zipkin-transport-httpoptionalHTTP logger for sending spans to Zipkin
Agent activity
39 hits · last 30 days
node
32
Amazon
1
OpenAI (training)
1
Resources
githubhttps://github.com/openzipkin/zipkin-js ↗
packagezipkin-instrumentation-grpc ↗
homepagehttps://github.com/openzipkin/zipkin-js#readme ↗
zipkin-instrumentation-grpc — npm install zipkin-instrumentation-grpc · libregistry