@ogcio/fastify-o11y

Fastify Observability Plugin

This Fastify plugin enhances observability by:

• Attaching the x-trace-id header to responses using OpenTelemetry tracing.
• Recording HTTP response metrics with a counter.

Installation

Ensure you have Fastify and @ogcio/o11y-sdk-node installed in your project with version >= 0.1.0-beta.8

npm install fastify @ogcio/o11y-sdk-node @ogcio/fastify-o11y

Usage

Import and register the plugin in your Fastify server:

import fastify from "fastify";
import observabilityPlugin from "@ogcio/fastify-o11y";

const app = fastify();

app.register(observabilityPlugin);

app.get("/", async () => {
  return { message: "Hello, world!" };
});

app.listen({ port: 3000 }, () => {
  console.log("Server running on http://localhost:3000");
});

Features

1. Trace ID Propagation

This plugin adds the x-trace-id header to responses, extracted from the active OpenTelemetry span.

2. HTTP Response Metrics

The plugin uses getMetric to track HTTP response counts, recording status codes:

const httpResponsesCounter = getMetric<"counter", { status_code: number }>(
  "counter",
  {
    meterName: "http.server.responses",
    metricName: "http.server.responses",
  }
);

Each request updates the counter in the onResponse hook:

server.addHook("onResponse", (_request, reply, done) => {
  try {
    httpResponsesCounter.add(1, { status_code: reply.statusCode });
  } finally {
    done();
  }
});

3. Error Tracing

The plugin traces errors by default using an onError hook:

• Annotates OpenTelemetry spans with error and route details (error type, error code, route, method).
• Adds validation error info (field, rule, message, schema path) if present.
• Marks the span as error.
• No PII is traced.

Disable through the plugin config by explicitly setting traceErrors to false:

app.register(observabilityPlugin, { traceErrors: false });

How It Works

• onRequest Hook: Extracts the trace ID and attaches it to the response headers.
• onResponse Hook: Increments the HTTP response counter with the response status code.
• onError Hook: Extracts error info from FastifyError and injects them in current active span as spanAttributes, events, and exception.