{"id":18020,"library":"zipkin-instrumentation-hapi","title":"Zipkin Hapi Instrumentation","description":"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.","status":"active","version":"0.22.0","language":"javascript","source_language":"en","source_url":"https://github.com/openzipkin/zipkin-js","tags":["javascript"],"install":[{"cmd":"npm install zipkin-instrumentation-hapi","lang":"bash","label":"npm"},{"cmd":"yarn add zipkin-instrumentation-hapi","lang":"bash","label":"yarn"},{"cmd":"pnpm add zipkin-instrumentation-hapi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"TypeScript type definitions for Hapi, required for type-safe development.","package":"@types/hapi","optional":true}],"imports":[{"note":"Primarily designed for ESM usage in modern Node.js environments. CommonJS `require` might work but is not the idiomatic way for newer versions.","wrong":"const hapiInstrumentation = require('zipkin-instrumentation-hapi');","symbol":"hapiInstrumentation","correct":"import { hapiInstrumentation } from 'zipkin-instrumentation-hapi';"},{"note":"Core Zipkin components like recorders are imported from the main `zipkin` package, not from instrumentation packages.","wrong":"import { BatchRecorder } from 'zipkin-instrumentation-hapi';","symbol":"BatchRecorder","correct":"import { BatchRecorder } from 'zipkin';"},{"note":"Used for development and debugging, also imported from the main `zipkin` package.","wrong":"import { ConsoleRecorder } from 'zipkin-instrumentation-hapi';","symbol":"ConsoleRecorder","correct":"import { ConsoleRecorder } from 'zipkin';"}],"quickstart":{"code":"import * as Hapi from '@hapi/hapi';\nimport { Tracer, BatchRecorder, ConsoleRecorder } from 'zipkin';\nimport { HttpLogger } from 'zipkin-transport-http';\nimport { hapiInstrumentation } from 'zipkin-instrumentation-hapi';\n\nconst ZIPKIN_URL = process.env.ZIPKIN_URL ?? 'http://localhost:9411';\n\nconst recorder = process.env.NODE_ENV === 'production'\n  ? new BatchRecorder({\n      logger: new HttpLogger({\n        endpoint: `${ZIPKIN_URL}/api/v2/spans`,\n        headers: { 'Content-Type': 'application/json' }\n      })\n    })\n  : new ConsoleRecorder();\n\nconst tracer = new Tracer({\n  recorder,\n  serviceName: 'my-hapi-service'\n});\n\nconst init = async () => {\n  const server = Hapi.server({\n    port: 3000,\n    host: 'localhost'\n  });\n\n  await server.register({\n    plugin: hapiInstrumentation,\n    options: { tracer, serviceName: 'my-hapi-service' }\n  });\n\n  server.route({\n    method: 'GET',\n    path: '/hello',\n    handler: (request, h) => {\n      // Example of custom span creation\n      const childSpan = tracer.startSpan('greet-user');\n      tracer.scoped(() => {\n        tracer.recordServiceName('my-hapi-service');\n        tracer.recordRpc('GET');\n        tracer.recordAnnotation(new tracer.Annotation.ServerRecv());\n        // ... do some work ...\n        tracer.recordAnnotation(new tracer.Annotation.ServerSend());\n      }, childSpan);\n      return 'Hello, Zipkin!';\n    }\n  });\n\n  await server.start();\n  console.log(`Server running on ${server.info.uri}`);\n};\n\nprocess.on('unhandledRejection', (err) => {\n  console.log(err);\n  process.exit(1);\n});\n\ninit();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade Node.js to a supported version (e.g., Node.js 10 or higher).","message":"Node.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.","severity":"breaking","affected_versions":">=0.21.0"},{"fix":"Upgrade Node.js to a supported version (e.g., Node.js 8 or higher, preferably 10+).","message":"Node.js 6 support was dropped in version 0.17.1. Applications running on Node.js 6 will fail or encounter issues.","severity":"breaking","affected_versions":">=0.17.1"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always initialize `Tracer` with a `recorder` (e.g., `BatchRecorder` or `ConsoleRecorder`) and a descriptive `serviceName`.","message":"The 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade `zipkin-instrumentation-hapi` to version 0.17.1 or newer for robust Hapi 17+ compatibility.","message":"Prior to v0.17.1, Hapi 17 support was added. Older versions of the instrumentation may not be fully compatible with Hapi 17+","severity":"breaking","affected_versions":"<0.17.1"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure your build process correctly transpiles the `zipkin-js` library. This was notably fixed in v0.18.6.","cause":"This error often relates to issues during transpilation or incorrect handling of trace identifiers.","error":"Error: Must be valid TraceId instance"},{"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: {...} }`.","cause":"This typically occurs if `hapiInstrumentation` is not properly imported or if the `server.register` call is malformed.","error":"TypeError: Cannot read properties of undefined (reading 'register')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}