OpenTelemetry

OpenTelemetry (OTel) is the standard for distributed tracing. Katman's otelWrap creates a span for each procedure call, so you can see every RPC call in your tracing dashboard (Jaeger, Zipkin, Honeycomb, Datadog, etc.).

How it works

otelWrap is a wrap middleware. It creates a span, runs your procedure inside it, then closes the span. If the procedure throws, the span records the error before rethrowing.

Setup

npm install @opentelemetry/api

import { otelWrap } from "katman/otel"
import { trace } from "@opentelemetry/api"

const tracing = otelWrap(trace.getTracer("my-service"))

const listUsers = k.query({
  use: [tracing],
  resolve: ({ ctx }) => ctx.db.users.findMany(),
})

const createUser = k.mutation({
  use: [auth, tracing],
  resolve: ({ ctx, input }) => ctx.db.users.create(input),
})

Each call to these procedures now produces a span in your tracing backend.

What gets recorded

Every span includes:

On errors, the span also includes an exception event:

Event: exception
  exception.message: "Not found"

This means errors are automatically visible in your tracing dashboard — you don't need to add manual error reporting to each procedure.

Custom span name

The default span name is "rpc.call". You can change it:

import { otelWrap } from "katman/otel"

const tracing = otelWrap(tracer, "api.procedure")

Combining with other middleware

otelWrap is a regular wrap middleware. Stack it with guards and other wraps normally:

const createUser = k.mutation({
  use: [auth, rateLimit, tracing],
  //    guards first, then wraps
  resolve: ({ ctx, input }) => ctx.db.users.create(input),
})

Guards (auth, rateLimit) run before the span wraps around the resolver. If you want the span to include guard execution time, put tracing before the guards in the array.

What's next?

• Pino Logging — structured logging for requests and responses
• Middleware — learn about guards and wraps
• Plugins — all available plugins