Observability & Telemetry

This guide walks through adding production-grade observability to your FrontMCP server — from zero-config tracing to connecting Coralogix, Datadog, or any OTLP-compatible backend.

Prerequisites: A working FrontMCP server with at least one tool. See Your First Tool if you need to get started.

What You’ll Get

Automatic spans for every tool call, resource read, auth flow, and HTTP request
Structured JSON logs with trace correlation (trace_id, span_id)
this.telemetry API for custom spans in your tools and plugins
Per-request log aggregation

Step 1: Install

npm install @frontmcp/observability

This installs the observability package with @opentelemetry/api as the only hard dependency (~50KB). OTel SDK packages are optional peers — install only what you need.

Step 2: Enable Observability

Add the observability field to your @FrontMcp config:

import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'my-server', version: '1.0.0' },
  apps: [MyApp],
  observability: true, // Enable tracing with all defaults
})
export default class Server {}

That’s it. Every flow is now instrumented. Without a TracerProvider configured, all OTel calls are no-ops with zero overhead.

For fine-grained control, pass an object instead of true:

observability: {
  tracing: {
    httpSpans: true,
    executionSpans: true,
    fetchSpans: true,
    flowStageEvents: true,
    transportSpans: true,
    authSpans: true,
  },
  logging: true,
  requestLogs: true,
}

Step 3: Configure a Backend

The @FrontMcp({ ... }) snippets below show only the observability block for brevity. Your full config still needs info: { name, version } and the rest of your server fields.

See spans printed to your terminal — great for development:

import { setupOTel } from '@frontmcp/observability';

setupOTel({
  serviceName: 'my-server',
  exporter: 'console',
});

Send traces to any OTLP-compatible collector (Jaeger, Grafana Tempo, etc.):

import { setupOTel } from '@frontmcp/observability';

setupOTel({
  serviceName: 'my-server',
  exporter: 'otlp',
  endpoint: 'http://localhost:4318',
});

Or use environment variables with no code changes:

OTEL_SERVICE_NAME=my-server \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
node server.js

@FrontMcp({
  observability: {
    tracing: true,
    logging: {
      sinks: [{
        type: 'otlp',
        endpoint: 'https://ingress.coralogix.com:443',
        headers: { Authorization: 'Bearer YOUR_CX_API_KEY' },
      }],
    },
  },
})

@FrontMcp({
  observability: {
    tracing: true,
    logging: {
      sinks: [{
        type: 'otlp',
        endpoint: 'https://http-intake.logs.datadoghq.com',
        headers: { 'DD-API-KEY': 'YOUR_DD_KEY' },
      }],
    },
  },
})

@FrontMcp({
  observability: {
    tracing: true,
    logging: {
      sinks: [{
        type: 'otlp',
        endpoint: 'https://otlp-listener.logz.io:8071',
        headers: { Authorization: 'Bearer YOUR_SHIPPING_TOKEN' },
      }],
    },
  },
})

Forward structured logs to an existing winston logger:

import winston from 'winston';

const logger = winston.createLogger({
  transports: [new winston.transports.Console()],
});

@FrontMcp({
  observability: {
    tracing: true,
    logging: {
      sinks: [{ type: 'winston', logger }],
    },
  },
})

Forward structured logs to an existing pino logger:

import pino from 'pino';

const logger = pino({ transport: { target: 'pino-pretty' } });

@FrontMcp({
  observability: {
    tracing: true,
    logging: {
      sinks: [{ type: 'pino', logger }],
    },
  },
})

Step 4: Use `this.telemetry` in Tools

Every execution context (tools, resources, prompts, agents) gets a this.telemetry API when observability is enabled. No context construction: it inherits the current request’s trace. observability: true installs this.telemetry at runtime, but its type comes from @frontmcp/observability, which declares it on ExecutionContextBase and PromptContext with a declare module '@frontmcp/sdk' augmentation. TypeScript applies that augmentation only when the package is part of the compilation, so import it in the file that uses this.telemetry (a type-only import is enough, and is erased at runtime), or once in any file the project compiles, such as the server entry:

import { Tool, ToolContext } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';
import type {} from '@frontmcp/observability'; // declares this.telemetry

@Tool({
  name: 'search',
  description: 'Search documents',
  inputSchema: { query: z.string() },
})
class SearchTool extends ToolContext {
  async execute({ query }: { query: string }) {
    // Add events to the current tool execution span
    this.telemetry.addEvent('query-parsed', { terms: query.split(' ').length });

    // Create a child span for a specific operation
    const results = await this.telemetry.withSpan('database-query', async (span) => {
      span.setAttribute('db.query', query);
      const data = await this.get(SearchService).search(query);
      span.addEvent('rows-returned', { count: data.length });
      return data;
    });

    // Set attributes on the tool execution span
    this.telemetry.setAttributes({ 'results.count': results.length });

    return { results };
  }
}

This produces:

tool search                          (auto-created by hooks)
  |-- event: query-parsed            (from this.telemetry.addEvent)
  |-- attribute: results.count=42    (from this.telemetry.setAttributes)
  |
  |-- database-query                 (child span from this.telemetry.withSpan)
  |     |-- attribute: db.query=...
  |     |-- event: rows-returned

Step 5: Structured Logging

When logging is enabled, every this.logger.info() call produces a structured JSON entry with automatic trace correlation:

{
  "timestamp": "2026-04-03T10:15:30.123Z",
  "level": "info",
  "severity_number": 9,
  "message": "processing user request",
  "trace_id": "abcdef1234567890abcdef1234567890",
  "span_id": "1234567890abcdef",
  "request_id": "req-uuid-001",
  "session_id_hash": "a3f8b2c1d4e5f6a7",
  "scope_id": "my-app",
  "flow_name": "tools:call-tool",
  "elapsed_ms": 42,
  "attributes": { "userId": 123 }
}

Configure redaction for sensitive fields:

observability: {
  logging: {
    sinks: [{ type: 'stdout' }],
    redactFields: ['password', 'token', 'secret', 'authorization'],
    includeStacks: process.env.NODE_ENV !== 'production',
  },
}

Step 6: Request Log Collection

Enable requestLogs to get a complete aggregated view of each request:

observability: {
  requestLogs: {
    maxEntries: 500,
    onRequestComplete: async (log) => {
      // log.request_id, log.trace_id, log.tool_name
      // log.duration_ms, log.status, log.entries[]
      await myStore.save(log);
    },
  },
}

A request’s log opens when its HTTP request starts and closes when the HTTP response is finalized, which calls onRequestComplete once with the HTTP method and path, the JSON-RPC method, the tool, resource or prompt it served, the entries logged while it ran, its status (error for an HTTP status of 400 or more, or when the tool, resource or prompt failed, with the failure in error; status_code is the status the server actually answered with, a 401 from authentication or a 429 from the throttle included) and its duration. The callback runs off the response path: the response is sent without waiting for it. Up to 1.9.1 the callback never fired. A tool, resource or prompt that fails ends its spans with an error status, the execution span included; up to 1.9.1 a failed tool’s span was left open and never exported. The “tracing enabled but no TracerProvider configured” warning appears only when no provider is registered; up to 1.9.1 it appeared even after setupOTel() or another SDK registered one.

Step 7: Testing with Telemetry

Use the built-in testing utilities to verify your spans:

import { createTestTracer, assertSpanExists, assertSpanAttribute }
  from '@frontmcp/observability';

describe('SearchTool', () => {
  const { tracer, exporter, cleanup } = createTestTracer();

  afterEach(() => exporter.reset());
  afterAll(() => cleanup());

  it('should create a database-query child span', async () => {
    // ... invoke tool ...

    const spans = exporter.getFinishedSpans();
    const dbSpan = assertSpanExists(spans, 'database-query');
    assertSpanAttribute(dbSpan, 'db.query', 'test query');
  });
});

Span Hierarchy

Every request produces a span tree like this:

HTTP Server Span: "POST /mcp"
  |-- event: stage.traceRequest
  |-- event: stage.acquireQuota
  |-- event: stage.checkAuthorization
  |-- event: stage.router
  |
  |-- RPC Span: "tools/call"
  |     |-- rpc.system = "mcp"
  |     |-- mcp.session.id = "a3f8b2c1..."
  |     |-- event: stage.parseInput
  |     |-- event: stage.findTool
  |     |-- event: stage.validateInput
  |     |
  |     |-- Tool Span: "tool get_weather"
  |     |     |-- mcp.component.type = "tool"
  |     |     |-- enduser.id = "client-42"
  |     |     |-- event: stage.execute.start
  |     |     |
  |     |     |-- HTTP Client Span: "GET" (from ctx.fetch)
  |     |     |     |-- url.full = "https://api.weather.com/..."
  |     |     |     |-- http.response.status_code = 200
  |     |     |
  |     |     |-- event: stage.execute.done
  |     |
  |     |-- event: stage.validateOutput
  |     |-- event: stage.finalize
  |
  |-- event: stage.finalize

Attributes Reference

MCP Protocol Attributes (interoperable)

Attribute	Example	Description
`mcp.method.name`	`tools/call`	MCP protocol method
`mcp.session.id`	`a3f8b2c1d4e5f6a7`	Hashed session ID
`mcp.resource.uri`	`file:///data.txt`	Resource URI
`mcp.component.type`	`tool`	Component type: tool, resource, prompt, agent
`mcp.component.key`	`tool:get_weather`	Fully qualified component key

Standard OTel Attributes

Attribute	Example	Description
`rpc.system`	`mcp`	RPC system identifier
`rpc.service`	`my-server`	Server name
`rpc.method`	`tools/call`	RPC method
`http.request.method`	`POST`	HTTP method
`http.response.status_code`	`200`	HTTP status
`enduser.id`	`client-42`	Client ID from auth token
`enduser.scope`	`read write admin`	OAuth scopes

FrontMCP Vendor Attributes

Attribute	Description
`frontmcp.scope.id`	Scope identifier
`frontmcp.request.id`	Unique request ID
`frontmcp.tool.name`	Tool name
`frontmcp.tool.owner`	Tool owner class
`frontmcp.flow.name`	Flow name (e.g., `tools:call-tool`)
`frontmcp.transport.type`	Transport: `legacy-sse`, `streamable-http`
`frontmcp.auth.mode`	Auth mode: `public`, `transparent`, `orchestrated`
`frontmcp.session.id_hash`	Privacy-safe session hash

Best Practices

1. Use this.telemetry for custom instrumentation

Don’t create spans with raw OTel API. Use this.telemetry.withSpan() or this.telemetry.startSpan() — they automatically inherit the trace context and add base attributes.

2. Add events, not child spans, for lightweight markers

this.telemetry.addEvent('step-done') is cheaper than this.telemetry.startSpan('step'). Use events for milestones, spans for timed operations.

3. Redact sensitive fields in structured logs

Always configure redactFields in production: ['password', 'token', 'secret', 'authorization', 'cookie'].

4. Use OTLP for vendor integrations

The otlp sink type works with all major platforms (Coralogix, Datadog, Logz.io, Grafana). Don’t build vendor-specific integrations.

5. Don't over-instrument

The auto-instrumentation covers all SDK flows. Only add this.telemetry spans for your business logic operations (API calls, database queries, complex processing).

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Observability & Telemetry

What You’ll Get

Step 1: Install

Step 2: Enable Observability

Step 3: Configure a Backend

Step 4: Use `this.telemetry` in Tools

Step 5: Structured Logging

Step 6: Request Log Collection

Step 7: Testing with Telemetry

Span Hierarchy

Attributes Reference

MCP Protocol Attributes (interoperable)

Standard OTel Attributes

FrontMCP Vendor Attributes

Best Practices

Next Steps

Telemetry API Reference

Rate Limiting

​What You’ll Get

​Step 1: Install

​Step 2: Enable Observability

​Step 3: Configure a Backend

​Step 4: Use this.telemetry in Tools

​Step 5: Structured Logging

​Step 6: Request Log Collection

​Step 7: Testing with Telemetry

​Span Hierarchy

​Attributes Reference

​MCP Protocol Attributes (interoperable)

​Standard OTel Attributes

​FrontMCP Vendor Attributes

​Best Practices

​Next Steps

Telemetry API Reference

Rate Limiting

What You’ll Get

Step 1: Install

Step 2: Enable Observability

Step 3: Configure a Backend

Step 4: Use `this.telemetry` in Tools

Step 5: Structured Logging

Step 6: Request Log Collection

Step 7: Testing with Telemetry

Span Hierarchy

Attributes Reference

MCP Protocol Attributes (interoperable)

Standard OTel Attributes

FrontMCP Vendor Attributes

Best Practices

Next Steps