@blokjs/runner 0.2.0

package/dist/integrations/AzureMonitorIntegration.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Azure Monitor Integration for Blok
+ *
+ * Exports traces, metrics, and logs to Azure Application Insights via the
+ * Azure Monitor OpenTelemetry Exporter or the Application Insights SDK.
+ *
+ * Supports two modes:
+ * 1. **OTLP mode** (recommended) – Uses the generic OTLP exporter pointing at
+ *    the Azure Monitor OTLP endpoint.  Requires an Application Insights
+ *    connection string.
+ * 2. **Azure Exporter mode** – Uses `@azure/monitor-opentelemetry-exporter`
+ *    for native Azure integration with automatic sampling and live metrics.
+ *
+ * All Azure SDK dependencies are loaded lazily so the framework doesn't
+ * hard-depend on any Azure packages.  If the packages are not installed
+ * `init()` returns false and the integration is a no-op.
+ *
+ * @example
+ * ```typescript
+ * import { AzureMonitorIntegration } from "@blokjs/runner";
+ *
+ * const azure = new AzureMonitorIntegration({
+ *   connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING!,
+ *   serviceName: "blok-http",
+ * });
+ *
+ * await azure.init();
+ *
+ * // Track a custom event
+ * azure.trackEvent("WorkflowCompleted", { workflowName: "get-user", durationMs: "42" });
+ *
+ * // Track an exception
+ * azure.trackException(error, { workflowName: "get-user", nodeName: "fetch-db" });
+ *
+ * // Track a metric
+ * azure.trackMetric("WorkflowDuration", 42);
+ * ```
+ */
+export interface AzureMonitorConfig {
+    /**
+     * Application Insights connection string.
+     * Falls back to APPLICATIONINSIGHTS_CONNECTION_STRING env var.
+     */
+    connectionString?: string;
+    /** Blok service name */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Environment label */
+    environment?: string;
+    /**
+     * Export mode:
+     * - "azure" – use @azure/monitor-opentelemetry-exporter (native)
+     * - "otlp"  – use generic OTLP exporter with Azure ingestion endpoint
+     * Default: "azure"
+     */
+    exportMode?: "azure" | "otlp";
+    /** Trace sampling ratio (0.0 – 1.0, default: 1.0) */
+    samplingRatio?: number;
+    /** Enable live metrics stream (default: false) */
+    enableLiveMetrics?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export interface AzureMonitorStats {
+    initialized: boolean;
+    eventsTracked: number;
+    exceptionsTracked: number;
+    metricsTracked: number;
+}
+export declare class AzureMonitorIntegration {
+    private config;
+    private initialized;
+    private exporter;
+    private tracingShutdown;
+    private telemetryClient;
+    private eventsTracked;
+    private exceptionsTracked;
+    private metricsTracked;
+    constructor(config: AzureMonitorConfig);
+    /**
+     * Initialize Azure Monitor.
+     * Returns false if required packages or connection string are missing.
+     */
+    init(): Promise<boolean>;
+    private initAzureExporter;
+    private initOTLP;
+    private initTelemetryClient;
+    /**
+     * Track a custom event (e.g. "WorkflowCompleted").
+     */
+    trackEvent(name: string, properties?: Record<string, string>): void;
+    /**
+     * Track an exception.
+     */
+    trackException(error: Error, properties?: Record<string, string>): void;
+    /**
+     * Track a numeric metric.
+     */
+    trackMetric(name: string, value: number, properties?: Record<string, string>): void;
+    /**
+     * Record a workflow execution as both a custom event and metric.
+     */
+    recordWorkflowExecution(workflowName: string, durationMs: number, success: boolean): void;
+    isInitialized(): boolean;
+    getStats(): AzureMonitorStats;
+    shutdown(): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * Extract the ingestion endpoint from an Application Insights connection string.
+     * Format: InstrumentationKey=...;IngestionEndpoint=https://...;...
+     */
+    private extractEndpoint;
+    /**
+     * Extract the instrumentation key from an Application Insights connection string.
+     */
+    private extractInstrumentationKey;
+}

package/dist/integrations/AzureMonitorIntegration.js

@@ -0,0 +1,254 @@
+/**
+ * Azure Monitor Integration for Blok
+ *
+ * Exports traces, metrics, and logs to Azure Application Insights via the
+ * Azure Monitor OpenTelemetry Exporter or the Application Insights SDK.
+ *
+ * Supports two modes:
+ * 1. **OTLP mode** (recommended) – Uses the generic OTLP exporter pointing at
+ *    the Azure Monitor OTLP endpoint.  Requires an Application Insights
+ *    connection string.
+ * 2. **Azure Exporter mode** – Uses `@azure/monitor-opentelemetry-exporter`
+ *    for native Azure integration with automatic sampling and live metrics.
+ *
+ * All Azure SDK dependencies are loaded lazily so the framework doesn't
+ * hard-depend on any Azure packages.  If the packages are not installed
+ * `init()` returns false and the integration is a no-op.
+ *
+ * @example
+ * ```typescript
+ * import { AzureMonitorIntegration } from "@blokjs/runner";
+ *
+ * const azure = new AzureMonitorIntegration({
+ *   connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING!,
+ *   serviceName: "blok-http",
+ * });
+ *
+ * await azure.init();
+ *
+ * // Track a custom event
+ * azure.trackEvent("WorkflowCompleted", { workflowName: "get-user", durationMs: "42" });
+ *
+ * // Track an exception
+ * azure.trackException(error, { workflowName: "get-user", nodeName: "fetch-db" });
+ *
+ * // Track a metric
+ * azure.trackMetric("WorkflowDuration", 42);
+ * ```
+ */
+export class AzureMonitorIntegration {
+    config;
+    initialized = false;
+    exporter = null;
+    tracingShutdown = null;
+    // Telemetry client for custom events / metrics (Application Insights SDK)
+    telemetryClient = null;
+    // stats
+    eventsTracked = 0;
+    exceptionsTracked = 0;
+    metricsTracked = 0;
+    constructor(config) {
+        this.config = {
+            connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
+            serviceVersion: "0.0.1",
+            environment: process.env.NODE_ENV || "development",
+            exportMode: "azure",
+            samplingRatio: 1.0,
+            enableLiveMetrics: false,
+            debug: false,
+            ...config,
+        };
+    }
+    /**
+     * Initialize Azure Monitor.
+     * Returns false if required packages or connection string are missing.
+     */
+    async init() {
+        if (this.initialized)
+            return true;
+        const connStr = this.config.connectionString;
+        if (!connStr)
+            return false;
+        try {
+            if (this.config.exportMode === "azure") {
+                return await this.initAzureExporter(connStr);
+            }
+            return await this.initOTLP(connStr);
+        }
+        catch {
+            return false;
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Azure Monitor exporter mode                                       */
+    /* ------------------------------------------------------------------ */
+    async initAzureExporter(connectionString) {
+        try {
+            // @ts-expect-error: optional peer dependency
+            const azureMod = await import("@azure/monitor-opentelemetry-exporter");
+            // The Azure trace exporter works via OpenTelemetry's TracerProvider.
+            // We bootstrap tracing with it by piping through our standard bootstrap
+            // path — the Azure exporter is OTLP-compatible.
+            const exporter = new azureMod.AzureMonitorTraceExporter({
+                connectionString,
+            });
+            this.exporter = exporter;
+            // Also try to set up a lightweight telemetry client for custom events
+            await this.initTelemetryClient(connectionString);
+            this.initialized = true;
+            return true;
+        }
+        catch {
+            // Fall back to OTLP mode
+            return this.initOTLP(connectionString);
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  OTLP mode (uses TracingBootstrap pointing at Azure endpoint)      */
+    /* ------------------------------------------------------------------ */
+    async initOTLP(connectionString) {
+        try {
+            // Extract ingestion endpoint from connection string
+            const endpoint = this.extractEndpoint(connectionString);
+            const instrumentationKey = this.extractInstrumentationKey(connectionString);
+            if (!endpoint || !instrumentationKey)
+                return false;
+            const { bootstrapTracing } = await import("../monitoring/TracingBootstrap");
+            const result = await bootstrapTracing({
+                serviceName: this.config.serviceName,
+                serviceVersion: this.config.serviceVersion,
+                exporter: "otlp",
+                endpoint: `${endpoint}/v2/track`,
+                headers: {
+                    "x-ms-instrumentationkey": instrumentationKey,
+                },
+                samplingRatio: this.config.samplingRatio,
+            });
+            if (!result)
+                return false;
+            this.tracingShutdown = result.shutdown;
+            await this.initTelemetryClient(connectionString);
+            this.initialized = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Lightweight telemetry client (custom events, metrics)             */
+    /* ------------------------------------------------------------------ */
+    async initTelemetryClient(connectionString) {
+        try {
+            // @ts-expect-error: optional peer dependency
+            const appInsights = await import("applicationinsights");
+            appInsights.setup(connectionString).setAutoCollectRequests(false).start();
+            const client = appInsights.defaultClient;
+            if (!client)
+                return;
+            this.telemetryClient = {
+                trackEvent: (event) => client.trackEvent(event),
+                trackException: (exc) => client.trackException(exc),
+                trackMetric: (metric) => client.trackMetric(metric),
+                flush: () => new Promise((resolve) => {
+                    client.flush({ callback: () => resolve() });
+                }),
+            };
+        }
+        catch {
+            // applicationinsights package not installed — custom events won't work
+            // but tracing via OTLP will still function
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Custom telemetry helpers                                          */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Track a custom event (e.g. "WorkflowCompleted").
+     */
+    trackEvent(name, properties) {
+        if (!this.telemetryClient)
+            return;
+        this.telemetryClient.trackEvent({ name, properties });
+        this.eventsTracked++;
+    }
+    /**
+     * Track an exception.
+     */
+    trackException(error, properties) {
+        if (!this.telemetryClient)
+            return;
+        this.telemetryClient.trackException({ exception: error, properties });
+        this.exceptionsTracked++;
+    }
+    /**
+     * Track a numeric metric.
+     */
+    trackMetric(name, value, properties) {
+        if (!this.telemetryClient)
+            return;
+        this.telemetryClient.trackMetric({ name, value, properties });
+        this.metricsTracked++;
+    }
+    /**
+     * Record a workflow execution as both a custom event and metric.
+     */
+    recordWorkflowExecution(workflowName, durationMs, success) {
+        this.trackEvent(success ? "WorkflowCompleted" : "WorkflowFailed", {
+            workflowName,
+            durationMs: String(durationMs),
+            environment: this.config.environment || "development",
+        });
+        this.trackMetric("WorkflowDuration", durationMs, { workflowName });
+        if (!success) {
+            this.trackMetric("WorkflowErrors", 1, { workflowName });
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Lifecycle                                                         */
+    /* ------------------------------------------------------------------ */
+    isInitialized() {
+        return this.initialized;
+    }
+    getStats() {
+        return {
+            initialized: this.initialized,
+            eventsTracked: this.eventsTracked,
+            exceptionsTracked: this.exceptionsTracked,
+            metricsTracked: this.metricsTracked,
+        };
+    }
+    async shutdown() {
+        if (this.tracingShutdown) {
+            await this.tracingShutdown();
+        }
+        if (this.exporter?.shutdown) {
+            await this.exporter.shutdown();
+        }
+        this.initialized = false;
+    }
+    async flush() {
+        if (this.telemetryClient) {
+            await this.telemetryClient.flush();
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Connection string parsing                                         */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Extract the ingestion endpoint from an Application Insights connection string.
+     * Format: InstrumentationKey=...;IngestionEndpoint=https://...;...
+     */
+    extractEndpoint(connectionString) {
+        const match = connectionString.match(/IngestionEndpoint=([^;]+)/i);
+        return match?.[1]?.replace(/\/$/, "") ?? null;
+    }
+    /**
+     * Extract the instrumentation key from an Application Insights connection string.
+     */
+    extractInstrumentationKey(connectionString) {
+        const match = connectionString.match(/InstrumentationKey=([^;]+)/i);
+        return match?.[1] ?? null;
+    }
+}
+//# sourceMappingURL=AzureMonitorIntegration.js.map

package/dist/integrations/AzureMonitorIntegration.js.map

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

package/dist/integrations/CloudWatchIntegration.d.ts

@@ -0,0 +1,135 @@
+/**
+ * AWS CloudWatch Integration for Blok
+ *
+ * Sends metrics to CloudWatch Metrics and logs to CloudWatch Logs.
+ * Traces are exported via OTLP to the AWS Distro for OpenTelemetry (ADOT)
+ * Collector, which forwards them to AWS X-Ray.
+ *
+ * Uses lazy dynamic imports so AWS SDK packages are optional peer
+ * dependencies.  If the SDK is not installed the integration silently
+ * degrades (init returns false).
+ *
+ * Supported transports:
+ * - **Metrics** – CloudWatch PutMetricData (via @aws-sdk/client-cloudwatch)
+ * - **Logs**    – CloudWatch Logs PutLogEvents (via @aws-sdk/client-cloudwatch-logs)
+ * - **Traces**  – OTLP → ADOT Collector → X-Ray (reuses TracingBootstrap)
+ *
+ * @example
+ * ```typescript
+ * import { CloudWatchIntegration } from "@blokjs/runner";
+ *
+ * const cw = new CloudWatchIntegration({
+ *   region: "us-east-1",
+ *   serviceName: "blok-http",
+ *   logGroupName: "/blok/workflows",
+ *   namespace: "Blok",
+ * });
+ *
+ * await cw.init();
+ *
+ * // Send a custom metric
+ * await cw.putMetric("WorkflowDuration", 42, "Milliseconds");
+ *
+ * // Send a structured log entry
+ * await cw.putLog({ level: "info", message: "workflow completed", workflowName: "get-user" });
+ *
+ * // Enable OTLP traces via ADOT Collector
+ * const cw = new CloudWatchIntegration({
+ *   region: "us-east-1",
+ *   serviceName: "blok-http",
+ *   enableTracing: true,
+ *   adotEndpoint: "http://localhost:4318/v1/traces",
+ * });
+ * ```
+ */
+export interface CloudWatchConfig {
+    /** AWS region (e.g. "us-east-1"). Falls back to AWS_REGION env var. */
+    region?: string;
+    /** Blok service name (used in metric dimensions and log metadata) */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Environment label */
+    environment?: string;
+    /** CloudWatch Logs log group name (default: "/blok/workflows") */
+    logGroupName?: string;
+    /** CloudWatch Logs log stream name (default: serviceName-<date>) */
+    logStreamName?: string;
+    /** CloudWatch Metrics namespace (default: "Blok") */
+    namespace?: string;
+    /** Enable OTLP trace export via ADOT Collector → X-Ray */
+    enableTracing?: boolean;
+    /** ADOT Collector OTLP endpoint (default: http://localhost:4318/v1/traces) */
+    adotEndpoint?: string;
+    /** Trace sampling ratio (0.0 – 1.0, default: 1.0) */
+    samplingRatio?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/** Supported CloudWatch metric units */
+export type CloudWatchUnit = "Seconds" | "Microseconds" | "Milliseconds" | "Bytes" | "Kilobytes" | "Megabytes" | "Gigabytes" | "Bits" | "Percent" | "Count" | "Count/Second" | "None";
+export interface CloudWatchLogEntry {
+    level: "debug" | "info" | "warn" | "error" | "fatal";
+    message: string;
+    [key: string]: unknown;
+}
+export interface CloudWatchStats {
+    initialized: boolean;
+    metricsPublished: number;
+    logsPublished: number;
+    metricErrors: number;
+    logErrors: number;
+    tracingEnabled: boolean;
+}
+export declare class CloudWatchIntegration {
+    private config;
+    private cwClient;
+    private cwLogsClient;
+    private initialized;
+    private tracingInitialized;
+    private tracingShutdown;
+    private sequenceToken;
+    private PutMetricDataCommand;
+    private PutLogEventsCommand;
+    private CreateLogGroupCommand;
+    private CreateLogStreamCommand;
+    private metricsPublished;
+    private logsPublished;
+    private metricErrors;
+    private logErrors;
+    constructor(config: CloudWatchConfig);
+    /**
+     * Initialize CloudWatch clients.
+     * Returns false if AWS SDK packages are not installed.
+     */
+    init(): Promise<boolean>;
+    /**
+     * Publish a custom metric to CloudWatch.
+     */
+    putMetric(metricName: string, value: number, unit?: CloudWatchUnit, dimensions?: Record<string, string>): Promise<boolean>;
+    /**
+     * Publish workflow execution metrics (duration + error count).
+     */
+    recordWorkflowExecution(workflowName: string, durationMs: number, success: boolean): Promise<void>;
+    /**
+     * Send a structured log entry to CloudWatch Logs.
+     */
+    putLog(entry: CloudWatchLogEntry): Promise<boolean>;
+    /**
+     * Log a workflow error to CloudWatch Logs.
+     */
+    logWorkflowError(error: Error, context: {
+        workflowName: string;
+        workflowPath: string;
+        requestId?: string;
+        nodeName?: string;
+    }): Promise<boolean>;
+    private initTracing;
+    isInitialized(): boolean;
+    isTracingEnabled(): boolean;
+    getStats(): CloudWatchStats;
+    shutdown(): Promise<void>;
+    flush(): Promise<void>;
+    private getLogStreamName;
+    private ensureLogDestination;
+}