@blokjs/runner 0.2.0

package/dist/monitoring/StructuredLogger.js

@@ -0,0 +1,207 @@
+/**
+ * StructuredLogger - Production-grade JSON structured logging with trace context
+ *
+ * Outputs machine-parseable JSON log lines with standardized fields compatible
+ * with Grafana Loki, ELK Stack, CloudWatch Logs, and DataDog Logs.
+ *
+ * Key features:
+ * - JSON-structured output with consistent field ordering
+ * - OpenTelemetry trace context correlation (trace_id, span_id)
+ * - Log levels: debug, info, warn, error, fatal
+ * - Child loggers with inherited context
+ * - Configurable transports (stdout, stderr, callback)
+ * - Respects BLOK_LOG_LEVEL and CONSOLE_LOG_ACTIVE env vars
+ *
+ * @example
+ * ```typescript
+ * import { StructuredLogger } from "@blokjs/runner";
+ *
+ * const logger = new StructuredLogger({
+ *   service: "blok-http",
+ *   environment: "production",
+ * });
+ *
+ * logger.info("Workflow started", { workflow: "user-api", requestId: "abc" });
+ * // Output: {"timestamp":"2026-01-29T...","level":"info","service":"blok-http",
+ * //          "message":"Workflow started","workflow":"user-api","requestId":"abc"}
+ *
+ * // Child logger with persistent fields
+ * const reqLogger = logger.child({ requestId: "abc", workflow: "user-api" });
+ * reqLogger.info("Node executed", { node: "db-query", durationMs: 42 });
+ * ```
+ */
+import { trace } from "@opentelemetry/api";
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+export class StructuredLogger {
+    config;
+    transport;
+    defaultFields;
+    minLevelPriority;
+    /** Collected log entries (kept for getLogs() compatibility) */
+    logs = [];
+    maxLogBuffer;
+    constructor(config) {
+        this.config = {
+            service: config.service,
+            environment: config.environment || process.env.NODE_ENV || "development",
+            level: config.level || process.env.BLOK_LOG_LEVEL || "info",
+        };
+        this.minLevelPriority = LOG_LEVEL_PRIORITY[this.config.level] ?? 1;
+        this.defaultFields = config.defaultFields ?? {};
+        this.maxLogBuffer = 1000;
+        this.transport =
+            config.transport ??
+                ((entry) => {
+                    const json = JSON.stringify(entry);
+                    if (entry.level === "error" || entry.level === "fatal") {
+                        process.stderr.write(`${json}\n`);
+                    }
+                    else {
+                        process.stdout.write(`${json}\n`);
+                    }
+                });
+    }
+    /**
+     * Create a child logger with additional persistent context fields.
+     * Useful for request-scoped logging.
+     */
+    child(fields) {
+        const child = new StructuredLogger({
+            service: this.config.service,
+            environment: this.config.environment,
+            level: this.config.level,
+            transport: this.transport,
+            defaultFields: { ...this.defaultFields, ...fields },
+        });
+        return child;
+    }
+    /**
+     * Log at debug level.
+     */
+    debug(message, fields) {
+        this.write("debug", message, fields);
+    }
+    /**
+     * Log at info level.
+     */
+    info(message, fields) {
+        this.write("info", message, fields);
+    }
+    /**
+     * Log at warn level.
+     */
+    warn(message, fields) {
+        this.write("warn", message, fields);
+    }
+    /**
+     * Log at error level, optionally with an Error object.
+     */
+    error(message, fields) {
+        const extra = { ...fields };
+        if (extra.error instanceof Error) {
+            extra.error_message = extra.error.message;
+            extra.error_stack = extra.error.stack;
+            extra.error_name = extra.error.name;
+            extra.error = undefined;
+        }
+        this.write("error", message, extra);
+    }
+    /**
+     * Log at fatal level.
+     */
+    fatal(message, fields) {
+        this.write("fatal", message, fields);
+    }
+    /**
+     * Log with an explicit span for trace correlation.
+     * Use when you have a reference to the active span.
+     */
+    withSpan(span, level, message, fields) {
+        const spanCtx = span.spanContext();
+        this.write(level, message, {
+            ...fields,
+            trace_id: spanCtx.traceId,
+            span_id: spanCtx.spanId,
+        });
+    }
+    /**
+     * Get collected log entries.
+     */
+    getLogs() {
+        return [...this.logs];
+    }
+    /**
+     * Get collected logs as newline-delimited JSON (NDJSON).
+     */
+    getLogsAsNDJSON() {
+        return this.logs.map((entry) => JSON.stringify(entry)).join("\n");
+    }
+    /**
+     * Clear the log buffer.
+     */
+    clearLogs() {
+        this.logs = [];
+    }
+    /**
+     * Get current minimum log level.
+     */
+    getLevel() {
+        return this.config.level;
+    }
+    /**
+     * Set minimum log level at runtime.
+     */
+    setLevel(level) {
+        this.config.level = level;
+        this.minLevelPriority = LOG_LEVEL_PRIORITY[level] ?? 1;
+    }
+    /**
+     * Check if a given level is enabled (at or above current minimum).
+     */
+    isLevelEnabled(level) {
+        return (LOG_LEVEL_PRIORITY[level] ?? 0) >= this.minLevelPriority;
+    }
+    // --- Internal ---
+    write(level, message, fields) {
+        // Check CONSOLE_LOG_ACTIVE
+        if (process.env.CONSOLE_LOG_ACTIVE === "false")
+            return;
+        // Check minimum level
+        if ((LOG_LEVEL_PRIORITY[level] ?? 0) < this.minLevelPriority)
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            service: this.config.service,
+            env: this.config.environment,
+            message,
+            ...this.defaultFields,
+            ...fields,
+        };
+        // Inject OpenTelemetry trace context if available and not already set
+        if (!entry.trace_id) {
+            const activeSpan = trace.getActiveSpan();
+            if (activeSpan) {
+                const spanCtx = activeSpan.spanContext();
+                if (spanCtx.traceId !== "00000000000000000000000000000000") {
+                    entry.trace_id = spanCtx.traceId;
+                    entry.span_id = spanCtx.spanId;
+                }
+            }
+        }
+        // Buffer for getLogs()
+        this.logs.push(entry);
+        if (this.logs.length > this.maxLogBuffer) {
+            this.logs = this.logs.slice(-Math.floor(this.maxLogBuffer / 2));
+        }
+        // Transport
+        this.transport(entry);
+    }
+}
+//# sourceMappingURL=StructuredLogger.js.map

package/dist/monitoring/StructuredLogger.js.map

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

package/dist/monitoring/TracingBootstrap.d.ts

@@ -0,0 +1,69 @@
+/**
+ * TracingBootstrap - Configures OpenTelemetry TracerProvider with OTLP/Jaeger/Zipkin exporters
+ *
+ * Uses dynamic imports for @opentelemetry/sdk-trace-node, OTLP exporter, etc.
+ * Returns null if the packages are not installed (they are optional peer dependencies).
+ * Call this once at trigger startup in listen().
+ *
+ * Supports multiple exporter backends:
+ * - OTLP (gRPC or HTTP) — works with Jaeger, Tempo, DataDog, New Relic, etc.
+ * - Console — for development/debugging
+ *
+ * @example
+ * ```typescript
+ * import { bootstrapTracing } from "@blokjs/runner";
+ *
+ * const result = await bootstrapTracing({
+ *   serviceName: "blok-http",
+ *   exporter: "otlp",
+ *   endpoint: "http://localhost:4318/v1/traces",
+ * });
+ *
+ * if (result) {
+ *   process.on("SIGTERM", result.shutdown);
+ * }
+ * ```
+ */
+export type TracingExporterType = "otlp" | "console";
+export interface TracingBootstrapConfig {
+    /** Service name used in Resource attributes */
+    serviceName: string;
+    /** Service version (default: "0.0.1") */
+    serviceVersion?: string;
+    /** Exporter type (default: "otlp") */
+    exporter?: TracingExporterType;
+    /**
+     * OTLP endpoint URL (default: env OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+     * or "http://localhost:4318/v1/traces")
+     */
+    endpoint?: string;
+    /** OTLP protocol: "http/protobuf" | "grpc" (default: "http/protobuf") */
+    protocol?: "http/protobuf" | "grpc";
+    /** Additional OTLP headers (e.g., auth tokens for DataDog/New Relic) */
+    headers?: Record<string, string>;
+    /** Sampling ratio (0.0 to 1.0, default: 1.0) */
+    samplingRatio?: number;
+    /** Max batch export delay in ms (default: 5000) */
+    batchExportDelayMs?: number;
+    /** Max export batch size (default: 512) */
+    maxExportBatchSize?: number;
+}
+export interface TracingBootstrapResult {
+    /** Graceful shutdown — flushes pending spans and shuts down the provider */
+    shutdown: () => Promise<void>;
+    /** Force flush pending spans */
+    forceFlush: () => Promise<void>;
+}
+/**
+ * Bootstrap distributed tracing using OpenTelemetry.
+ *
+ * Dynamically imports @opentelemetry/sdk-trace-node and the selected exporter.
+ * If the packages are not installed, returns null silently.
+ *
+ * @returns Bootstrap result with shutdown/flush, or null if packages unavailable
+ */
+export declare function bootstrapTracing(config: TracingBootstrapConfig): Promise<TracingBootstrapResult | null>;
+/**
+ * Reset the initialization state. Useful for testing.
+ */
+export declare function resetTracingBootstrap(): void;

package/dist/monitoring/TracingBootstrap.js

@@ -0,0 +1,129 @@
+/**
+ * TracingBootstrap - Configures OpenTelemetry TracerProvider with OTLP/Jaeger/Zipkin exporters
+ *
+ * Uses dynamic imports for @opentelemetry/sdk-trace-node, OTLP exporter, etc.
+ * Returns null if the packages are not installed (they are optional peer dependencies).
+ * Call this once at trigger startup in listen().
+ *
+ * Supports multiple exporter backends:
+ * - OTLP (gRPC or HTTP) — works with Jaeger, Tempo, DataDog, New Relic, etc.
+ * - Console — for development/debugging
+ *
+ * @example
+ * ```typescript
+ * import { bootstrapTracing } from "@blokjs/runner";
+ *
+ * const result = await bootstrapTracing({
+ *   serviceName: "blok-http",
+ *   exporter: "otlp",
+ *   endpoint: "http://localhost:4318/v1/traces",
+ * });
+ *
+ * if (result) {
+ *   process.on("SIGTERM", result.shutdown);
+ * }
+ * ```
+ */
+import { trace } from "@opentelemetry/api";
+let initialized = false;
+/**
+ * Bootstrap distributed tracing using OpenTelemetry.
+ *
+ * Dynamically imports @opentelemetry/sdk-trace-node and the selected exporter.
+ * If the packages are not installed, returns null silently.
+ *
+ * @returns Bootstrap result with shutdown/flush, or null if packages unavailable
+ */
+export async function bootstrapTracing(config) {
+    if (initialized) {
+        return null;
+    }
+    try {
+        const exporterType = config.exporter ?? "otlp";
+        const protocol = config.protocol ?? "http/protobuf";
+        // Dynamic imports — these are optional peer dependencies
+        const sdkTracePkg = "@opentelemetry/sdk-trace-node";
+        const resourcesPkg = "@opentelemetry/resources";
+        const semconvPkg = "@opentelemetry/semantic-conventions";
+        const [sdkMod, resourceMod, semconvMod] = await Promise.all([
+            import(/* webpackIgnore: true */ sdkTracePkg),
+            import(/* webpackIgnore: true */ resourcesPkg),
+            import(/* webpackIgnore: true */ semconvPkg),
+        ]);
+        const { NodeTracerProvider, BatchSpanProcessor, SimpleSpanProcessor, ConsoleSpanExporter } = sdkMod;
+        const { Resource } = resourceMod;
+        const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = semconvMod;
+        // Build resource
+        const resource = Resource.default().merge(new Resource({
+            [ATTR_SERVICE_NAME]: config.serviceName,
+            [ATTR_SERVICE_VERSION]: config.serviceVersion ?? "0.0.1",
+        }));
+        // Create the appropriate exporter
+        let spanExporter;
+        let spanProcessor;
+        if (exporterType === "console") {
+            spanExporter = new ConsoleSpanExporter();
+            spanProcessor = new SimpleSpanProcessor(spanExporter);
+        }
+        else {
+            // OTLP exporter
+            const endpoint = config.endpoint ||
+                process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
+                process.env.OTEL_EXPORTER_OTLP_ENDPOINT ||
+                "http://localhost:4318/v1/traces";
+            if (protocol === "grpc") {
+                const grpcPkg = "@opentelemetry/exporter-trace-otlp-grpc";
+                const grpcMod = await import(/* webpackIgnore: true */ grpcPkg);
+                spanExporter = new grpcMod.OTLPTraceExporter({
+                    url: endpoint,
+                    headers: config.headers,
+                });
+            }
+            else {
+                const httpPkg = "@opentelemetry/exporter-trace-otlp-http";
+                const httpMod = await import(/* webpackIgnore: true */ httpPkg);
+                spanExporter = new httpMod.OTLPTraceExporter({
+                    url: endpoint,
+                    headers: config.headers,
+                });
+            }
+            spanProcessor = new BatchSpanProcessor(spanExporter, {
+                maxExportBatchSize: config.maxExportBatchSize ?? 512,
+                scheduledDelayMillis: config.batchExportDelayMs ?? 5000,
+            });
+        }
+        // Create provider with optional sampling
+        const providerConfig = { resource };
+        if (config.samplingRatio !== undefined && config.samplingRatio < 1.0) {
+            const { TraceIdRatioBasedSampler } = sdkMod;
+            providerConfig.sampler = new TraceIdRatioBasedSampler(config.samplingRatio);
+        }
+        const provider = new NodeTracerProvider(providerConfig);
+        provider.addSpanProcessor(spanProcessor);
+        // Register globally so `trace.getTracer()` picks up this provider
+        provider.register();
+        initialized = true;
+        return {
+            shutdown: async () => {
+                await provider.shutdown();
+                initialized = false;
+            },
+            forceFlush: async () => {
+                await provider.forceFlush();
+            },
+        };
+    }
+    catch {
+        // OpenTelemetry SDK packages not installed — this is expected and fine
+        return null;
+    }
+}
+/**
+ * Reset the initialization state. Useful for testing.
+ */
+export function resetTracingBootstrap() {
+    // Also disable the global tracer provider so a fresh one can be registered
+    trace.disable();
+    initialized = false;
+}
+//# sourceMappingURL=TracingBootstrap.js.map

package/dist/monitoring/TracingBootstrap.js.map

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

package/dist/monitoring/TriggerMetricsCollector.d.ts

@@ -0,0 +1,94 @@
+/**
+ * TriggerMetricsCollector - Enhanced Metrics for Blok Triggers
+ *
+ * Centralized metrics collection with latency percentiles,
+ * error categorization, throughput tracking, and resource monitoring.
+ */
+export interface LatencyStats {
+    count: number;
+    min: number;
+    max: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+}
+export interface ErrorStats {
+    total: number;
+    byCategory: Record<string, number>;
+    recentErrors: Array<{
+        message: string;
+        category: string;
+        timestamp: number;
+    }>;
+}
+export interface ThroughputStats {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    requestsPerSecond: number;
+    successRate: number;
+}
+export interface TriggerMetrics {
+    triggerType: string;
+    triggerName: string;
+    startTime: number;
+    latency: LatencyStats;
+    errors: ErrorStats;
+    throughput: ThroughputStats;
+    activeConnections: number;
+    customMetrics: Record<string, number>;
+}
+export declare class TriggerMetricsCollector {
+    private triggerType;
+    private triggerName;
+    private startTime;
+    private latencySamples;
+    private errorCount;
+    private errorsByCategory;
+    private recentErrors;
+    private totalRequests;
+    private successfulRequests;
+    private failedRequests;
+    private _activeConnections;
+    private customMetrics;
+    private requestTimestamps;
+    private rpsWindow;
+    constructor(triggerType: string, triggerName: string);
+    /**
+     * Record a successful request with its latency.
+     */
+    recordSuccess(latencyMs: number): void;
+    /**
+     * Record a failed request with error details.
+     */
+    recordFailure(latencyMs: number, error: Error | string, category?: string): void;
+    /**
+     * Track active connections (for WebSocket, SSE, etc.).
+     */
+    incrementConnections(): void;
+    decrementConnections(): void;
+    get activeConnections(): number;
+    /**
+     * Set a custom metric value.
+     */
+    setMetric(name: string, value: number): void;
+    /**
+     * Increment a custom metric.
+     */
+    incrementMetric(name: string, amount?: number): void;
+    /**
+     * Get a snapshot of all metrics.
+     */
+    getMetrics(): TriggerMetrics;
+    /**
+     * Reset all collected metrics.
+     */
+    reset(): void;
+    private addLatencySample;
+    private recordRequestTimestamp;
+    private getLatencyStats;
+    private getErrorStats;
+    private getThroughputStats;
+    private percentile;
+}

package/dist/monitoring/TriggerMetricsCollector.js

@@ -0,0 +1,174 @@
+/**
+ * TriggerMetricsCollector - Enhanced Metrics for Blok Triggers
+ *
+ * Centralized metrics collection with latency percentiles,
+ * error categorization, throughput tracking, and resource monitoring.
+ */
+const MAX_RECENT_ERRORS = 50;
+const MAX_LATENCY_SAMPLES = 10_000;
+export class TriggerMetricsCollector {
+    triggerType;
+    triggerName;
+    startTime;
+    latencySamples = [];
+    errorCount = 0;
+    errorsByCategory = new Map();
+    recentErrors = [];
+    totalRequests = 0;
+    successfulRequests = 0;
+    failedRequests = 0;
+    _activeConnections = 0;
+    customMetrics = new Map();
+    requestTimestamps = [];
+    rpsWindow = 60_000; // 1 minute window for RPS calculation
+    constructor(triggerType, triggerName) {
+        this.triggerType = triggerType;
+        this.triggerName = triggerName;
+        this.startTime = Date.now();
+    }
+    /**
+     * Record a successful request with its latency.
+     */
+    recordSuccess(latencyMs) {
+        this.totalRequests++;
+        this.successfulRequests++;
+        this.addLatencySample(latencyMs);
+        this.recordRequestTimestamp();
+    }
+    /**
+     * Record a failed request with error details.
+     */
+    recordFailure(latencyMs, error, category = "unknown") {
+        this.totalRequests++;
+        this.failedRequests++;
+        this.errorCount++;
+        this.addLatencySample(latencyMs);
+        this.recordRequestTimestamp();
+        const count = this.errorsByCategory.get(category) || 0;
+        this.errorsByCategory.set(category, count + 1);
+        this.recentErrors.push({
+            message: typeof error === "string" ? error : error.message,
+            category,
+            timestamp: Date.now(),
+        });
+        if (this.recentErrors.length > MAX_RECENT_ERRORS) {
+            this.recentErrors.shift();
+        }
+    }
+    /**
+     * Track active connections (for WebSocket, SSE, etc.).
+     */
+    incrementConnections() {
+        this._activeConnections++;
+    }
+    decrementConnections() {
+        this._activeConnections = Math.max(0, this._activeConnections - 1);
+    }
+    get activeConnections() {
+        return this._activeConnections;
+    }
+    /**
+     * Set a custom metric value.
+     */
+    setMetric(name, value) {
+        this.customMetrics.set(name, value);
+    }
+    /**
+     * Increment a custom metric.
+     */
+    incrementMetric(name, amount = 1) {
+        const current = this.customMetrics.get(name) || 0;
+        this.customMetrics.set(name, current + amount);
+    }
+    /**
+     * Get a snapshot of all metrics.
+     */
+    getMetrics() {
+        return {
+            triggerType: this.triggerType,
+            triggerName: this.triggerName,
+            startTime: this.startTime,
+            latency: this.getLatencyStats(),
+            errors: this.getErrorStats(),
+            throughput: this.getThroughputStats(),
+            activeConnections: this._activeConnections,
+            customMetrics: Object.fromEntries(this.customMetrics),
+        };
+    }
+    /**
+     * Reset all collected metrics.
+     */
+    reset() {
+        this.latencySamples = [];
+        this.errorCount = 0;
+        this.errorsByCategory.clear();
+        this.recentErrors = [];
+        this.totalRequests = 0;
+        this.successfulRequests = 0;
+        this.failedRequests = 0;
+        this._activeConnections = 0;
+        this.customMetrics.clear();
+        this.requestTimestamps = [];
+        this.startTime = Date.now();
+    }
+    addLatencySample(ms) {
+        this.latencySamples.push(ms);
+        if (this.latencySamples.length > MAX_LATENCY_SAMPLES) {
+            // Keep only the most recent half
+            this.latencySamples = this.latencySamples.slice(-MAX_LATENCY_SAMPLES / 2);
+        }
+    }
+    recordRequestTimestamp() {
+        const now = Date.now();
+        this.requestTimestamps.push(now);
+        // Prune timestamps outside the RPS window
+        const cutoff = now - this.rpsWindow;
+        while (this.requestTimestamps.length > 0 && this.requestTimestamps[0] < cutoff) {
+            this.requestTimestamps.shift();
+        }
+    }
+    getLatencyStats() {
+        if (this.latencySamples.length === 0) {
+            return { count: 0, min: 0, max: 0, avg: 0, p50: 0, p95: 0, p99: 0 };
+        }
+        const sorted = [...this.latencySamples].sort((a, b) => a - b);
+        const count = sorted.length;
+        const sum = sorted.reduce((a, b) => a + b, 0);
+        return {
+            count,
+            min: sorted[0],
+            max: sorted[count - 1],
+            avg: sum / count,
+            p50: this.percentile(sorted, 50),
+            p95: this.percentile(sorted, 95),
+            p99: this.percentile(sorted, 99),
+        };
+    }
+    getErrorStats() {
+        return {
+            total: this.errorCount,
+            byCategory: Object.fromEntries(this.errorsByCategory),
+            recentErrors: [...this.recentErrors],
+        };
+    }
+    getThroughputStats() {
+        const now = Date.now();
+        const cutoff = now - this.rpsWindow;
+        const recentRequests = this.requestTimestamps.filter((t) => t > cutoff).length;
+        const windowSeconds = this.rpsWindow / 1000;
+        return {
+            totalRequests: this.totalRequests,
+            successfulRequests: this.successfulRequests,
+            failedRequests: this.failedRequests,
+            requestsPerSecond: recentRequests / windowSeconds,
+            successRate: this.totalRequests > 0 ? this.successfulRequests / this.totalRequests : 1,
+        };
+    }
+    percentile(sorted, p) {
+        if (sorted.length === 0)
+            return 0;
+        const index = Math.ceil((p / 100) * sorted.length) - 1;
+        return sorted[Math.max(0, Math.min(index, sorted.length - 1))];
+    }
+}
+//# sourceMappingURL=TriggerMetricsCollector.js.map