frontmcp-observability

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.

仓库: agentfront/frontmcp
最近来源活动: 2026年6月5日 00:39
检测到的 SKILL.md 语言: 英语
星标: 147
分支: 6

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

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`

@FrontMcp({
  observability: true,
})

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

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

Pattern	Correct	Incorrect	Why
Enable observability	`observability: true` in `@FrontMcp` config	Import and install `ObservabilityPlugin` manually	Config-driven is the standard pattern since v1.0
Custom spans	`this.telemetry.withSpan('op', fn)`	`trace.getTracer().startSpan()` directly	`this.telemetry` auto-inherits trace context
Log correlation	`this.logger.info('msg', { key: val })`	`console.log('msg')`	SDK logger flows through StructuredLogTransport with trace_id
Session ID	Use `mcp.session.id` attribute (hashed)	Log the real session ID	Privacy: the hash is sufficient for correlation
Vendor integration	Use `{ type: 'otlp', endpoint }` sink	Build vendor-specific HTTP clients	OTLP is the universal standard

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`

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`
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

Example	Level	Description
`basic-tracing`	Basic	Enable auto-tracing and see spans printed to your terminal.
`production-tracing`	Intermediate	Full production observability — traces to OTLP, structured logs to stdout, per-request log collection.

Example	Level	Description
`stdout-logging`	Basic	Enable NDJSON structured logging to stdout with automatic trace correlation and field redaction.
`winston-integration`	Intermediate	Forward FrontMCP structured log entries to your existing winston logger. Each entry includes trace_id and span_id as metadata.

Example	Level	Description
`tool-custom-spans`	Basic	Create child spans, events, and attributes inside a tool's execute method using this.telemetry.
`plugin-telemetry`	Intermediate	Add telemetry events from a custom plugin's hooks. Events appear on the tool execution span, giving you visibility into plugin behavior within the trace.
`agent-nested-tracing`	Advanced	Trace an agent's execution lifecycle including its nested tool calls. Every span shares the same trace ID.

Example	Level	Description
`test-custom-spans`	Basic	Verify that your tool creates the expected child spans with correct attributes.
`test-log-correlation`	Intermediate	Verify that structured log entries include trace context fields for correlation with spans.

Mode	How it works
Filesystem	Read `libs/skills/catalog/frontmcp-observability/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.
`frontmcp` CLI	`frontmcp skills list`, `frontmcp skills read frontmcp-observability`, `frontmcp skills read frontmcp-observability:references/<file>.md`, `frontmcp skills install frontmcp-observability` — no server required.
MCP `skill://`	When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-observability/SKILL.md`, `skill://frontmcp-observability/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it.