git:20260605.de54865 to git:20261005.84ff37a

2 added, 1 removed. Audit A to A.

---

name: frontmcp-observability

description: 'Use when adding tracing, structured logging, metrics, or monitoring to a FrontMCP server. Covers zero-config OpenTelemetry distributed tracing across all flows; the this.telemetry API for custom spans, events, and attributes in tools, plugins, agents, and skills; structured JSON logging with trace correlation and configurable sinks (Winston, Pino, stdout); the off-by-default /metrics endpoint (process and framework metrics, Prometheus-compatible); vendor integrations (Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend); and testing spans, log correlation, and instrumentation. Triggers: observability, telemetry, tracing, logging, monitoring, OpenTelemetry, OTel, spans, metrics, Prometheus, Datadog, Coralogix, Logz.io, Grafana, Winston, Pino.'

tags: [router, observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans]

category: observability

targets: [all]

bundle: [recommended, full]

priority: 10

visibility: both

license: Apache-2.0

metadata:

docs: https://docs.agentfront.dev/frontmcp/guides/observability

---

# FrontMCP Observability

Router for adding observability to FrontMCP servers. Covers distributed tracing (OpenTelemetry), structured JSON logging, per-request log collection, the `this.telemetry` developer API, and vendor integrations.

## When to Use This Skill

### Must Use

- Adding tracing, logging, or monitoring to a FrontMCP server

- Connecting Coralogix, Datadog, Logz.io, Grafana, or any OTLP backend

- Using `this.telemetry` to create custom spans in tools, plugins, or agents

- Setting up structured logging with winston, pino, or NDJSON stdout

- Testing that spans and log entries are created correctly

### Recommended

- Before going to production (see also `frontmcp-production-readiness`)

- When debugging request latency or error rates

- When building plugins that need trace context propagation

### Skip When

- Building a prototype that doesn't need observability yet

- Configuring auth, transport, or throttle (see `frontmcp-config`)

- Setting up the project from scratch (see `frontmcp-setup`)

> **Decision:** Use this skill when you need to observe, trace, or log your server. Start with `tracing-setup` for auto-instrumentation, add `structured-logging` for production logs, and use `telemetry-api` for custom spans in your code.

## Prerequisites

- A working FrontMCP server (see `frontmcp-setup`)

- `npm install @frontmcp/observability`

## Step 1: Choose What You Need

| I want to... | Reference |

| -------------------------------------------------- | ------------------------------------- |

| Enable auto-tracing for all flows | `references/tracing-setup.md` |

| Add structured JSON logging with trace correlation | `references/structured-logging.md` |

| Create custom spans in tools/plugins | `references/telemetry-api.md` |

| Connect Coralogix, Datadog, Logz.io, Grafana | `references/vendor-integrations.md` |

| Test that spans and logs are correct | `references/testing-observability.md` |

| Expose Prometheus `/metrics` endpoint | `references/metrics-endpoint.md` |

## Step 2: Enable Observability

The simplest way — one config line:

```typescript

@FrontMcp({

observability: true,

})

```

This enables auto-tracing for all SDK flows. Add structured logging:

```typescript

@FrontMcp({

observability: {

tracing: true,

logging: { sinks: [{ type: 'stdout' }] },

requestLogs: true,

})

```

## Step 3: Read the Relevant Reference

Follow the scenario routing table above to find the right reference for your use case.

## Scenario Routing Table

| Scenario | Reference | Description |

| ------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------- |

| Enable OpenTelemetry tracing | `references/tracing-setup.md` | Zero-config auto-instrumentation, setupOTel(), span hierarchy |

| Add JSON logs with trace correlation | `references/structured-logging.md` | Sinks (stdout, console, OTLP, winston, pino), redaction, log format |

| Custom spans in tools/plugins | `references/telemetry-api.md` | `this.telemetry.startSpan()`, `withSpan()`, `addEvent()`, `setAttributes()` |

| Connect to monitoring platforms | `references/vendor-integrations.md` | Coralogix, Datadog, Logz.io, Grafana — OTLP and direct |

| Test spans and log entries | `references/testing-observability.md` | `createTestTracer()`, `assertSpanExists()`, integration test patterns |

| Expose Prometheus `/metrics` endpoint | `references/metrics-endpoint.md` | Off-by-default Prometheus scrape endpoint with process + framework counters |

## Common Patterns

| -------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |

| Log correlation | `this.logger.info('msg', { key: val })` | `console.log('msg')` | SDK logger flows through StructuredLogTransport with trace_id |

| Vendor integration | Use `{ type: 'otlp', endpoint }` sink | Build vendor-specific HTTP clients | OTLP is the universal standard |

## Quick Reference: What Gets Traced

| Category | Flows | Attributes |

| -------------- | ---------------------------------------------------- | ------------------------------------------------- |

| HTTP requests | traceRequest, auth, route, finalize | `http.request.method`, `url.path` |

| Tool calls | parseInput → findTool → execute → finalize | `mcp.component.type=tool`, `enduser.id` |

| Resource reads | parseInput → findResource → execute | `mcp.component.type=resource`, `mcp.resource.uri` |

| Prompts | parseInput → findPrompt → execute | `mcp.component.type=prompt` |

| Agents | parseInput → findAgent → execute (nested tool calls) | `mcp.component.type=agent` |

| Auth | verify, session verify, OAuth flows | `frontmcp.auth.mode`, `frontmcp.auth.result` |

| Transport | SSE, Streamable HTTP, Stateless HTTP | `frontmcp.transport.type` |

| Skills | search, load, HTTP endpoints | `frontmcp.flow.name` |

## Verification Checklist

### Configuration

- [ ] `@frontmcp/observability` installed

- [ ] `observability` field added to `@FrontMcp` config

- [ ] TracerProvider configured (via `setupOTel()` or external SDK)

- [ ] Logging sinks configured for production (stdout or OTLP)

### Runtime

- [ ] Spans appear in trace backend when calling a tool

- [ ] Log entries include `trace_id` and `span_id`

- - [ ] `this.telemetry` is available in tool execution contexts

+ - [ ] `this.telemetry` is available in tool execution contexts, and `@frontmcp/observability` is imported so it type-checks

- [ ] Session tracing ID is consistent across all spans in a request

- [ ] Errors are recorded on spans with `ERROR` status

### Testing

- [ ] Tests verify span creation with `createTestTracer()`

- [ ] Tests verify log entries via `CallbackSink`

- [ ] No test isolation issues (each test resets exporter)

## Troubleshooting

| Problem | Cause | Solution |

| ------------------------------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |

| `this.telemetry` is undefined in a tool | `observability` not enabled on the parent `@FrontMcp` config | Set `observability: true` (or a config object) in the `@FrontMcp` decorator; see `tracing-setup` |

+ | `Property 'telemetry' does not exist` (TS2339) | `@frontmcp/observability` is not part of the compilation | Add `import type {} from '@frontmcp/observability'` where you use it (or once in the server entry); see `telemetry-api` |

| Spans appear without `trace_id` in logs | Logger not connected to `StructuredLogTransport` | Use `this.logger`, not `console`; see `structured-logging` |

| OTLP exporter silently drops spans | Endpoint URL points at the UI, not the OTLP collector | Use the OTLP HTTP/gRPC ingest endpoint exposed by your vendor (Datadog, Coralogix, Logz, etc.); see `vendor-integrations` |

| Real session ID appears in span attributes | A custom span attribute writes `session.id` directly | Use the SDK-provided `mcp.session.id` (already hashed); never log the raw session token |

| Tests randomly fail with leftover spans | Exporter retained between tests | Reset the in-memory exporter in `afterEach`; see `testing-observability` |

| OTel auto-instrumentation double-traces requests | Both `setupOTel()` AND a vendor agent attached to the process | Pick one: either FrontMCP-managed OTel OR the vendor agent — not both |

## Examples

Each reference has matching examples under [`examples/<reference>/`](./examples/):

### `tracing-setup`