mcard-js
Version:
MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers
144 lines • 4.21 kB
TypeScript
/**
* OpenTelemetrySidecar - Universal Observability for PTR Engine
*
* This module provides OpenTelemetry-based observability for the PTR runtime,
* enabling distributed tracing, metrics, and logging across all REPL phases.
*
* REPL Phase Instrumentation:
* - prep: Log V_pre validation status, trace artifact loading
* - exec: Metrics (CPU, memory, duration), trace execution path
* - post: Log verification results, trace VCard generation
* - await: Event for handle_history recording
*
* Works in both Node.js and Browser environments:
* - Node.js: Uses @opentelemetry/sdk-node
* - Browser: Uses FaroSidecar (Grafana Faro)
*
* See Also:
* - CLM_MCard_REPL_Implementation.md §11: Grafana LGTM Integration
* - PTR_MCard_CLM_Recent_Developments_Jan2026.md §6.2: Universal Observability
*/
/**
* REPL Phase enum for instrumentation
*/
export declare enum REPLPhase {
PREP = "prep",
EXEC = "exec",
POST = "post",
AWAIT = "await"
}
/**
* Configuration for the OpenTelemetry Sidecar
*/
export interface OpenTelemetryConfig {
/** OTLP endpoint (e.g., "http://localhost:4317") */
endpoint: string;
/** Service name for traces/metrics */
serviceName: string;
/** Service version */
serviceVersion: string;
/** Optional namespace prefix */
namespace?: string;
/** Enable tracing (default: true) */
enableTracing?: boolean;
/** Enable metrics (default: true) */
enableMetrics?: boolean;
}
/**
* Span context for phase tracing
*/
export interface PhaseSpanContext {
phase: REPLPhase;
pcardHash?: string;
targetHash?: string;
attributes?: Record<string, string | number | boolean>;
startTime: number;
}
/**
* OpenTelemetrySidecar - Universal observability for PTR
*
* Provides instrumentation hooks for each REPL phase:
* - prep: Artifact loading, V_pre validation
* - exec: CLM execution, sandbox runtime
* - post: Balanced verification, VCard generation
* - await: Handle history recording, state transition
*
* Usage:
* const sidecar = OpenTelemetrySidecar.getInstance();
* sidecar.initialize({
* endpoint: "http://localhost:4317",
* serviceName: "ptr-runtime",
* serviceVersion: "1.0.0"
* });
*
* const span = sidecar.startPhase(REPLPhase.PREP, { pcardHash: "abc123" });
* // ... do prep work
* sidecar.endPhase(span);
*/
export declare class OpenTelemetrySidecar {
private static instance;
private _initialized;
private _config;
private _isNode;
private _phaseDurations;
private _phaseCounts;
private _errorCounts;
private constructor();
/**
* Get the singleton instance
*/
static getInstance(): OpenTelemetrySidecar;
/**
* Initialize the OpenTelemetry SDK
*/
initialize(config: OpenTelemetryConfig): boolean;
/**
* Start tracing a REPL phase
*/
startPhase(phase: REPLPhase, options?: {
pcardHash?: string;
targetHash?: string;
attributes?: Record<string, string | number | boolean>;
}): PhaseSpanContext;
/**
* End tracing a REPL phase
*/
endPhase(context: PhaseSpanContext, success?: boolean, attributes?: Record<string, string | number | boolean>): void;
/**
* Log an event within a REPL phase
*/
logEvent(phase: REPLPhase, eventName: string, attributes?: Record<string, string | number | boolean>): void;
/**
* Record phase duration metric
*/
private _recordPhaseDuration;
/**
* Record phase count metric
*/
private _recordPhaseCount;
/**
* Record error count
*/
private _recordError;
/**
* Get metrics summary
*/
getMetrics(): Record<string, any>;
/**
* Check if initialized
*/
isInitialized(): boolean;
/**
* Check if running in Node.js
*/
isNode(): boolean;
}
/**
* Helper function to create a traced phase execution
*/
export declare function tracePhase<T>(phase: REPLPhase, fn: () => Promise<T>, options?: {
pcardHash?: string;
targetHash?: string;
attributes?: Record<string, string | number | boolean>;
}): Promise<T>;
//# sourceMappingURL=OpenTelemetrySidecar.d.ts.map