@blokjs/runner 0.2.0

package/dist/monitoring/PrometheusMetricsBridge.js

@@ -0,0 +1,216 @@
+/**
+ * PrometheusMetricsBridge - Bridges internal metrics to OpenTelemetry/Prometheus
+ *
+ * Exposes TriggerMetricsCollector data as properly-named Prometheus metrics
+ * using the OpenTelemetry API. Works as no-op if no MeterProvider is configured.
+ */
+import { metrics } from "@opentelemetry/api";
+export class PrometheusMetricsBridge {
+    meter;
+    config;
+    collector;
+    circuitBreaker = null;
+    rateLimiter = null;
+    // Active instruments
+    executionsCounter;
+    durationHistogram;
+    errorsCounter;
+    // Observable instruments (registered once, polled at scrape time)
+    observableGauges = [];
+    initialized = false;
+    constructor(config, collector) {
+        this.config = config;
+        this.collector = collector;
+        this.meter = metrics.getMeter("blok");
+        // Create active instruments immediately
+        this.executionsCounter = this.meter.createCounter("blok_workflow_executions_total", {
+            description: "Total number of workflow executions",
+            unit: "1",
+        });
+        this.durationHistogram = this.meter.createHistogram("blok_workflow_duration_seconds", {
+            description: "Workflow execution duration in seconds",
+            unit: "s",
+        });
+        this.errorsCounter = this.meter.createCounter("blok_workflow_errors_total", {
+            description: "Total number of workflow execution errors",
+            unit: "1",
+        });
+    }
+    /**
+     * Register observable callbacks that pull from the TriggerMetricsCollector
+     * at scrape time. Call this once after construction.
+     */
+    initialize() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        const baseAttrs = {
+            trigger_type: this.config.triggerType,
+            trigger_name: this.config.triggerName,
+        };
+        // Latency percentile gauges (pulled from collector at scrape time)
+        const p50 = this.meter.createObservableGauge("blok_trigger_latency_p50_seconds", {
+            description: "Trigger request latency 50th percentile in seconds",
+            unit: "s",
+        });
+        p50.addCallback((result) => {
+            const m = this.collector.getMetrics();
+            result.observe(m.latency.p50 / 1000, baseAttrs);
+        });
+        this.observableGauges.push(p50);
+        const p95 = this.meter.createObservableGauge("blok_trigger_latency_p95_seconds", {
+            description: "Trigger request latency 95th percentile in seconds",
+            unit: "s",
+        });
+        p95.addCallback((result) => {
+            const m = this.collector.getMetrics();
+            result.observe(m.latency.p95 / 1000, baseAttrs);
+        });
+        this.observableGauges.push(p95);
+        const p99 = this.meter.createObservableGauge("blok_trigger_latency_p99_seconds", {
+            description: "Trigger request latency 99th percentile in seconds",
+            unit: "s",
+        });
+        p99.addCallback((result) => {
+            const m = this.collector.getMetrics();
+            result.observe(m.latency.p99 / 1000, baseAttrs);
+        });
+        this.observableGauges.push(p99);
+        // Throughput
+        const rps = this.meter.createObservableGauge("blok_trigger_throughput_rps", {
+            description: "Trigger requests per second",
+            unit: "1/s",
+        });
+        rps.addCallback((result) => {
+            const m = this.collector.getMetrics();
+            result.observe(m.throughput.requestsPerSecond, baseAttrs);
+        });
+        this.observableGauges.push(rps);
+        const successRate = this.meter.createObservableGauge("blok_trigger_success_rate", {
+            description: "Trigger success rate (0-1)",
+            unit: "1",
+        });
+        successRate.addCallback((result) => {
+            const m = this.collector.getMetrics();
+            result.observe(m.throughput.successRate, baseAttrs);
+        });
+        this.observableGauges.push(successRate);
+        // Active connections (for WebSocket/SSE)
+        const connections = this.meter.createObservableGauge("blok_trigger_active_connections", {
+            description: "Number of active connections",
+            unit: "1",
+        });
+        connections.addCallback((result) => {
+            const m = this.collector.getMetrics();
+            result.observe(m.activeConnections, baseAttrs);
+        });
+        this.observableGauges.push(connections);
+        // Process metrics
+        const heapMemory = this.meter.createObservableGauge("blok_process_memory_heap_bytes", {
+            description: "Process heap memory usage in bytes",
+            unit: "By",
+        });
+        heapMemory.addCallback((result) => {
+            const memUsage = process.memoryUsage();
+            result.observe(memUsage.heapUsed, { trigger_type: this.config.triggerType });
+        });
+        this.observableGauges.push(heapMemory);
+        const rssMemory = this.meter.createObservableGauge("blok_process_memory_rss_bytes", {
+            description: "Process RSS memory in bytes",
+            unit: "By",
+        });
+        rssMemory.addCallback((result) => {
+            const memUsage = process.memoryUsage();
+            result.observe(memUsage.rss, { trigger_type: this.config.triggerType });
+        });
+        this.observableGauges.push(rssMemory);
+        // Circuit breaker state gauge
+        const cbState = this.meter.createObservableGauge("blok_circuit_breaker_state", {
+            description: "Circuit breaker state (0=closed, 1=open, 2=half_open)",
+            unit: "1",
+        });
+        cbState.addCallback((result) => {
+            if (!this.circuitBreaker)
+                return;
+            const stats = this.circuitBreaker.getStats();
+            const stateValue = stats.state === "CLOSED" ? 0 : stats.state === "OPEN" ? 1 : 2;
+            result.observe(stateValue, baseAttrs);
+        });
+        this.observableGauges.push(cbState);
+        // Rate limiter remaining tokens
+        const rlRemaining = this.meter.createObservableGauge("blok_rate_limiter_remaining", {
+            description: "Rate limiter remaining tokens (global bucket)",
+            unit: "1",
+        });
+        rlRemaining.addCallback((result) => {
+            if (!this.rateLimiter)
+                return;
+            const peek = this.rateLimiter.peek("global");
+            result.observe(peek.remaining, baseAttrs);
+        });
+        this.observableGauges.push(rlRemaining);
+    }
+    /**
+     * Record a workflow execution. Called from TriggerBase.run() after each request.
+     *
+     * @param durationMs - Execution duration in milliseconds
+     * @param success - Whether the execution succeeded
+     * @param labels - Workflow-specific labels
+     */
+    recordExecution(durationMs, success, labels) {
+        const attrs = {
+            trigger_type: this.config.triggerType,
+            trigger_name: this.config.triggerName,
+            workflow_name: labels.workflow_name,
+            status: success ? "success" : "error",
+            env: labels.env,
+        };
+        this.executionsCounter.add(1, attrs);
+        this.durationHistogram.record(durationMs / 1000, {
+            trigger_type: this.config.triggerType,
+            trigger_name: this.config.triggerName,
+            workflow_name: labels.workflow_name,
+            env: labels.env,
+        });
+        // Also record to the internal collector for percentile tracking
+        if (success) {
+            this.collector.recordSuccess(durationMs);
+        }
+        else {
+            this.collector.recordFailure(durationMs, "execution_error", "runtime");
+        }
+    }
+    /**
+     * Record an error with a specific category.
+     */
+    recordError(category, labels = {}) {
+        this.errorsCounter.add(1, {
+            trigger_type: this.config.triggerType,
+            trigger_name: this.config.triggerName,
+            error_category: category,
+            env: labels.env || process.env.NODE_ENV || "development",
+        });
+    }
+    /**
+     * Attach a CircuitBreaker for state monitoring.
+     */
+    attachCircuitBreaker(cb) {
+        this.circuitBreaker = cb;
+    }
+    /**
+     * Attach a RateLimiter for remaining token monitoring.
+     */
+    attachRateLimiter(rl) {
+        this.rateLimiter = rl;
+    }
+    /**
+     * Clean up resources.
+     */
+    destroy() {
+        this.circuitBreaker = null;
+        this.rateLimiter = null;
+        this.observableGauges = [];
+        this.initialized = false;
+    }
+}
+//# sourceMappingURL=PrometheusMetricsBridge.js.map

package/dist/monitoring/PrometheusMetricsBridge.js.map

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

package/dist/monitoring/RateLimiter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Token Bucket Rate Limiter for Blok Triggers
+ *
+ * Implements the token bucket algorithm for rate limiting trigger events.
+ * Supports per-client, per-workflow, and per-topic rate limiting.
+ */
+export interface RateLimitConfig {
+    /** Maximum number of tokens in the bucket */
+    maxTokens: number;
+    /** Tokens added per second */
+    refillRate: number;
+    /** Key strategy for identifying rate limit buckets */
+    keyStrategy?: "client" | "workflow" | "topic" | "global";
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfterMs: number;
+    limit: number;
+}
+export declare class RateLimiter {
+    private buckets;
+    private config;
+    private cleanupInterval;
+    private bucketMaxIdleMs;
+    constructor(config: RateLimitConfig, bucketMaxIdleMs?: number);
+    /**
+     * Check if a request is allowed under the rate limit.
+     * Consumes a token if allowed.
+     */
+    consume(key: string, tokens?: number): RateLimitResult;
+    /**
+     * Check rate limit without consuming a token.
+     */
+    peek(key: string): RateLimitResult;
+    /**
+     * Reset the rate limiter for a specific key.
+     */
+    reset(key: string): void;
+    /**
+     * Reset all rate limit buckets.
+     */
+    resetAll(): void;
+    /**
+     * Get current stats for monitoring.
+     */
+    getStats(): {
+        activeBuckets: number;
+        config: RateLimitConfig;
+    };
+    /**
+     * Stop the cleanup interval. Call when shutting down.
+     */
+    destroy(): void;
+    private getOrCreateBucket;
+    private refill;
+    private startCleanup;
+}

package/dist/monitoring/RateLimiter.js

@@ -0,0 +1,128 @@
+/**
+ * Token Bucket Rate Limiter for Blok Triggers
+ *
+ * Implements the token bucket algorithm for rate limiting trigger events.
+ * Supports per-client, per-workflow, and per-topic rate limiting.
+ */
+export class RateLimiter {
+    buckets = new Map();
+    config;
+    cleanupInterval = null;
+    bucketMaxIdleMs;
+    constructor(config, bucketMaxIdleMs = 60_000) {
+        this.config = config;
+        this.bucketMaxIdleMs = bucketMaxIdleMs;
+        this.startCleanup();
+    }
+    /**
+     * Check if a request is allowed under the rate limit.
+     * Consumes a token if allowed.
+     */
+    consume(key, tokens = 1) {
+        const bucket = this.getOrCreateBucket(key);
+        this.refill(bucket);
+        if (bucket.tokens >= tokens) {
+            bucket.tokens -= tokens;
+            return {
+                allowed: true,
+                remaining: Math.floor(bucket.tokens),
+                retryAfterMs: 0,
+                limit: this.config.maxTokens,
+            };
+        }
+        const tokensNeeded = tokens - bucket.tokens;
+        const retryAfterMs = Math.ceil((tokensNeeded / this.config.refillRate) * 1000);
+        return {
+            allowed: false,
+            remaining: 0,
+            retryAfterMs,
+            limit: this.config.maxTokens,
+        };
+    }
+    /**
+     * Check rate limit without consuming a token.
+     */
+    peek(key) {
+        const bucket = this.buckets.get(key);
+        if (!bucket) {
+            return {
+                allowed: true,
+                remaining: this.config.maxTokens,
+                retryAfterMs: 0,
+                limit: this.config.maxTokens,
+            };
+        }
+        const cloned = { ...bucket };
+        this.refill(cloned);
+        return {
+            allowed: cloned.tokens >= 1,
+            remaining: Math.floor(cloned.tokens),
+            retryAfterMs: cloned.tokens >= 1 ? 0 : Math.ceil((1 / this.config.refillRate) * 1000),
+            limit: this.config.maxTokens,
+        };
+    }
+    /**
+     * Reset the rate limiter for a specific key.
+     */
+    reset(key) {
+        this.buckets.delete(key);
+    }
+    /**
+     * Reset all rate limit buckets.
+     */
+    resetAll() {
+        this.buckets.clear();
+    }
+    /**
+     * Get current stats for monitoring.
+     */
+    getStats() {
+        return {
+            activeBuckets: this.buckets.size,
+            config: { ...this.config },
+        };
+    }
+    /**
+     * Stop the cleanup interval. Call when shutting down.
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.buckets.clear();
+    }
+    getOrCreateBucket(key) {
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = {
+                tokens: this.config.maxTokens,
+                lastRefill: Date.now(),
+            };
+            this.buckets.set(key, bucket);
+        }
+        return bucket;
+    }
+    refill(bucket) {
+        const now = Date.now();
+        const elapsed = (now - bucket.lastRefill) / 1000;
+        const tokensToAdd = elapsed * this.config.refillRate;
+        bucket.tokens = Math.min(this.config.maxTokens, bucket.tokens + tokensToAdd);
+        bucket.lastRefill = now;
+    }
+    startCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [key, bucket] of this.buckets.entries()) {
+                if (now - bucket.lastRefill > this.bucketMaxIdleMs) {
+                    this.buckets.delete(key);
+                }
+            }
+        }, this.bucketMaxIdleMs);
+        // Don't prevent process exit
+        if (this.cleanupInterval.unref) {
+            this.cleanupInterval.unref();
+        }
+    }
+}
+//# sourceMappingURL=RateLimiter.js.map

package/dist/monitoring/RateLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimiter.js","sourceRoot":"","sources":["../../src/monitoring/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH,MAAM,OAAO,WAAW;IACf,OAAO,GAAwB,IAAI,GAAG,EAAE,CAAC;IACzC,MAAM,CAAkB;IACxB,eAAe,GAA0C,IAAI,CAAC;IAC9D,eAAe,CAAS;IAEhC,YAAY,MAAuB,EAAE,eAAe,GAAG,MAAM;QAC5D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,YAAY,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,GAAW,EAAE,MAAM,GAAG,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEpB,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YAC7B,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC;YACxB,OAAO;gBACN,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;gBACpC,YAAY,EAAE,CAAC;gBACf,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;aAC5B,CAAC;QACH,CAAC;QAED,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;QAE/E,OAAO;YACN,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,CAAC;YACZ,YAAY;YACZ,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;SAC5B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,GAAW;QACf,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,OAAO;gBACN,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAChC,YAAY,EAAE,CAAC;gBACf,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;aAC5B,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEpB,OAAO;YACN,OAAO,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC;YAC3B,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;YACpC,YAAY,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;YACrF,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;SAC5B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,QAAQ;QACP,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,QAAQ;QACP,OAAO;YACN,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;YAChC,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;SAC1B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO;QACN,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACpC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAEO,iBAAiB,CAAC,GAAW;QACpC,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,MAAM,GAAG;gBACR,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAC7B,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAEO,MAAM,CAAC,MAAc;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACjD,MAAM,WAAW,GAAG,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;QAErD,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;QAC7E,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC;IACzB,CAAC;IAEO,YAAY;QACnB,IAAI,CAAC,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;gBACpD,IAAI,GAAG,GAAG,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;oBACpD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC1B,CAAC;YACF,CAAC;QACF,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QAEzB,6BAA6B;QAC7B,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC9B,CAAC;IACF,CAAC;CACD"}

package/dist/monitoring/StructuredLogger.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 { type Span } from "@opentelemetry/api";
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+export interface StructuredLoggerConfig {
+    /** Service name */
+    service: string;
+    /** Deployment environment (defaults to NODE_ENV) */
+    environment?: string;
+    /** Minimum log level (defaults to BLOK_LOG_LEVEL env or "info") */
+    level?: LogLevel;
+    /** Custom transport function (defaults to console.log/console.error) */
+    transport?: (entry: LogEntry) => void;
+    /** Additional fields added to every log entry */
+    defaultFields?: Record<string, unknown>;
+}
+export interface LogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Service name */
+    service: string;
+    /** Environment */
+    env: string;
+    /** Log message */
+    message: string;
+    /** OpenTelemetry trace ID (if available) */
+    trace_id?: string;
+    /** OpenTelemetry span ID (if available) */
+    span_id?: string;
+    /** Additional structured fields */
+    [key: string]: unknown;
+}
+export declare class StructuredLogger {
+    private config;
+    private transport;
+    private defaultFields;
+    private minLevelPriority;
+    /** Collected log entries (kept for getLogs() compatibility) */
+    private logs;
+    private maxLogBuffer;
+    constructor(config: StructuredLoggerConfig);
+    /**
+     * Create a child logger with additional persistent context fields.
+     * Useful for request-scoped logging.
+     */
+    child(fields: Record<string, unknown>): StructuredLogger;
+    /**
+     * Log at debug level.
+     */
+    debug(message: string, fields?: Record<string, unknown>): void;
+    /**
+     * Log at info level.
+     */
+    info(message: string, fields?: Record<string, unknown>): void;
+    /**
+     * Log at warn level.
+     */
+    warn(message: string, fields?: Record<string, unknown>): void;
+    /**
+     * Log at error level, optionally with an Error object.
+     */
+    error(message: string, fields?: Record<string, unknown> & {
+        error?: Error;
+    }): void;
+    /**
+     * Log at fatal level.
+     */
+    fatal(message: string, fields?: Record<string, unknown>): void;
+    /**
+     * Log with an explicit span for trace correlation.
+     * Use when you have a reference to the active span.
+     */
+    withSpan(span: Span, level: LogLevel, message: string, fields?: Record<string, unknown>): void;
+    /**
+     * Get collected log entries.
+     */
+    getLogs(): LogEntry[];
+    /**
+     * Get collected logs as newline-delimited JSON (NDJSON).
+     */
+    getLogsAsNDJSON(): string;
+    /**
+     * Clear the log buffer.
+     */
+    clearLogs(): void;
+    /**
+     * Get current minimum log level.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set minimum log level at runtime.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Check if a given level is enabled (at or above current minimum).
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    private write;
+}