apcore-js 0.5.0 → 0.6.0

package/dist/observability/context-logger.js

@@ -0,0 +1,151 @@
+/**
+ * Structured logging: ContextLogger and ObsLoggingMiddleware.
+ */
+import { Middleware } from '../middleware/base.js';
+const LEVELS = {
+    trace: 0,
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    fatal: 50,
+};
+const REDACTED = '***REDACTED***';
+export class ContextLogger {
+    _name;
+    _format;
+    _level;
+    _levelValue;
+    _redactSensitive;
+    _output;
+    _traceId = null;
+    _moduleId = null;
+    _callerId = null;
+    constructor(options) {
+        this._name = options?.name ?? 'apcore';
+        this._format = options?.format ?? 'json';
+        this._level = options?.level ?? 'info';
+        this._levelValue = LEVELS[this._level] ?? 20;
+        this._redactSensitive = options?.redactSensitive ?? true;
+        // Default output uses console.error for universal compatibility (Node.js + browser)
+        this._output = options?.output ?? { write: (s) => console.error(s) };
+    }
+    static fromContext(context, name, options) {
+        const logger = new ContextLogger({ name, ...options });
+        logger._traceId = context.traceId;
+        logger._moduleId = context.callChain.length > 0 ? context.callChain[context.callChain.length - 1] : null;
+        logger._callerId = context.callerId;
+        return logger;
+    }
+    _emit(levelName, message, extra) {
+        const levelValue = LEVELS[levelName] ?? 20;
+        if (levelValue < this._levelValue)
+            return;
+        let redactedExtra = extra ?? null;
+        if (extra != null && this._redactSensitive) {
+            redactedExtra = {};
+            for (const [k, v] of Object.entries(extra)) {
+                redactedExtra[k] = k.startsWith('_secret_') ? REDACTED : v;
+            }
+        }
+        const now = new Date();
+        const entry = {
+            timestamp: now.toISOString(),
+            level: levelName,
+            message,
+            trace_id: this._traceId,
+            module_id: this._moduleId,
+            caller_id: this._callerId,
+            logger: this._name,
+            extra: redactedExtra,
+        };
+        if (this._format === 'json') {
+            this._output.write(JSON.stringify(entry) + '\n');
+        }
+        else {
+            const ts = now.toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
+            const lvl = levelName.toUpperCase();
+            const trace = this._traceId ?? 'none';
+            const mod = this._moduleId ?? 'none';
+            let extrasStr = '';
+            if (redactedExtra) {
+                extrasStr = ' ' + Object.entries(redactedExtra).map(([k, v]) => `${k}=${v}`).join(' ');
+            }
+            this._output.write(`${ts} [${lvl}] [trace=${trace}] [module=${mod}] ${message}${extrasStr}\n`);
+        }
+    }
+    trace(message, extra) {
+        this._emit('trace', message, extra);
+    }
+    debug(message, extra) {
+        this._emit('debug', message, extra);
+    }
+    info(message, extra) {
+        this._emit('info', message, extra);
+    }
+    warn(message, extra) {
+        this._emit('warn', message, extra);
+    }
+    error(message, extra) {
+        this._emit('error', message, extra);
+    }
+    fatal(message, extra) {
+        this._emit('fatal', message, extra);
+    }
+}
+export class ObsLoggingMiddleware extends Middleware {
+    _logger;
+    _logInputs;
+    _logOutputs;
+    constructor(options) {
+        super();
+        this._logger = options?.logger ?? new ContextLogger({ name: 'apcore.obs_logging' });
+        this._logInputs = options?.logInputs ?? true;
+        this._logOutputs = options?.logOutputs ?? true;
+    }
+    before(moduleId, inputs, context) {
+        const starts = context.data['_obs_logging_starts'] ?? [];
+        starts.push(performance.now());
+        context.data['_obs_logging_starts'] = starts;
+        const extra = {
+            module_id: moduleId,
+            caller_id: context.callerId,
+        };
+        if (this._logInputs) {
+            extra['inputs'] = context.redactedInputs ?? inputs;
+        }
+        this._logger.info('Module call started', extra);
+        return null;
+    }
+    after(moduleId, _inputs, output, context) {
+        const starts = context.data['_obs_logging_starts'];
+        if (!starts || starts.length === 0)
+            return null;
+        const startTime = starts.pop();
+        const durationMs = performance.now() - startTime;
+        const extra = {
+            module_id: moduleId,
+            duration_ms: durationMs,
+        };
+        if (this._logOutputs) {
+            extra['output'] = output;
+        }
+        this._logger.info('Module call completed', extra);
+        return null;
+    }
+    onError(moduleId, _inputs, error, context) {
+        const starts = context.data['_obs_logging_starts'];
+        if (!starts || starts.length === 0)
+            return null;
+        const startTime = starts.pop();
+        const durationMs = performance.now() - startTime;
+        this._logger.error('Module call failed', {
+            module_id: moduleId,
+            duration_ms: durationMs,
+            error_type: error.constructor.name,
+            error_message: String(error),
+        });
+        return null;
+    }
+}
+//# sourceMappingURL=context-logger.js.map

package/dist/observability/context-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-logger.js","sourceRoot":"","sources":["../../src/observability/context-logger.ts"],"names":[],"mappings":"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"}

package/{src/observability/index.ts → dist/observability/index.d.ts}

@@ -2,3 +2,4 @@ export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from
 export type { Span, SpanExporter } from './tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/F,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,4 @@
+export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from './tracing.js';
+export { MetricsCollector, MetricsMiddleware } from './metrics.js';
+export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-memory metrics collection with Prometheus export.
+ */
+import type { Context } from '../context.js';
+import { Middleware } from '../middleware/base.js';
+export declare class MetricsCollector {
+    static readonly DEFAULT_BUCKETS: number[];
+    private _buckets;
+    private _counters;
+    private _histogramSums;
+    private _histogramCounts;
+    private _histogramBuckets;
+    constructor(buckets?: number[]);
+    increment(name: string, labels: Record<string, string>, amount?: number): void;
+    observe(name: string, labels: Record<string, string>, value: number): void;
+    snapshot(): Record<string, unknown>;
+    reset(): void;
+    exportPrometheus(): string;
+    incrementCalls(moduleId: string, status: string): void;
+    incrementErrors(moduleId: string, errorCode: string): void;
+    observeDuration(moduleId: string, durationSeconds: number): void;
+}
+export declare class MetricsMiddleware extends Middleware {
+    private _collector;
+    constructor(collector: MetricsCollector);
+    before(_moduleId: string, _inputs: Record<string, unknown>, context: Context): null;
+    after(moduleId: string, _inputs: Record<string, unknown>, _output: Record<string, unknown>, context: Context): null;
+    onError(moduleId: string, _inputs: Record<string, unknown>, error: Error, context: Context): null;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAYnD,qBAAa,gBAAgB;IAC3B,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAEvC;IAEF,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,OAAO,CAAC,iBAAiB,CAAkC;gBAE/C,OAAO,CAAC,EAAE,MAAM,EAAE;IAI9B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAE,MAAU,GAAG,IAAI;IAKjF,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAkB1E,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAWnC,KAAK,IAAI,IAAI;IAOb,gBAAgB,IAAI,MAAM;IAsD1B,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAItD,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAI1D,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;CAGjE;AAwBD,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,OAAO,CAAC,UAAU,CAAmB;gBAEzB,SAAS,EAAE,gBAAgB;IAK9B,MAAM,CACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,OAAO,GACf,IAAI;IAOE,KAAK,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,OAAO,GACf,IAAI;IAUE,OAAO,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,GACf,IAAI;CAWR"}

package/dist/observability/metrics.js

@@ -0,0 +1,177 @@
+/**
+ * In-memory metrics collection with Prometheus export.
+ */
+import { ModuleError } from '../errors.js';
+import { Middleware } from '../middleware/base.js';
+const DESCRIPTIONS = {
+    apcore_module_calls_total: 'Total module calls',
+    apcore_module_errors_total: 'Total module errors',
+    apcore_module_duration_seconds: 'Module execution duration',
+};
+function labelsKey(labels) {
+    return Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(',');
+}
+export class MetricsCollector {
+    static DEFAULT_BUCKETS = [
+        0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0,
+    ];
+    _buckets;
+    _counters = new Map();
+    _histogramSums = new Map();
+    _histogramCounts = new Map();
+    _histogramBuckets = new Map();
+    constructor(buckets) {
+        this._buckets = buckets ? [...buckets].sort((a, b) => a - b) : [...MetricsCollector.DEFAULT_BUCKETS];
+    }
+    increment(name, labels, amount = 1) {
+        const key = `${name}|${labelsKey(labels)}`;
+        this._counters.set(key, (this._counters.get(key) ?? 0) + amount);
+    }
+    observe(name, labels, value) {
+        const lk = labelsKey(labels);
+        const key = `${name}|${lk}`;
+        this._histogramSums.set(key, (this._histogramSums.get(key) ?? 0) + value);
+        this._histogramCounts.set(key, (this._histogramCounts.get(key) ?? 0) + 1);
+        for (const b of this._buckets) {
+            if (value <= b) {
+                const bkey = `${name}|${lk}|${b}`;
+                this._histogramBuckets.set(bkey, (this._histogramBuckets.get(bkey) ?? 0) + 1);
+            }
+        }
+        // +Inf bucket
+        const infKey = `${name}|${lk}|Inf`;
+        this._histogramBuckets.set(infKey, (this._histogramBuckets.get(infKey) ?? 0) + 1);
+    }
+    snapshot() {
+        return {
+            counters: Object.fromEntries(this._counters),
+            histograms: {
+                sums: Object.fromEntries(this._histogramSums),
+                counts: Object.fromEntries(this._histogramCounts),
+                buckets: Object.fromEntries(this._histogramBuckets),
+            },
+        };
+    }
+    reset() {
+        this._counters.clear();
+        this._histogramSums.clear();
+        this._histogramCounts.clear();
+        this._histogramBuckets.clear();
+    }
+    exportPrometheus() {
+        const lines = [];
+        const counterNames = new Set();
+        const histNames = new Set();
+        // Counters
+        for (const [compositeKey, value] of [...this._counters.entries()].sort()) {
+            const [name, lk] = compositeKey.split('|', 2);
+            if (!counterNames.has(name)) {
+                const desc = DESCRIPTIONS[name] ?? name;
+                lines.push(`# HELP ${name} ${desc}`);
+                lines.push(`# TYPE ${name} counter`);
+                counterNames.add(name);
+            }
+            const labelsStr = formatLabels(parseLabels(lk));
+            lines.push(`${name}${labelsStr} ${value}`);
+        }
+        // Histograms
+        const histKeys = [...this._histogramSums.keys()].sort();
+        for (const compositeKey of histKeys) {
+            const [name, lk] = compositeKey.split('|', 2);
+            if (!histNames.has(name)) {
+                const desc = DESCRIPTIONS[name] ?? name;
+                lines.push(`# HELP ${name} ${desc}`);
+                lines.push(`# TYPE ${name} histogram`);
+                histNames.add(name);
+            }
+            const labelsDict = parseLabels(lk);
+            const labelsStr = formatLabels(labelsDict);
+            for (const b of this._buckets) {
+                const bkey = `${name}|${lk}|${b}`;
+                const count = this._histogramBuckets.get(bkey) ?? 0;
+                const leStr = String(b);
+                const leLabels = { ...labelsDict, le: leStr };
+                lines.push(`${name}_bucket${formatLabels(leLabels)} ${count}`);
+            }
+            const infKey = `${name}|${lk}|Inf`;
+            const infCount = this._histogramBuckets.get(infKey) ?? 0;
+            const infLabels = { ...labelsDict, le: '+Inf' };
+            lines.push(`${name}_bucket${formatLabels(infLabels)} ${infCount}`);
+            const sumVal = this._histogramSums.get(compositeKey) ?? 0;
+            const countVal = this._histogramCounts.get(compositeKey) ?? 0;
+            lines.push(`${name}_sum${labelsStr} ${sumVal}`);
+            lines.push(`${name}_count${labelsStr} ${countVal}`);
+        }
+        return lines.length > 0 ? lines.join('\n') + '\n' : '';
+    }
+    incrementCalls(moduleId, status) {
+        this.increment('apcore_module_calls_total', { module_id: moduleId, status });
+    }
+    incrementErrors(moduleId, errorCode) {
+        this.increment('apcore_module_errors_total', { module_id: moduleId, error_code: errorCode });
+    }
+    observeDuration(moduleId, durationSeconds) {
+        this.observe('apcore_module_duration_seconds', { module_id: moduleId }, durationSeconds);
+    }
+}
+function parseLabels(lk) {
+    if (!lk)
+        return {};
+    const result = {};
+    for (const pair of lk.split(',')) {
+        const [k, v] = pair.split('=', 2);
+        if (k)
+            result[k] = v ?? '';
+    }
+    return result;
+}
+function formatLabels(labels) {
+    const entries = Object.entries(labels);
+    if (entries.length === 0)
+        return '';
+    const sorted = entries.sort(([a], [b]) => {
+        if (a === 'le')
+            return 1;
+        if (b === 'le')
+            return -1;
+        return a.localeCompare(b);
+    });
+    const pairs = sorted.map(([k, v]) => `${k}="${v}"`).join(',');
+    return `{${pairs}}`;
+}
+export class MetricsMiddleware extends Middleware {
+    _collector;
+    constructor(collector) {
+        super();
+        this._collector = collector;
+    }
+    before(_moduleId, _inputs, context) {
+        const starts = context.data['_metrics_starts'] ?? [];
+        starts.push(performance.now());
+        context.data['_metrics_starts'] = starts;
+        return null;
+    }
+    after(moduleId, _inputs, _output, context) {
+        const starts = context.data['_metrics_starts'];
+        if (!starts || starts.length === 0)
+            return null;
+        const startTime = starts.pop();
+        const durationS = (performance.now() - startTime) / 1000;
+        this._collector.incrementCalls(moduleId, 'success');
+        this._collector.observeDuration(moduleId, durationS);
+        return null;
+    }
+    onError(moduleId, _inputs, error, context) {
+        const starts = context.data['_metrics_starts'];
+        if (!starts || starts.length === 0)
+            return null;
+        const startTime = starts.pop();
+        const durationS = (performance.now() - startTime) / 1000;
+        const errorCode = error instanceof ModuleError ? error.code : error.constructor.name;
+        this._collector.incrementCalls(moduleId, 'error');
+        this._collector.incrementErrors(moduleId, errorCode);
+        this._collector.observeDuration(moduleId, durationS);
+        return null;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"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"}

package/dist/observability/tracing.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tracing system: Span, SpanExporter implementations, and TracingMiddleware.
+ */
+import type { Context } from '../context.js';
+import { Middleware } from '../middleware/base.js';
+export interface Span {
+    traceId: string;
+    name: string;
+    startTime: number;
+    spanId: string;
+    parentSpanId: string | null;
+    attributes: Record<string, unknown>;
+    endTime: number | null;
+    status: string;
+    events: Array<Record<string, unknown>>;
+}
+export declare function createSpan(options: {
+    traceId: string;
+    name: string;
+    startTime: number;
+    spanId?: string;
+    parentSpanId?: string | null;
+    attributes?: Record<string, unknown>;
+}): Span;
+export interface SpanExporter {
+    export(span: Span): void;
+}
+export declare class StdoutExporter implements SpanExporter {
+    export(span: Span): void;
+}
+export declare class InMemoryExporter implements SpanExporter {
+    private _spans;
+    private _maxSpans;
+    constructor(maxSpans?: number);
+    export(span: Span): void;
+    getSpans(): Span[];
+    clear(): void;
+}
+export declare class OTLPExporter implements SpanExporter {
+    private _endpoint;
+    private _serviceName;
+    private _headers;
+    constructor(options?: {
+        endpoint?: string;
+        serviceName?: string;
+        headers?: Record<string, string>;
+    });
+    export(span: Span): void;
+}
+export declare class TracingMiddleware extends Middleware {
+    private _exporter;
+    private _samplingRate;
+    private _samplingStrategy;
+    constructor(exporter: SpanExporter, samplingRate?: number, samplingStrategy?: string);
+    /** Replace the span exporter used by this middleware. */
+    setExporter(exporter: SpanExporter): void;
+    private _shouldSample;
+    before(moduleId: string, _inputs: Record<string, unknown>, context: Context): null;
+    after(moduleId: string, _inputs: Record<string, unknown>, _output: Record<string, unknown>, context: Context): null;
+    onError(moduleId: string, _inputs: Record<string, unknown>, error: Error, context: Context): null;
+}
+//# sourceMappingURL=tracing.d.ts.map

package/dist/observability/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/observability/tracing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGnD,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,GAAG,IAAI,CAYP;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CAC1B;AAED,qBAAa,cAAe,YAAW,YAAY;IACjD,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;CAIzB;AAED,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAAS;gBAEd,QAAQ,GAAE,MAAe;IAIrC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAQxB,QAAQ,IAAI,IAAI,EAAE;IAIlB,KAAK,IAAI,IAAI;CAGd;AAED,qBAAa,YAAa,YAAW,YAAY;IAC/C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAyB;gBAE7B,OAAO,CAAC,EAAE;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC;IAMD,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;CAuCzB;AAID,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAS;gBAGhC,QAAQ,EAAE,YAAY,EACtB,YAAY,GAAE,MAAY,EAC1B,gBAAgB,GAAE,MAAe;IAcnC,yDAAyD;IACzD,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAOzC,OAAO,CAAC,aAAa;IAiBZ,MAAM,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,OAAO,GACf,IAAI;IAsBE,KAAK,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,OAAO,GACf,IAAI;IAgBE,OAAO,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,GACf,IAAI;CAkBR"}

package/dist/observability/tracing.js

@@ -0,0 +1,184 @@
+/**
+ * Tracing system: Span, SpanExporter implementations, and TracingMiddleware.
+ */
+import { Middleware } from '../middleware/base.js';
+import { randomHex } from '../utils/index.js';
+export function createSpan(options) {
+    return {
+        traceId: options.traceId,
+        name: options.name,
+        startTime: options.startTime,
+        spanId: options.spanId ?? randomHex(8),
+        parentSpanId: options.parentSpanId ?? null,
+        attributes: options.attributes ?? {},
+        endTime: null,
+        status: 'ok',
+        events: [],
+    };
+}
+export class StdoutExporter {
+    export(span) {
+        // Use console.info for universal compatibility (Node.js + browser)
+        console.info(JSON.stringify(span));
+    }
+}
+export class InMemoryExporter {
+    _spans = [];
+    _maxSpans;
+    constructor(maxSpans = 10_000) {
+        this._maxSpans = maxSpans;
+    }
+    export(span) {
+        if (this._spans.length >= this._maxSpans) {
+            // Drop oldest half to amortize the cost instead of O(n) shift per insert
+            this._spans = this._spans.slice(Math.floor(this._maxSpans / 2));
+        }
+        this._spans.push(span);
+    }
+    getSpans() {
+        return [...this._spans];
+    }
+    clear() {
+        this._spans = [];
+    }
+}
+export class OTLPExporter {
+    _endpoint;
+    _serviceName;
+    _headers;
+    constructor(options) {
+        this._endpoint = options?.endpoint ?? 'http://localhost:4318/v1/traces';
+        this._serviceName = options?.serviceName ?? 'apcore';
+        this._headers = options?.headers ?? {};
+    }
+    export(span) {
+        const payload = {
+            resourceSpans: [{
+                    resource: {
+                        attributes: [
+                            { key: 'service.name', value: { stringValue: this._serviceName } },
+                        ],
+                    },
+                    scopeSpans: [{
+                            scope: { name: 'apcore' },
+                            spans: [{
+                                    traceId: span.traceId,
+                                    spanId: span.spanId,
+                                    parentSpanId: span.parentSpanId ?? undefined,
+                                    name: span.name,
+                                    startTimeUnixNano: String(Math.round(span.startTime * 1_000_000_000)),
+                                    endTimeUnixNano: span.endTime ? String(Math.round(span.endTime * 1_000_000_000)) : undefined,
+                                    status: { code: span.status === 'ok' ? 1 : 2 },
+                                    attributes: Object.entries(span.attributes).map(([key, value]) => ({
+                                        key,
+                                        value: { stringValue: String(value) },
+                                    })),
+                                }],
+                        }],
+                }],
+        };
+        // Fire-and-forget POST
+        fetch(this._endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this._headers,
+            },
+            body: JSON.stringify(payload),
+        }).catch(() => {
+            // Silently ignore network errors
+        });
+    }
+}
+const VALID_STRATEGIES = new Set(['full', 'proportional', 'error_first', 'off']);
+export class TracingMiddleware extends Middleware {
+    _exporter;
+    _samplingRate;
+    _samplingStrategy;
+    constructor(exporter, samplingRate = 1.0, samplingStrategy = 'full') {
+        super();
+        if (samplingRate < 0.0 || samplingRate > 1.0) {
+            throw new Error(`sampling_rate must be between 0.0 and 1.0, got ${samplingRate}`);
+        }
+        if (!VALID_STRATEGIES.has(samplingStrategy)) {
+            throw new Error(`sampling_strategy must be one of ${[...VALID_STRATEGIES].join(', ')}, got '${samplingStrategy}'`);
+        }
+        this._exporter = exporter;
+        this._samplingRate = samplingRate;
+        this._samplingStrategy = samplingStrategy;
+    }
+    /** Replace the span exporter used by this middleware. */
+    setExporter(exporter) {
+        if (!exporter || typeof exporter.export !== 'function') {
+            throw new Error('exporter must implement SpanExporter interface');
+        }
+        this._exporter = exporter;
+    }
+    _shouldSample(context) {
+        const existing = context.data['_tracing_sampled'];
+        if (typeof existing === 'boolean')
+            return existing;
+        let decision;
+        if (this._samplingStrategy === 'full') {
+            decision = true;
+        }
+        else if (this._samplingStrategy === 'off') {
+            decision = false;
+        }
+        else {
+            decision = Math.random() < this._samplingRate;
+        }
+        context.data['_tracing_sampled'] = decision;
+        return decision;
+    }
+    before(moduleId, _inputs, context) {
+        this._shouldSample(context);
+        const spansStack = context.data['_tracing_spans'] ?? [];
+        context.data['_tracing_spans'] = spansStack;
+        const parentSpanId = spansStack.length > 0 ? spansStack[spansStack.length - 1].spanId : null;
+        const span = createSpan({
+            traceId: context.traceId,
+            name: 'apcore.module.execute',
+            startTime: Date.now() / 1000,
+            parentSpanId,
+            attributes: {
+                moduleId,
+                method: 'execute',
+                callerId: context.callerId,
+            },
+        });
+        spansStack.push(span);
+        return null;
+    }
+    after(moduleId, _inputs, _output, context) {
+        const spansStack = context.data['_tracing_spans'] ?? [];
+        if (spansStack.length === 0)
+            return null;
+        const span = spansStack.pop();
+        span.endTime = Date.now() / 1000;
+        span.status = 'ok';
+        span.attributes['duration_ms'] = (span.endTime - span.startTime) * 1000;
+        span.attributes['success'] = true;
+        if (context.data['_tracing_sampled']) {
+            this._exporter.export(span);
+        }
+        return null;
+    }
+    onError(moduleId, _inputs, error, context) {
+        const spansStack = context.data['_tracing_spans'] ?? [];
+        if (spansStack.length === 0)
+            return null;
+        const span = spansStack.pop();
+        span.endTime = Date.now() / 1000;
+        span.status = 'error';
+        span.attributes['duration_ms'] = (span.endTime - span.startTime) * 1000;
+        span.attributes['success'] = false;
+        span.attributes['error_code'] = error['code'] ?? error.constructor.name;
+        const shouldExport = this._samplingStrategy === 'error_first' || context.data['_tracing_sampled'];
+        if (shouldExport) {
+            this._exporter.export(span);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=tracing.js.map