Registry / observability / zipkin-instrumentation-hapi

zipkin-instrumentation-hapi

JSON →
library0.22.0jsnpmunverified

zipkin-instrumentation-hapi provides middleware for integrating Hapi.js applications with Zipkin for distributed tracing. It enables automatic span creation for incoming requests and outgoing responses, propagating trace context across service boundaries. The current stable version is 0.22.0, released as part of the broader zipkin-js monorepo. Releases appear to be somewhat frequent, often including bug fixes, new transport support (like AWS SQS in v0.21.0), and improvements to instrumentation across various libraries. Key differentiators include its adherence to the OpenZipkin specification and its tight integration within the zipkin-js ecosystem, offering consistent tracing across different frameworks and transport layers.

npm install zipkin-instrumentation-hapi
INSTALL
IMPORT
SIG · ZIPKIN-INSTRUMENTA
Z
zipkin-instrumentation-hapi
observabilityjavascriptv0.22.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

hapiInstrumentation
import { hapiInstrumentation } from 'zipkin-instrumentation-hapi';
const hapiInstrumentation = require('zipkin-instrumentation-hapi');
Primarily designed for ESM usage in modern Node.js environments. CommonJS `require` might work but is not the idiomatic way for newer versions.
BatchRecorder
import { BatchRecorder } from 'zipkin';
import { BatchRecorder } from 'zipkin-instrumentation-hapi';
Core Zipkin components like recorders are imported from the main `zipkin` package, not from instrumentation packages.
ConsoleRecorder
import { ConsoleRecorder } from 'zipkin';
import { ConsoleRecorder } from 'zipkin-instrumentation-hapi';
Used for development and debugging, also imported from the main `zipkin` package.

This example sets up a basic Hapi server with Zipkin tracing enabled, using `hapiInstrumentation`. It demonstrates configuring a `Tracer` with `BatchRecorder` (for production) or `ConsoleRecorder` (for development), and registering the Hapi plugin. It also includes a basic route and an example of creating a custom child span.

import * as Hapi from '@hapi/hapi'; import { Tracer, BatchRecorder, ConsoleRecorder } from 'zipkin'; import { HttpLogger } from 'zipkin-transport-http'; import { hapiInstrumentation } from 'zipkin-instrumentation-hapi'; const ZIPKIN_URL = process.env.ZIPKIN_URL ?? 'http://localhost:9411'; const recorder = process.env.NODE_ENV === 'production' ? new BatchRecorder({ logger: new HttpLogger({ endpoint: `${ZIPKIN_URL}/api/v2/spans`, headers: { 'Content-Type': 'application/json' } }) }) : new ConsoleRecorder(); const tracer = new Tracer({ recorder, serviceName: 'my-hapi-service' }); const init = async () => { const server = Hapi.server({ port: 3000, host: 'localhost' }); await server.register({ plugin: hapiInstrumentation, options: { tracer, serviceName: 'my-hapi-service' } }); server.route({ method: 'GET', path: '/hello', handler: (request, h) => { // Example of custom span creation const childSpan = tracer.startSpan('greet-user'); tracer.scoped(() => { tracer.recordServiceName('my-hapi-service'); tracer.recordRpc('GET'); tracer.recordAnnotation(new tracer.Annotation.ServerRecv()); // ... do some work ... tracer.recordAnnotation(new tracer.Annotation.ServerSend()); }, childSpan); return 'Hello, Zipkin!'; } }); await server.start(); console.log(`Server running on ${server.info.uri}`); }; process.on('unhandledRejection', (err) => { console.log(err); process.exit(1); }); init();
Debug
Known issues
breakingNode.js 8 support was dropped in version 0.21.0 due to its End-of-Life (EOL). Users on Node.js 8 will not receive updates or fixes.
fix
Upgrade Node.js to a supported version (e.g., Node.js 10 or higher).
affects: >=0.21.0
breakingNode.js 6 support was dropped in version 0.17.1. Applications running on Node.js 6 will fail or encounter issues.
fix
Upgrade Node.js to a supported version (e.g., Node.js 8 or higher, preferably 10+).
affects: >=0.17.1
gotchaWhen upgrading `zipkin-js` packages, ensure all related `zipkin-instrumentation-*` packages are also updated to compatible versions, as breaking changes in core components can affect instrumentations.
fix
Use a consistent version range for all `zipkin-js` related packages, e.g., using `^` or `~` in `package.json`, or explicitly updating all to the latest major release.
affects: all
gotchaThe Hapi instrumentation requires a properly configured `Tracer` instance, which includes a `Recorder` and a `serviceName`. Incorrect configuration can lead to spans not being reported or trace context not propagating.
fix
Always initialize `Tracer` with a `recorder` (e.g., `BatchRecorder` or `ConsoleRecorder`) and a descriptive `serviceName`.
affects: all
breakingPrior to v0.17.1, Hapi 17 support was added. Older versions of the instrumentation may not be fully compatible with Hapi 17+
fix
Upgrade `zipkin-instrumentation-hapi` to version 0.17.1 or newer for robust Hapi 17+ compatibility.
affects: <0.17.1
Errors
Common errors & fixes
Error: Must be valid TraceId instance
This error often relates to issues during transpilation or incorrect handling of trace identifiers.
fix
Ensure your build process correctly transpiles the `zipkin-js` library. This was notably fixed in v0.18.6.
TypeError: Cannot read properties of undefined (reading 'register')
This typically occurs if `hapiInstrumentation` is not properly imported or if the `server.register` call is malformed.
fix
Verify that `hapiInstrumentation` is correctly imported and that the `server.register` call adheres to Hapi's plugin registration syntax, including wrapping the plugin in an object `{ plugin: hapiInstrumentation, options: {...} }`.
Upgrade
Version history
0.22.0latest on npm
Audit
Dependencies
@types/hapioptionalTypeScript type definitions for Hapi, required for type-safe development.
Agent activity
46 hits · last 30 days
node
34
OpenAI (training)
1
Resources
zipkin-instrumentation-hapi — npm install zipkin-instrumentation-hapi · libregistry