@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-observability/examples/telemetry-api/agent-nested-tracing.md

@@ -0,0 +1,86 @@
+---
+name: agent-nested-tracing
+reference: telemetry-api
+level: advanced
+description: "Trace an agent's execution lifecycle including its nested tool calls. Every span shares the same trace ID."
+tags: [telemetry, agent, nested, tools, trace-id]
+features:
+  - 'Agent span wraps the entire execution (including LLM loop)'
+  - 'Nested tool calls automatically get their own spans'
+  - 'All spans share the same trace ID for end-to-end visibility'
+  - 'this.telemetry works identically in agents and tools'
+---
+
+# Agent Nested Tracing
+
+Trace an agent's execution lifecycle including its nested tool calls. Every span shares the same trace ID.
+
+## Code
+
+```typescript
+// src/apps/research/agents/research.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { WebSearchTool } from '../tools/web-search.tool';
+import { SummarizerTool } from '../tools/summarizer.tool';
+
+@Agent({
+  name: 'research_agent',
+  description: 'Research a topic using web search and summarization',
+  systemInstructions: 'You are a research assistant. Search for information, then summarize.',
+  tools: [WebSearchTool, SummarizerTool],
+})
+export class ResearchAgent extends AgentContext {
+  async execute(input: { query: string }) {
+    // Event on the "agent research_agent" span
+    this.telemetry.addEvent('research-started', {
+      query: input.query,
+      tools: 'web_search, summarize',
+    });
+
+    // The agent loop calls tools automatically.
+    // Each tool call gets its own span under this agent's span.
+    const result = await super.execute(input);
+
+    this.telemetry.setAttributes({
+      'research.iterations': 3,
+      'research.sources': 5,
+    });
+
+    return result;
+  }
+}
+```
+
+Result in the trace:
+
+```
+RPC Span: "agents/call"
+  └── Agent Span: "agent research_agent"
+        ├── event: research-started (query=..., tools=...)
+        ├── attribute: research.iterations=3
+        │
+        ├── RPC Span: "tools/call"
+        │     └── Tool Span: "tool web_search"
+        │           └── HTTP Client Span: "GET" (search API)
+        │
+        ├── RPC Span: "tools/call"
+        │     └── Tool Span: "tool web_search"
+        │           └── HTTP Client Span: "GET" (another query)
+        │
+        └── RPC Span: "tools/call"
+              └── Tool Span: "tool summarize"
+
+All spans share traceId = "abcdef1234567890..."
+```
+
+## What This Demonstrates
+
+- Agent span wraps the entire execution (including LLM loop)
+- Nested tool calls automatically get their own spans
+- All spans share the same trace ID for end-to-end visibility
+- this.telemetry works identically in agents and tools
+
+## Related
+
+- See `telemetry-api` for the full API reference
+- See `frontmcp-development` for building agents

package/catalog/frontmcp-observability/examples/telemetry-api/plugin-telemetry.md

@@ -0,0 +1,93 @@
+---
+name: plugin-telemetry
+reference: telemetry-api
+level: intermediate
+description: "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."
+tags: [telemetry, plugin, hooks, cache, audit]
+features:
+  - 'Plugin hooks can access toolCtx.telemetry to add events to the active span'
+  - 'Events from plugins appear in the same trace as the tool execution'
+  - 'Graceful degradation when observability is not enabled'
+---
+
+# Plugin Telemetry
+
+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.
+
+## Code
+
+```typescript
+// src/plugins/audit.plugin.ts
+import { DynamicPlugin, Plugin, ToolHook, FlowCtxOf } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'audit',
+  description: 'Audit logging with telemetry integration',
+  providers: [],
+})
+export default class AuditPlugin extends DynamicPlugin<{ enabled: boolean }> {
+  @ToolHook.Will('execute')
+  willExecute(flowCtx: FlowCtxOf<'tools:call-tool'>): void {
+    const toolCtx = flowCtx.state.toolContext;
+    if (!toolCtx) return;
+
+    // Add audit event to the tool's execution span
+    try {
+      toolCtx.telemetry?.addEvent('audit.pre-execution', {
+        tool: flowCtx.state.input?.name ?? 'unknown',
+        user: toolCtx.context?.authInfo?.clientId ?? 'anonymous',
+      });
+    } catch {
+      // telemetry may not be available if observability is disabled
+    }
+  }
+
+  @ToolHook.Did('execute')
+  didExecute(flowCtx: FlowCtxOf<'tools:call-tool'>): void {
+    const toolCtx = flowCtx.state.toolContext;
+    if (!toolCtx) return;
+
+    try {
+      toolCtx.telemetry?.addEvent('audit.post-execution', {
+        success: !flowCtx.state.error,
+      });
+    } catch {
+      // graceful degradation
+    }
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import AuditPlugin from './plugins/audit.plugin';
+
+@FrontMcp({
+  plugins: [AuditPlugin.init({ enabled: true })],
+  observability: true,
+})
+export default class Server {}
+```
+
+Result in the trace:
+
+```
+tool my_tool
+  ├── event: audit.pre-execution (tool=my_tool, user=client-42)
+  ├── event: stage.execute.start
+  ├── ... tool work ...
+  ├── event: stage.execute.done
+  └── event: audit.post-execution (success=true)
+```
+
+## What This Demonstrates
+
+- Plugin hooks can access toolCtx.telemetry to add events to the active span
+- Events from plugins appear in the same trace as the tool execution
+- Graceful degradation when observability is not enabled
+
+## Related
+
+- See `telemetry-api` for all TelemetryAccessor methods
+- See `frontmcp-extensibility` for building plugins

package/catalog/frontmcp-observability/examples/telemetry-api/tool-custom-spans.md

@@ -0,0 +1,72 @@
+---
+name: tool-custom-spans
+reference: telemetry-api
+level: basic
+description: "Create child spans, events, and attributes inside a tool's execute method using this.telemetry."
+tags: [telemetry, tool, spans, events, attributes]
+features:
+  - 'this.telemetry.withSpan() creates auto-managed child spans'
+  - 'this.telemetry.addEvent() adds events to the parent tool span'
+  - 'this.telemetry.setAttributes() adds metadata to the parent tool span'
+  - 'Child spans inherit the trace ID automatically'
+---
+
+# Custom Spans in a Tool
+
+Create child spans, events, and attributes inside a tool's execute method using this.telemetry.
+
+## Code
+
+```typescript
+// src/apps/my-app/tools/weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_weather',
+  description: 'Get weather for a city',
+  inputSchema: { city: z.string() },
+})
+export class GetWeatherTool extends ToolContext<typeof GetWeatherTool> {
+  async execute({ city }: { city: string }) {
+    // Event on the "tool get_weather" span
+    this.telemetry.addEvent('request-received', { city });
+
+    // Child span for the API call
+    const weather = await this.telemetry.withSpan('fetch-weather-api', async (span) => {
+      span.setAttribute('api.city', city);
+
+      const response = await this.fetch(`https://api.weatherapi.com/v1/current.json?q=${city}`);
+
+      span.setAttribute('api.status', response.status);
+      span.addEvent('response-received');
+
+      return response.json();
+    });
+
+    // Attributes on the tool span (visible in trace backend)
+    this.telemetry.setAttributes({
+      'weather.temp_c': weather.current.temp_c,
+      'weather.condition': weather.current.condition.text,
+    });
+
+    return {
+      city,
+      temperature: weather.current.temp_c,
+      condition: weather.current.condition.text,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- this.telemetry.withSpan() creates auto-managed child spans
+- this.telemetry.addEvent() adds events to the parent tool span
+- this.telemetry.setAttributes() adds metadata to the parent tool span
+- Child spans inherit the trace ID automatically
+
+## Related
+
+- See `telemetry-api` for all available methods
+- See `testing-observability` for testing custom spans

package/catalog/frontmcp-observability/examples/testing-observability/test-custom-spans.md

@@ -0,0 +1,90 @@
+---
+name: test-custom-spans
+reference: testing-observability
+level: basic
+description: 'Verify that your tool creates the expected child spans with correct attributes.'
+tags: [testing, spans, assertions, jest, basic]
+features:
+  - 'createTestTracer() provides isolated OTel setup (no global pollution)'
+  - 'assertSpanExists() throws helpful errors when spans are missing'
+  - 'assertSpanAttribute() verifies span attributes'
+  - 'findSpansByAttribute() queries spans by attribute value'
+---
+
+# Test Custom Spans
+
+Verify that your tool creates the expected child spans with correct attributes.
+
+## Code
+
+```typescript
+// src/apps/my-app/tools/__tests__/weather.tool.spec.ts
+import { SpanStatusCode } from '@opentelemetry/api';
+import {
+  createTestTracer,
+  getFinishedSpans,
+  assertSpanExists,
+  assertSpanAttribute,
+  findSpansByAttribute,
+} from '@frontmcp/observability';
+
+describe('GetWeatherTool', () => {
+  const { tracer, exporter, cleanup } = createTestTracer();
+
+  afterEach(() => {
+    exporter.reset();
+  });
+
+  afterAll(async () => {
+    await cleanup();
+  });
+
+  it('should create a fetch-weather-api child span', async () => {
+    // ... set up and invoke tool ...
+    // (the tool uses this.telemetry.withSpan('fetch-weather-api', ...))
+
+    const spans = getFinishedSpans(exporter);
+
+    // Verify span exists
+    const fetchSpan = assertSpanExists(spans, 'fetch-weather-api');
+
+    // Verify attributes
+    assertSpanAttribute(fetchSpan, 'api.city', 'London');
+    assertSpanAttribute(fetchSpan, 'api.status', 200);
+
+    // Verify it completed successfully
+    expect(fetchSpan.status.code).toBe(SpanStatusCode.OK);
+  });
+
+  it('should record error when API fails', async () => {
+    // ... invoke tool with failing API ...
+
+    const spans = getFinishedSpans(exporter);
+    const fetchSpan = assertSpanExists(spans, 'fetch-weather-api');
+
+    expect(fetchSpan.status.code).toBe(SpanStatusCode.ERROR);
+    expect(fetchSpan.events.some((e) => e.name === 'exception')).toBe(true);
+  });
+
+  it('should find all tool spans', async () => {
+    // ... invoke multiple tools ...
+
+    const spans = getFinishedSpans(exporter);
+    const toolSpans = findSpansByAttribute(spans, 'mcp.component.type', 'tool');
+
+    expect(toolSpans.length).toBeGreaterThan(0);
+  });
+});
+```
+
+## What This Demonstrates
+
+- createTestTracer() provides isolated OTel setup (no global pollution)
+- assertSpanExists() throws helpful errors when spans are missing
+- assertSpanAttribute() verifies span attributes
+- findSpansByAttribute() queries spans by attribute value
+
+## Related
+
+- See `testing-observability` for log entry testing
+- See `frontmcp-testing` for general testing patterns

package/catalog/frontmcp-observability/examples/testing-observability/test-log-correlation.md

@@ -0,0 +1,104 @@
+---
+name: test-log-correlation
+reference: testing-observability
+level: intermediate
+description: 'Verify that structured log entries include trace context fields for correlation with spans.'
+tags: [testing, logging, correlation, trace-id, intermediate]
+features:
+  - 'CallbackSink captures log entries for test assertions'
+  - 'StructuredLogTransport with mock context accessor provides trace fields'
+  - 'Verifying trace_id, span_id, request_id are present'
+  - 'Testing field redaction behavior'
+---
+
+# Test Log Correlation
+
+Verify that structured log entries include trace context fields for correlation with spans.
+
+## Code
+
+```typescript
+// src/__tests__/log-correlation.spec.ts
+import { StructuredLogTransport, CallbackSink } from '@frontmcp/observability';
+import type { StructuredLogEntry } from '@frontmcp/observability';
+
+describe('Log correlation', () => {
+  it('should include trace_id and request_id in log entries', () => {
+    const entries: StructuredLogEntry[] = [];
+    const sink = new CallbackSink((e) => entries.push(e));
+
+    const transport = new StructuredLogTransport([sink], {}, () => ({
+      requestId: 'req-test-001',
+      traceContext: {
+        traceId: 'a'.repeat(32),
+        parentId: 'b'.repeat(16),
+        traceFlags: 1,
+      },
+      sessionIdHash: 'hash12345678',
+      scopeId: 'test-scope',
+      flowName: 'tools:call-tool',
+      elapsed: 100,
+    }));
+
+    transport.log({
+      level: 2,
+      levelName: 'info',
+      message: 'tool executed',
+      args: [{ toolName: 'get_weather', duration: 142 }],
+      timestamp: new Date(),
+      prefix: 'MyTool',
+    });
+
+    expect(entries).toHaveLength(1);
+    const entry = entries[0];
+
+    // Trace correlation
+    expect(entry.trace_id).toBe('a'.repeat(32));
+    expect(entry.span_id).toBe('b'.repeat(16));
+    expect(entry.request_id).toBe('req-test-001');
+    expect(entry.session_id_hash).toBe('hash12345678');
+    expect(entry.scope_id).toBe('test-scope');
+    expect(entry.flow_name).toBe('tools:call-tool');
+    expect(entry.elapsed_ms).toBe(100);
+
+    // Structured attributes
+    expect(entry.attributes).toEqual({
+      toolName: 'get_weather',
+      duration: 142,
+    });
+  });
+
+  it('should redact sensitive fields', () => {
+    const entries: StructuredLogEntry[] = [];
+    const sink = new CallbackSink((e) => entries.push(e));
+    const transport = new StructuredLogTransport([sink], { redactFields: ['password', 'apiKey'] });
+
+    transport.log({
+      level: 2,
+      levelName: 'info',
+      message: 'auth attempt',
+      args: [{ user: 'alice', password: 'secret', apiKey: 'sk-123' }],
+      timestamp: new Date(),
+      prefix: '',
+    });
+
+    expect(entries[0].attributes).toEqual({
+      user: 'alice',
+      password: '[REDACTED]',
+      apiKey: '[REDACTED]',
+    });
+  });
+});
+```
+
+## What This Demonstrates
+
+- CallbackSink captures log entries for test assertions
+- StructuredLogTransport with mock context accessor provides trace fields
+- Verifying trace_id, span_id, request_id are present
+- Testing field redaction behavior
+
+## Related
+
+- See `testing-observability` for span testing patterns
+- See `structured-logging` for sink configuration

package/catalog/frontmcp-observability/examples/tracing-setup/basic-tracing.md

@@ -0,0 +1,82 @@
+---
+name: basic-tracing
+reference: tracing-setup
+level: basic
+description: 'Enable auto-tracing and see spans printed to your terminal.'
+tags: [tracing, setup, console, basic]
+features:
+  - 'Zero-config tracing via observability: true'
+  - 'Console exporter for local development'
+  - 'Single trace ID shared across all spans in a request'
+---
+
+# Basic Tracing Setup
+
+Enable auto-tracing and see spans printed to your terminal.
+
+## Code
+
+```typescript
+// src/setup-otel.ts
+import { setupOTel } from '@frontmcp/observability';
+
+// Call BEFORE @FrontMcp runs
+setupOTel({ serviceName: 'my-server', exporter: 'console' });
+```
+
+```typescript
+// src/server.ts
+import './setup-otel'; // Must be first import
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './apps/my-app';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  observability: true,
+})
+export default class Server {}
+```
+
+```typescript
+// src/apps/my-app/tools/hello.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'hello',
+  description: 'Say hello',
+  inputSchema: { name: z.string() },
+})
+export class HelloTool extends ToolContext<typeof HelloTool> {
+  async execute({ name }: { name: string }) {
+    return { greeting: `Hello, ${name}!` };
+  }
+}
+```
+
+When you call `hello` via an MCP client, you'll see spans in the console:
+
+```
+{
+  traceId: 'abcdef1234567890abcdef1234567890',
+  name: 'tools/call',
+  attributes: { 'rpc.system': 'mcp', 'mcp.method.name': 'tools/call' }
+}
+{
+  traceId: 'abcdef1234567890abcdef1234567890',
+  parentId: '...',
+  name: 'tool hello',
+  attributes: { 'mcp.component.type': 'tool', 'mcp.component.key': 'tool:hello' }
+}
+```
+
+## What This Demonstrates
+
+- Zero-config tracing via observability: true
+- Console exporter for local development
+- Single trace ID shared across all spans in a request
+
+## Related
+
+- See `tracing-setup` for OTLP and production configuration

package/catalog/frontmcp-observability/examples/tracing-setup/production-tracing.md

@@ -0,0 +1,73 @@
+---
+name: production-tracing
+reference: tracing-setup
+level: intermediate
+description: 'Full production observability — traces to OTLP, structured logs to stdout, per-request log collection.'
+tags: [tracing, production, otlp, logging, request-logs]
+features:
+  - 'OTLP exporter with env var configuration'
+  - 'Structured logging with sensitive field redaction'
+  - 'Request log collection with error alerting'
+  - 'Full tracing across all SDK flows'
+---
+
+# Production Tracing Setup
+
+Full production observability — traces to OTLP, structured logs to stdout, per-request log collection.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { setupOTel } from '@frontmcp/observability';
+import { MyApp } from './apps/my-app';
+
+setupOTel({
+  serviceName: process.env.OTEL_SERVICE_NAME ?? 'my-server',
+  exporter: 'otlp',
+  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://collector:4318',
+  serviceVersion: '1.0.0',
+});
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  observability: {
+    tracing: {
+      httpSpans: true,
+      executionSpans: true,
+      fetchSpans: true,
+      flowStageEvents: true,
+      transportSpans: true,
+      authSpans: true,
+    },
+    logging: {
+      sinks: [{ type: 'stdout' }],
+      redactFields: ['password', 'token', 'secret', 'authorization'],
+      includeStacks: false,
+    },
+    requestLogs: {
+      maxEntries: 500,
+      onRequestComplete: async (log) => {
+        if (log.status === 'error') {
+          console.error('Request failed:', JSON.stringify(log));
+        }
+      },
+    },
+  },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- OTLP exporter with env var configuration
+- Structured logging with sensitive field redaction
+- Request log collection with error alerting
+- Full tracing across all SDK flows
+
+## Related
+
+- See `tracing-setup` for all configuration options
+- See `vendor-integrations` for Coralogix/Datadog/Logz.io setup

package/catalog/frontmcp-observability/examples/vendor-integrations/coralogix-setup.md

@@ -0,0 +1,74 @@
+---
+name: coralogix-setup
+reference: vendor-integrations
+level: intermediate
+description: 'Send both traces and structured logs to Coralogix. Logs include trace_id so Coralogix links them to traces automatically.'
+tags: [coralogix, otlp, vendor, integration, production]
+features:
+  - 'Traces and logs both sent to Coralogix via OTLP'
+  - 'Automatic trace_id correlation — click a trace, see its logs'
+  - 'Environment variable configuration for production'
+---
+
+# Coralogix Setup
+
+Send both traces and structured logs to Coralogix. Logs include trace_id so Coralogix links them to traces automatically.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { setupOTel } from '@frontmcp/observability';
+
+// Traces → Coralogix via OTLP
+setupOTel({
+  serviceName: 'my-mcp-server',
+  exporter: 'otlp',
+  endpoint: 'https://ingress.coralogix.com:443', // EU: eu2.coralogix.com
+  serviceVersion: '1.0.0',
+});
+
+@FrontMcp({
+  info: { name: 'my-mcp-server', version: '1.0.0' },
+  apps: [MyApp],
+  observability: {
+    tracing: true,
+    logging: {
+      sinks: [
+        // Logs → Coralogix via OTLP
+        {
+          type: 'otlp',
+          endpoint: 'https://ingress.coralogix.com:443',
+          headers: { Authorization: `Bearer ${process.env.CX_PRIVATE_KEY}` },
+          serviceName: 'my-mcp-server',
+        },
+        // Also stdout for Docker log collection
+        { type: 'stdout' },
+      ],
+      redactFields: ['password', 'token', 'secret'],
+    },
+    requestLogs: true,
+  },
+})
+export default class Server {}
+```
+
+Environment variables alternative:
+
+```bash
+OTEL_SERVICE_NAME=my-mcp-server
+OTEL_EXPORTER_OTLP_ENDPOINT=https://ingress.coralogix.com:443
+CX_PRIVATE_KEY=your-coralogix-private-key
+```
+
+## What This Demonstrates
+
+- Traces and logs both sent to Coralogix via OTLP
+- Automatic trace_id correlation — click a trace, see its logs
+- Environment variable configuration for production
+
+## Related
+
+- See `vendor-integrations` for Datadog, Logz.io, Grafana setup
+- See `tracing-setup` for trace configuration options