feat(node): Add an instrumentation interface for Hono #17366

Karibash · 2025-08-10T16:02:24Z

This PR introduces the scaffolding for Sentry’s tracing integration with Hono by adding interface-only implementations and wiring needed to verify the overall approach before filling in the tracing logic.

Summary

Adds a new Hono Instrumentation (OpenTelemetry-based) which patches Hono route and middleware APIs.
Provides a honoIntegration exported via defineIntegration, plus an instrumentHono guard using generateInstrumentOnce.
Introduces minimal, vendored Hono types required for patching, and enums for consistent attribute naming.

Intent & scope

Implemented interfaces only to validate the design direction.
The goal is to confirm the wrapping points, attribute schema, and initialization flow before we add any span creation, context propagation, or attribute setting.
If this approach looks good, the next step is to ship a patch that implements the route handler tracing.
That follow-up will include span start/finish, setting hono.type/hono.name, request path/method extraction, and trace context propagation.
No tests added in this PR because it only introduces the interface and structure. Tests will land together with the first functional instrumentation patch.

Rationale

There is an existing Hono OTel package (@hono/otel), but it currently lacks several features we need for a robust Sentry integration—especially middleware instrumentation and Sentry-specific integration points (e.g., seamless correlation with Sentry transactions/spans and future Sentry error handler wiring).
Given these gaps, we’re proceeding with an in-repo implementation tailored for Sentry’s needs.

Related Issue

#15260

Karibash · 2025-08-10T16:05:47Z

packages/node/src/integrations/tracing/hono/types.ts

I extracted and defined only the minimal types necessary for instrumentation from Hono source code.

Karibash · 2025-08-10T16:09:02Z

packages/node/src/integrations/tracing/hono/instrumentation.ts

+    function Hono(this: HonoInstance, ...args: any): HonoInstance {
+      const app: HonoInstance = moduleExports.Hono.apply(this, args);
+
+      instrumentation._wrap(app, 'get', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'post', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'put', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'delete', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'options', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'patch', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'all', instrumentation._patchHandler());
+      instrumentation._wrap(app, 'on', instrumentation._patchOnHandler());
+      instrumentation._wrap(app, 'use', instrumentation._patchMiddlewareHandler());
+
+      return app;
+    }


Hono dynamically defines these methods within its constructor, which prevented overriding the prototype, so I decided to patch the constructor instead.

Karibash · 2025-08-10T16:14:05Z

packages/node/src/integrations/tracing/hono/instrumentation.ts

+  /**
+   * Patches the route handler to instrument it.
+   */
+  private _patchHandler(): (original: HandlerInterface) => HandlerInterface {
+    return function(original: HandlerInterface) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return function wrappedHandler(this: HonoInstance, ...args: any) {
+        // TODO: Add OpenTelemetry tracing logic here
+        return original.apply(this, args);
+      };
+    };
+  }
+
+  /**
+   * Patches the 'on' handler to instrument it.
+   */
+  private _patchOnHandler(): (original: OnHandlerInterface) => OnHandlerInterface {
+    return function(original: OnHandlerInterface) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return function wrappedHandler(this: HonoInstance, ...args: any) {
+        // TODO: Add OpenTelemetry tracing logic here
+        return original.apply(this, args);
+      };
+    };
+  }
+
+  /**
+   * Patches the middleware handler to instrument it.
+   */
+  private _patchMiddlewareHandler(): (original: MiddlewareHandlerInterface) => MiddlewareHandlerInterface {
+    return function(original: MiddlewareHandlerInterface) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return function wrappedHandler(this: HonoInstance, ...args: any) {
+        // TODO: Add OpenTelemetry tracing logic here
+        return original.apply(this, args);
+      };
+    };
+  }


The implementation of these patches will be submitted later across several PRs.

… instead of function replacement

s1gr1d

Thanks for adding this PR!

s1gr1d · 2025-08-11T12:29:46Z

packages/node/src/integrations/tracing/hono/enums.ts

We don't use enums in our repository (also see related PR). However, I think this file can be deleted, as those enums are not used anywhere.

I have removed the enums as you pointed out.
These values will be needed when specifying span attributes, so at that time I plan to define them as constants with primitive values.
2a6cd6e

s1gr1d · 2025-08-11T12:36:30Z

packages/node/src/integrations/tracing/hono/instrumentation.ts

@@ -0,0 +1,88 @@
+import { InstrumentationBase,InstrumentationNodeModuleDefinition  } from '@opentelemetry/instrumentation';


Run yarn fix to fix linting and the code formatting with prettier.

I’ve fixed it. I’ll be careful not to forget next time.
98a2c37

s1gr1d · 2025-08-11T12:39:36Z

packages/node/src/integrations/tracing/hono/instrumentation.ts

+  /**
+   * Patches the module exports to instrument Hono.
+   */
+  private _patch(moduleExports: { Hono: Hono }): { Hono: Hono } {


Lowercase the hono variable so it's easier to differentiate between the type and the variable.

Suggested change

private _patch(moduleExports: { Hono: Hono }): { Hono: Hono } {

private _patch(moduleExports: { hono: Hono }): { hono: Hono } {

Since we are patching the class exported by hono, wouldn’t it need to be uppercase here, same as the exported class name?
https://github.com/honojs/hono/blob/main/src/hono.ts#L16

ah this makes sense, yes :)

s1gr1d · 2025-08-11T14:32:02Z

Thank you for this contribution 🙌

cursor · 2025-08-11T15:00:26Z

packages/node/src/integrations/tracing/hono/instrumentation.ts

+        instrumentation._wrap(this, 'use', instrumentation._patchMiddlewareHandler());
+      }
+    };
+    return moduleExports;


Bug: Hono Instrumentation Fails on Default Imports

The Hono instrumentation only patches the named Hono export, ignoring the default export. This prevents instrumentation for applications importing Hono as a default. Additionally, the Hono class is replaced in-place without using InstrumentationBase._wrap, and instance methods are wrapped within the subclass constructor. This design prevents proper unpatching, leading to persistent instrumentation where new Hono instances remain wrapped even after the instrumentation is disabled, breaking enable/disable semantics.

This comment was marked as outdated.

Sign in to view

Karibash commented Aug 10, 2025

View reviewed changes

feat(node): Add an instrumentation interface for Hono

0ddfe17

Karibash force-pushed the feature/hono-instrumentation branch from 75251f3 to 0ddfe17 Compare August 10, 2025 16:22

This comment was marked as outdated.

Sign in to view

bugfix(node): Change Hono instrumentation to wrap via class extension…

cb1a52e

… instead of function replacement

Karibash force-pushed the feature/hono-instrumentation branch from b40e85a to cb1a52e Compare August 11, 2025 06:45

refactor(node): Use unknown instead of any

21fba19

Karibash force-pushed the feature/hono-instrumentation branch from 6a3abac to 21fba19 Compare August 11, 2025 08:28

s1gr1d reviewed Aug 11, 2025

View reviewed changes

refactor(node): Remove enums

2a6cd6e

This comment was marked as outdated.

Sign in to view

s1gr1d approved these changes Aug 11, 2025

View reviewed changes

chore(node): Format code with Prettier

e694aae

Karibash force-pushed the feature/hono-instrumentation branch from 98a2c37 to e694aae Compare August 11, 2025 14:53

cursor bot reviewed Aug 11, 2025

View reviewed changes

		@@ -0,0 +1,88 @@
		import { InstrumentationBase,InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';

	private _patch(moduleExports: { Hono: Hono }): { Hono: Hono } {
	private _patch(moduleExports: { hono: Hono }): { hono: Hono } {

Uh oh!

feat(node): Add an instrumentation interface for Hono #17366

Are you sure you want to change the base?

feat(node): Add an instrumentation interface for Hono #17366

Conversation

Karibash commented Aug 10, 2025

Summary

Intent & scope

Rationale

Related Issue

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

s1gr1d left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

s1gr1d commented Aug 11, 2025

Uh oh!

cursor bot Aug 11, 2025

Choose a reason for hiding this comment

Bug: Hono Instrumentation Fails on Default Imports

Uh oh!

Uh oh!