@frontmcp/observability 1.5.7 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +106 -0
  2. package/esm/package.json +3 -3
  3. package/package.json +3 -3
package/README.md ADDED
@@ -0,0 +1,106 @@
1
+ # @frontmcp/observability
2
+
3
+ OpenTelemetry instrumentation, structured JSON logging, and Prometheus metrics
4
+ for FrontMCP servers.
5
+
6
+ [![NPM](https://img.shields.io/npm/v/@frontmcp/observability.svg)](https://www.npmjs.com/package/@frontmcp/observability)
7
+
8
+ ## What you get
9
+
10
+ Install the plugin and every MCP request produces a trace span, a structured log
11
+ line, and counters — without touching your tool code.
12
+
13
+ - **Traces** — W3C trace context propagated across the request pipeline, with
14
+ MCP-specific span attributes (tool name, session, transport, RPC method).
15
+ - **Logs** — one structured JSON object per request; ready for Datadog, Loki,
16
+ CloudWatch, or anything that reads JSON from stdout.
17
+ - **Metrics** — counters and gauges exposed in Prometheus or JSON format.
18
+ - **Process stats** — memory, event-loop lag, and uptime.
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ npm install @frontmcp/observability
24
+ ```
25
+
26
+ ## Usage
27
+
28
+ ```ts
29
+ import { ObservabilityPlugin } from '@frontmcp/observability';
30
+ import { FrontMcp } from '@frontmcp/sdk';
31
+
32
+ @FrontMcp({
33
+ info: { name: 'my-server', version: '1.0.0' },
34
+ apps: [MyApp],
35
+ plugins: [ObservabilityPlugin],
36
+ })
37
+ class Server {}
38
+ ```
39
+
40
+ ### Configure
41
+
42
+ ```ts
43
+ plugins: [
44
+ ObservabilityPlugin.configure({
45
+ logging: { level: 'info', includeRequestBody: false },
46
+ otel: { serviceName: 'my-server', endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT },
47
+ }),
48
+ ];
49
+ ```
50
+
51
+ <!-- prettier-ignore -->
52
+ > Do not log request bodies in production unless you have reviewed them for PII —
53
+ > tool arguments frequently carry user data.
54
+
55
+ ## Exposing metrics
56
+
57
+ ```ts
58
+ import { PROMETHEUS_CONTENT_TYPE, renderPrometheusExposition } from '@frontmcp/observability';
59
+
60
+ http: {
61
+ routes: [
62
+ {
63
+ method: 'GET',
64
+ path: '/metrics',
65
+ handler: (_req, res) => {
66
+ res.setHeader('Content-Type', PROMETHEUS_CONTENT_TYPE);
67
+ res.status(200).send(renderPrometheusExposition());
68
+ },
69
+ },
70
+ ];
71
+ }
72
+ ```
73
+
74
+ `renderJsonExposition()` returns the same data as JSON when you would rather
75
+ scrape structured output.
76
+
77
+ <!-- prettier-ignore -->
78
+ > `/metrics` is unauthenticated in the snippet above. Bind it to an internal
79
+ > interface, or put it behind auth, before exposing the server publicly.
80
+
81
+ ## Key exports
82
+
83
+ | Export | Purpose |
84
+ | ---------------------------------------------------- | --------------------------------------------------- |
85
+ | `ObservabilityPlugin` | The plugin — add it to `plugins: []` |
86
+ | `setupOTel` | Wire an OTel SDK yourself instead of via the plugin |
87
+ | `FrontMcpPropagator` | W3C trace-context propagator for FrontMCP contexts |
88
+ | `McpAttributes`, `RpcAttributes`, `HttpAttributes` | Semantic-convention attribute keys |
89
+ | `renderPrometheusExposition`, `renderJsonExposition` | Metrics rendering |
90
+ | `ProcessStatsCollector` | Memory / event-loop / uptime sampling |
91
+ | `reportStartup` | Emit a structured boot record |
92
+
93
+ ## Trace context over MCP
94
+
95
+ Protocol revision `2026-07-28` carries OpenTelemetry context in the request
96
+ `_meta` (`traceparent`, `tracestate`, `baggage`) per SEP-414, and FrontMCP echoes
97
+ it back on the result. A client can therefore stitch its span to the server's
98
+ without an out-of-band correlation id — see the
99
+ [protocol versions guide](https://docs.agentfront.dev/frontmcp/fundamentals/protocol-versions).
100
+
101
+ Full guide: [Observability](https://docs.agentfront.dev/frontmcp/features/observability)
102
+ &middot; [Metrics](https://docs.agentfront.dev/frontmcp/deployment/metrics)
103
+
104
+ ## License
105
+
106
+ Apache-2.0
package/esm/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@frontmcp/observability",
3
- "version": "1.5.7",
3
+ "version": "1.6.0",
4
4
  "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "license": "Apache-2.0",
@@ -51,8 +51,8 @@
51
51
  "@opentelemetry/api": "^1.9.0"
52
52
  },
53
53
  "peerDependencies": {
54
- "@frontmcp/sdk": "1.5.7",
55
- "@frontmcp/utils": "1.5.7",
54
+ "@frontmcp/sdk": "1.6.0",
55
+ "@frontmcp/utils": "1.6.0",
56
56
  "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
57
57
  "@opentelemetry/sdk-node": "^0.219.0",
58
58
  "@opentelemetry/sdk-trace-base": "^2.8.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@frontmcp/observability",
3
- "version": "1.5.7",
3
+ "version": "1.6.0",
4
4
  "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "license": "Apache-2.0",
@@ -51,8 +51,8 @@
51
51
  "@opentelemetry/api": "^1.9.0"
52
52
  },
53
53
  "peerDependencies": {
54
- "@frontmcp/sdk": "1.5.7",
55
- "@frontmcp/utils": "1.5.7",
54
+ "@frontmcp/sdk": "1.6.0",
55
+ "@frontmcp/utils": "1.6.0",
56
56
  "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
57
57
  "@opentelemetry/sdk-node": "^0.219.0",
58
58
  "@opentelemetry/sdk-trace-base": "^2.8.0",