Dokumentation

MCP Fusion/Operate and integrate/Observability

Observability

Frag die KI über Vinkius

Untersuchen Sie jeden MCP-Aufruf, ohne stdio zu verunreinigen: DebugObserver-Ereignisse, TelemetrySink-Datensätze, Pipeline-Tracing, Token-Ökonomie und der Out-of-Band-Inspector.

Ein MCP-Server hat ein besonderes Observability-Problem: stdio gehört zum Protokoll. Eine Logzeile an der falschen Stelle beschädigt den Transport. MCP Fusion hält Diagnosen auf getrennten Kanälen, sodass Sie einen aktiven Konnektor untersuchen können, ohne die Agentenantwort zu verändern.

Drei Sinks, drei Aufgaben

typescript
registry.enableDebug((event) => {
  console.error('[fusion]', event.type, event);
});

registry.enableTelemetry((event) => telemetry.write(event));
registry.enableTracing(tracer);
SinkJobWhen to use
DebugObserverlokaler, menschenlesbarer Ereignisstrommcpfusion dev und mcpfusion inspect
TelemetrySinkstrukturierte Sicherheits-, Kosten- und Lifecycle-EreignisseProduktions-Dashboards und Alerts
MCPFusionTracerSpans mit Stufendauer und semantischen FehlerattributenOpenTelemetry-Backends

Alle drei bleiben bis zur Konfiguration inaktiv. Wenn kein Sink vorhanden ist, wird dem Request-Pfad kein Wrapper, Timer oder Speicheraufwand hinzugefügt.

DebugObserver-Ereignisse

Der Observer empfängt die Pipeline in ihrem Ablauf: Eingang der Anfrage, Toolauflösung, Validierung, Middleware, Handler, Presenter, Antwort und Fehler. Sicherheitsmiddleware ergänzt Ereignisse wie security.firewall, security.rateLimit und security.audit; die Sandbox emittiert sandbox.exec; FSM-Änderungen emittieren fsm.transition. Das Payload enthält Tool-/Aktionsidentität, Dauer, Ergebnisstatus und relevante sichere Metadaten, niemals ein Rohgeheimnis.

Der Inspector verwendet denselben Stream über einen Out-of-Band-Shadow-Socket. Er schreibt nie nach stdout, sodass ein stdio-Client protokollsauber bleibt, während das Terminal Aufrufe, Latenz, Fehler, aktive Tools und Presenter-Ausgabe anzeigt.

bash
mcpfusion inspect

Den Request tracen

Ein Tracer bildet dieselben Stufen als Spans ab: route, parse, validate, middleware, execute, Present und serialize. Attribute identifizieren Tool und Aktion, ob sie destruktiv oder schreibgeschützt waren, sowie die semantische Fehlerklasse. Das Framework trennt einen Agentenfehler von einem Upstream-Fehler und einem Vinkius-seitigen Fehler. Dadurch wird ein Zuverlässigkeitsdashboard statt eines einzelnen roten Zählers handlungsfähig.

Verbinden Sie den Tracer an der Grenze mit Ihrem OpenTelemetry-Exporter. MCP Fusion besitzt das Span-Vokabular; Ihr Exporter bestimmt das Ziel.

Telemetrie und Kosten

Der Telemetrie-Collector erfasst die vom Governance-System benötigten Metadaten: Redaction-Pfade, Firewall-Entscheidungen, Rate-Limit-Entscheidungen, Auditstatus, Tokenprofil, Sandbox-Ergebnis und Zustandsübergänge. Token Economics ergänzt geschätzte Eingabe- und Ausgabeinflation, Overhead-Verhältnis und Risikoklassifizierung. Es sind Schätzungen auf Basis von JSON-förmigem Text, keine Abrechnungsangaben des Providers; entscheidend ist der Vergleich einer Änderung mit dem vorherigen Vertrag.

Sicherheit der Observability

Audit-Ereignisse hashen Argumente mit SHA-256, wenn hashArgs aktiviert ist. Das Framework sendet Ereignisse an Ihren Sink, behauptet aber nicht, dass der OSS-Sink eine manipulationssichere Ed25519-Kette bildet. Auf Vinkius Cloud ergänzt der gehostete Konnektor die signierte Auditspur und die Aufbewahrung in der Konsole. Diese Grenze ist bei einer Compliance-Prüfung wichtig.

Protokollieren Sie niemals ctx, Credentials, rohe Authorization-Header oder vollständige Tool-Argumente. Beobachten Sie Identitätsklasse, Tenant-Hash, Toolname, Dauer, Status und einen Digest. Die integrierten Ereignisse folgen diesem Prinzip, doch ein eigener Sink kann weiterhin Inhalte preisgeben, die Sie ihm übergeben.

Verdrahtung für die Produktion

typescript
const observer = createDebugObserver({
  sink: (event) => process.stderr.write(JSON.stringify(event) + '\n'),
});

await registry.attachToServer(server, {
  debug: observer,
  telemetry: (event) => metrics.record(event),
  tracing: otelTracer,
});

Binden Sie dies beim Start an, nicht innerhalb eines Handlers. Die Registry propagiert Sinks an bestehende Builder und später registrierte Builder. Wenn Tracing und Debug gleichzeitig aktiv sind, gibt das Framework dem Tracing auf dem überlappenden Diagnosepfad Vorrang.

Nächste Schritte