@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-observability/references/structured-logging.md

@@ -0,0 +1,114 @@
+---
+name: structured-logging
+description: 'Add structured JSON logging with trace correlation and configurable sinks (stdout, winston, pino, OTLP).'
+tags: [logging, structured, json, sinks, ndjson, winston, pino, redaction]
+---
+
+# Structured Logging
+
+Add structured JSON logging that enriches every log entry with `trace_id`, `span_id`, `request_id`, and `session_id_hash`. Logs flow through configurable sinks — stdout (NDJSON), winston, pino, OTLP, console, or custom callbacks.
+
+## How It Works
+
+```
+this.logger.info('message', { userId: 123 })
+    │
+    ├── ConsoleLogTransport (dev console — pretty colored output)
+    │
+    └── StructuredLogTransport (enriches with trace context)
+          ├── StdoutSink → NDJSON to stdout (Docker/K8s collects)
+          ├── OtlpSink → OTLP HTTP to Coralogix/Datadog/Logz.io
+          ├── WinstonSink → forward to winston instance
+          ├── PinoSink → forward to pino instance
+          └── CallbackSink → custom handler function
+```
+
+## Enable Structured Logging
+
+```typescript
+@FrontMcp({
+  observability: {
+    tracing: true,
+    logging: true,          // Default: StdoutSink (NDJSON)
+  },
+})
+```
+
+## Log Entry Format
+
+Every `this.logger.info()` call produces:
+
+```json
+{
+  "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,
+  "prefix": "MyTool",
+  "attributes": { "userId": 123 }
+}
+```
+
+## Configure Sinks
+
+```typescript
+observability: {
+  logging: {
+    sinks: [
+      { type: 'stdout' },                                    // NDJSON to stdout
+      { type: 'console' },                                   // console.log (browser-safe)
+      { type: 'otlp', endpoint: 'http://collector:4318' },   // OTLP to any backend
+      { type: 'winston', logger: winstonInstance },           // Forward to winston
+      { type: 'pino', logger: pinoInstance },                 // Forward to pino
+      { type: 'callback', fn: (entry) => queue.push(entry) },// Custom handler
+    ],
+    redactFields: ['password', 'token', 'secret', 'authorization'],
+    includeStacks: process.env.NODE_ENV !== 'production',
+    staticFields: { service: 'my-server', env: 'production' },
+  },
+}
+```
+
+## Sink Types
+
+| Type       | Output                       | Environment      | Use Case                             |
+| ---------- | ---------------------------- | ---------------- | ------------------------------------ |
+| `stdout`   | NDJSON to `process.stdout`   | Node.js          | 12-factor apps, Docker, K8s          |
+| `console`  | `console.log/warn/error`     | Browser, Node.js | Local dev, browser apps              |
+| `otlp`     | OTLP HTTP POST to `/v1/logs` | Node.js          | Coralogix, Datadog, Logz.io, Grafana |
+| `winston`  | Forward to winston instance  | Node.js          | Existing winston setup               |
+| `pino`     | Forward to pino instance     | Node.js          | Existing pino setup                  |
+| `callback` | User-provided function       | Any              | Custom integrations                  |
+
+## Field Redaction
+
+Sensitive fields are replaced with `[REDACTED]` before reaching any sink:
+
+```typescript
+logging: {
+  redactFields: ['password', 'token', 'secret', 'authorization', 'cookie'],
+}
+```
+
+Redaction is recursive (handles nested objects) and case-insensitive.
+
+## Examples
+
+| Example                                                                        | Level        | Description                                                                                                                    |
+| ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| [`stdout-logging`](../examples/structured-logging/stdout-logging.md)           | Basic        | Enable NDJSON structured logging to stdout with automatic trace correlation and field redaction.                               |
+| [`winston-integration`](../examples/structured-logging/winston-integration.md) | Intermediate | Forward FrontMCP structured log entries to your existing winston logger. Each entry includes trace_id and span_id as metadata. |
+
+> See all examples in [`examples/structured-logging/`](../examples/structured-logging/)
+
+## Reference
+
+- [Observability Guide](https://docs.agentfront.dev/frontmcp/guides/observability)
+- Related skills: `frontmcp-observability`, `frontmcp-production-readiness`

package/catalog/frontmcp-observability/references/telemetry-api.md

@@ -0,0 +1,155 @@
+---
+name: telemetry-api
+description: 'Use this.telemetry in tools, plugins, and agents to create custom spans, events, and attributes.'
+tags: [telemetry, api, spans, events, attributes, this-telemetry, custom]
+---
+
+# Telemetry API (`this.telemetry`)
+
+Every execution context (tools, resources, prompts, agents) gets a `this.telemetry` API when observability is enabled. No imports, no context construction — it automatically inherits the current request's trace ID, session ID, and scope.
+
+## Available Methods
+
+| Method                       | Purpose                                             |
+| ---------------------------- | --------------------------------------------------- |
+| `startSpan(name, attrs?)`    | Create a child span (you must call `.end()`)        |
+| `withSpan(name, fn, attrs?)` | Run a function in an auto-managed span              |
+| `addEvent(name, attrs?)`     | Add an event to the active execution span           |
+| `setAttributes(attrs)`       | Set attributes on the active execution span         |
+| `traceId`                    | Get the current trace ID (for external correlation) |
+| `sessionId`                  | Get the privacy-safe session tracing ID             |
+
+## Usage in Tools
+
+```typescript
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'analyze_data',
+  description: 'Analyze dataset with custom telemetry',
+  inputSchema: { datasetId: z.string() },
+})
+class AnalyzeDataTool extends ToolContext<typeof AnalyzeDataTool> {
+  async execute({ datasetId }: { datasetId: string }) {
+    // Events go on the "tool analyze_data" span
+    this.telemetry.addEvent('analysis-started', { datasetId });
+
+    // Child span for a specific operation
+    const data = await this.telemetry.withSpan('fetch-dataset', async (span) => {
+      span.setAttribute('dataset.id', datasetId);
+      const res = await this.fetch(`/api/datasets/${datasetId}`);
+      span.addEvent('data-received', { rows: res.headers.get('x-total-count') ?? '0' });
+      return res.json();
+    });
+
+    // Attributes on the execution span
+    this.telemetry.setAttributes({ 'dataset.size': data.length });
+
+    // Another child span
+    const result = await this.telemetry.withSpan('run-analysis', async (span) => {
+      const analysis = this.get(AnalysisService).run(data);
+      span.setAttribute('result.score', analysis.score);
+      return analysis;
+    });
+
+    return { score: result.score, datasetId };
+  }
+}
+```
+
+Result in the trace:
+
+```
+tool analyze_data
+  ├── event: analysis-started
+  ├── attribute: dataset.size = 1500
+  │
+  ├── fetch-dataset (child span)
+  │     ├── attribute: dataset.id = "ds-123"
+  │     └── event: data-received
+  │
+  └── run-analysis (child span)
+        └── attribute: result.score = 0.95
+```
+
+## Usage in Plugins
+
+External plugins use the same `this.telemetry` API. Events appear on the parent tool/resource span:
+
+```typescript
+@Plugin({ name: 'my-audit-plugin', contextExtensions: [...] })
+class AuditPlugin extends DynamicPlugin<AuditOptions> {
+  @ToolHook.Will('execute')
+  willExecute(flowCtx: FlowCtxOf<'tools:call-tool'>): void {
+    const toolCtx = flowCtx.state.toolContext;
+    if (toolCtx?.telemetry) {
+      toolCtx.telemetry.addEvent('audit.pre-check', { policy: 'strict' });
+    }
+  }
+}
+```
+
+## Usage in Agents
+
+Agents have the same API. Nested tool calls automatically share the trace ID:
+
+```typescript
+@Agent({ name: 'research-agent', tools: [WebSearchTool, SummarizerTool] })
+class ResearchAgent extends AgentContext {
+  async execute(input: { query: string }) {
+    this.telemetry.addEvent('research-started', { query: input.query });
+    // Nested tool calls get their own spans under the agent span
+    return super.execute(input);
+  }
+}
+```
+
+## Manual Span Management
+
+For operations where you need explicit control:
+
+```typescript
+const span = this.telemetry.startSpan('complex-operation', {
+  'operation.type': 'batch-import',
+  'batch.size': items.length,
+});
+
+try {
+  for (const item of items) {
+    await processItem(item);
+    span.addEvent('item-processed', { itemId: item.id });
+  }
+  span.end();
+} catch (err) {
+  span.recordError(err);
+  span.endWithError(err);
+  throw err;
+}
+```
+
+## Access to Raw OTel Span
+
+For advanced use cases, access the underlying OTel Span:
+
+```typescript
+const telemetrySpan = this.telemetry.startSpan('advanced-op');
+const otelSpan = telemetrySpan.raw; // @opentelemetry/api Span
+otelSpan.setAttributes({ 'custom.otel.attr': 'value' });
+telemetrySpan.end();
+```
+
+## Examples
+
+| Example                                                                     | Level        | Description                                                                                                                                               |
+| --------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tool-custom-spans`](../examples/telemetry-api/tool-custom-spans.md)       | Basic        | Create child spans, events, and attributes inside a tool's execute method using this.telemetry.                                                           |
+| [`plugin-telemetry`](../examples/telemetry-api/plugin-telemetry.md)         | 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`](../examples/telemetry-api/agent-nested-tracing.md) | Advanced     | Trace an agent's execution lifecycle including its nested tool calls. Every span shares the same trace ID.                                                |
+
+> See all examples in [`examples/telemetry-api/`](../examples/telemetry-api/)
+
+## Reference
+
+- [Telemetry API Reference](https://docs.agentfront.dev/frontmcp/sdk-reference/telemetry)
+- Related skills: `frontmcp-development`, `frontmcp-extensibility`

package/catalog/frontmcp-observability/references/testing-observability.md

@@ -0,0 +1,169 @@
+---
+name: testing-observability
+description: 'Test that your spans, log entries, and telemetry instrumentation work correctly.'
+tags: [testing, spans, assertions, integration, jest]
+---
+
+# Testing Observability
+
+Verify that your tools create the right spans, log entries include trace context, and custom telemetry produces the expected output.
+
+## Test Utilities
+
+```typescript
+import {
+  createTestTracer,
+  getFinishedSpans,
+  assertSpanExists,
+  assertSpanAttribute,
+  findSpan,
+  findSpansByAttribute,
+} from '@frontmcp/observability';
+```
+
+## Testing Custom Spans
+
+```typescript
+describe('AnalyzeDataTool', () => {
+  const { tracer, exporter, cleanup } = createTestTracer();
+
+  afterEach(() => exporter.reset());
+  afterAll(() => cleanup());
+
+  it('should create a fetch-dataset child span', async () => {
+    // ... invoke tool ...
+
+    const spans = getFinishedSpans(exporter);
+    const fetchSpan = assertSpanExists(spans, 'fetch-dataset');
+    assertSpanAttribute(fetchSpan, 'dataset.id', 'ds-123');
+  });
+
+  it('should record error on span when API fails', async () => {
+    // ... invoke tool that fails ...
+
+    const spans = getFinishedSpans(exporter);
+    const span = findSpan(spans, 'fetch-dataset');
+    expect(span?.status.code).toBe(SpanStatusCode.ERROR);
+  });
+});
+```
+
+## Testing Log Entries
+
+Use a `CallbackSink` to capture structured log entries:
+
+```typescript
+import { StructuredLogTransport, CallbackSink } from '@frontmcp/observability';
+import type { StructuredLogEntry } from '@frontmcp/observability';
+
+describe('Structured logging', () => {
+  it('should include trace_id in log entries', () => {
+    const entries: StructuredLogEntry[] = [];
+    const sink = new CallbackSink((e) => entries.push(e));
+
+    const transport = new StructuredLogTransport([sink], {}, () => ({
+      requestId: 'req-001',
+      traceContext: { traceId: 'a'.repeat(32), parentId: 'b'.repeat(16), traceFlags: 1 },
+      sessionIdHash: 'hash12345678',
+      scopeId: 'test',
+      elapsed: 0,
+    }));
+
+    transport.log({
+      level: 2,
+      levelName: 'info',
+      message: 'test message',
+      args: [{ userId: 123 }],
+      timestamp: new Date(),
+      prefix: 'MyTool',
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].trace_id).toBe('a'.repeat(32));
+    expect(entries[0].attributes).toEqual({ userId: 123 });
+  });
+});
+```
+
+## Testing Auto-Instrumentation Hooks
+
+Test that the SDK's hook functions produce correct spans:
+
+```typescript
+import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import {
+  onToolWillParse,
+  onToolWillExecute,
+  onToolDidExecute,
+  onToolDidFinalize,
+} from '@frontmcp/observability/plugin/observability.hooks';
+
+const exporter = new InMemorySpanExporter();
+const provider = new BasicTracerProvider();
+provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+provider.register();
+
+it('should create RPC + tool spans', () => {
+  const flowCtx = {
+    state: { input: { name: 'my_tool' }, _toolOwnerId: 'MyApp' },
+    get: (token) => {
+      if (token === Symbol.for('frontmcp:CONTEXT')) {
+        return {
+          requestId: 'req-001',
+          sessionId: 'sess',
+          scopeId: 'scope',
+          traceContext: { traceId: 'a'.repeat(32), parentId: 'b'.repeat(16), traceFlags: 1, raw: '...' },
+          authInfo: {},
+          metadata: { customHeaders: {} },
+          set: () => {},
+          get: () => undefined,
+          delete: () => {},
+        };
+      }
+    },
+  };
+
+  const opts = { executionSpans: true, flowStageEvents: true };
+  onToolWillParse(opts, flowCtx);
+  onToolWillExecute(opts, flowCtx);
+  onToolDidExecute(opts, flowCtx);
+  onToolDidFinalize(flowCtx);
+
+  const spans = exporter.getFinishedSpans();
+  expect(spans.find((s) => s.name === 'tools/call')).toBeTruthy();
+  expect(spans.find((s) => s.name === 'tool my_tool')).toBeTruthy();
+});
+```
+
+## Test Isolation
+
+Each test should:
+
+1. Call `exporter.reset()` in `beforeEach` to clear previous spans
+2. Call `cleanup()` in `afterAll` to shut down the provider
+3. Use `createTestTracer()` which does NOT register globally (safe for parallel tests)
+
+## API Reference
+
+| Function                                  | Purpose                                             |
+| ----------------------------------------- | --------------------------------------------------- |
+| `createTestTracer(name?)`                 | Create isolated tracer + exporter (not global)      |
+| `getFinishedSpans(exporter)`              | Get all exported spans                              |
+| `assertSpanExists(spans, name)`           | Assert span exists, return it (throws if not found) |
+| `assertSpanAttribute(span, key, value)`   | Assert attribute value on a span                    |
+| `findSpan(spans, name)`                   | Find span by name (returns undefined if not found)  |
+| `findSpansByAttribute(spans, key, value)` | Find all spans with matching attribute              |
+
+## Examples
+
+| Example                                                                             | Level        | Description                                                                                 |
+| ----------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| [`test-custom-spans`](../examples/testing-observability/test-custom-spans.md)       | Basic        | Verify that your tool creates the expected child spans with correct attributes.             |
+| [`test-log-correlation`](../examples/testing-observability/test-log-correlation.md) | Intermediate | Verify that structured log entries include trace context fields for correlation with spans. |
+
+> See all examples in [`examples/testing-observability/`](../examples/testing-observability/)
+
+## Reference
+
+- [Telemetry API Reference](https://docs.agentfront.dev/frontmcp/sdk-reference/telemetry)
+- Related skills: `frontmcp-testing`, `frontmcp-observability`

package/catalog/frontmcp-observability/references/tracing-setup.md

@@ -0,0 +1,146 @@
+---
+name: tracing-setup
+description: 'Enable OpenTelemetry distributed tracing for all FrontMCP flows with zero configuration.'
+tags: [tracing, opentelemetry, spans, setup]
+---
+
+# Tracing Setup
+
+Enable automatic distributed tracing for every flow in your FrontMCP server. When enabled, 103+ hooks create spans for tool calls, resource reads, HTTP requests, auth flows, transport sessions, and more — with zero code changes.
+
+## How It Works
+
+1. Set `observability: true` in `@FrontMcp` config
+2. The SDK auto-loads `@frontmcp/observability` and registers hooks on all 33 flows
+3. Every request gets a single W3C trace ID, shared across all spans
+4. Without a TracerProvider, all OTel calls are no-ops (zero overhead)
+
+## Enable Tracing
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  observability: true,
+})
+export default class Server {}
+```
+
+## Configure a TracerProvider
+
+Spans only appear when a TracerProvider is configured. Three ways:
+
+### Option A: setupOTel() convenience
+
+```typescript
+import { setupOTel } from '@frontmcp/observability';
+
+// Call BEFORE @FrontMcp decorator runs
+setupOTel({
+  serviceName: 'my-server',
+  exporter: 'otlp',
+  endpoint: 'http://localhost:4318',
+});
+```
+
+### Option B: Environment variables
+
+```bash
+OTEL_SERVICE_NAME=my-server \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+node server.js
+```
+
+### Option C: Your own OTel SDK
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+});
+sdk.start();
+```
+
+## Span Hierarchy
+
+Every request produces a span tree:
+
+```
+HTTP Server Span: "POST /mcp"
+  ├── event: stage.traceRequest
+  ├── event: stage.checkAuthorization
+  ├── event: stage.router
+  │
+  ├── RPC Span: "tools/call"
+  │     ├── rpc.system = "mcp"
+  │     ├── mcp.session.id = "a3f8..."
+  │     ├── 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
+  │     │     ├── event: stage.execute.done
+  │     │
+  │     ├── event: stage.validateOutput
+  │     └── event: stage.finalize
+  │
+  └── event: stage.finalize
+```
+
+## Fine-Grained Control
+
+```typescript
+observability: {
+  tracing: {
+    httpSpans: true,           // HTTP request spans
+    executionSpans: true,      // Tool/resource/prompt/agent spans
+    fetchSpans: true,          // Outbound ctx.fetch() spans
+    flowStageEvents: true,     // Flow stage events on execution spans
+    transportSpans: true,      // SSE/HTTP transport spans
+    authSpans: true,           // Auth/session verify spans
+    oauthSpans: true,          // OAuth flow spans
+    elicitationSpans: true,    // Elicitation spans
+    hookSpans: false,          // Individual hook spans (verbose)
+    startupReport: true,       // Emit startup span on first request
+  },
+}
+```
+
+## Local Development
+
+### otel-desktop-viewer
+
+```bash
+brew install ymtdzzz/tap/otel-desktop-viewer
+otel-desktop-viewer  # UI at :8000, OTLP on :4317
+```
+
+### Jaeger
+
+```bash
+docker run -d --name jaeger \
+  -p 16686:16686 -p 4317:4317 -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+# UI at http://localhost:16686
+```
+
+## Examples
+
+| Example                                                                 | Level        | Description                                                                                            |
+| ----------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
+| [`basic-tracing`](../examples/tracing-setup/basic-tracing.md)           | Basic        | Enable auto-tracing and see spans printed to your terminal.                                            |
+| [`production-tracing`](../examples/tracing-setup/production-tracing.md) | Intermediate | Full production observability — traces to OTLP, structured logs to stdout, per-request log collection. |
+
+> See all examples in [`examples/tracing-setup/`](../examples/tracing-setup/)
+
+## Reference
+
+- [Observability Guide](https://docs.agentfront.dev/frontmcp/guides/observability)
+- Related skills: `frontmcp-config`, `frontmcp-deployment`