@hatchet-dev/typescript-sdk 1.17.2 → 1.19.0

package/clients/event/event-client.d.ts

@@ -29,7 +29,15 @@ export declare class EventClient {
     tenantId: string;
     logger: Logger;
     constructor(config: ClientConfig, channel: Channel, factory: ClientFactory, api: HatchetClient['api']);
+    /**
+     * @important This method is instrumented by HatchetInstrumentor._patchPushEvent.
+     * Keep the signature in sync with the instrumentor wrapper.
+     */
     push<T>(type: string, input: T, options?: PushEventOptions): Promise<import("../../protoc/events/events").Event>;
+    /**
+     * @important This method is instrumented by HatchetInstrumentor._patchBulkPushEvent.
+     * Keep the signature in sync with the instrumentor wrapper.
+     */
     bulkPush<T>(type: string, inputs: EventWithMetadata<T>[], options?: PushEventOptions): Promise<import("../../protoc/events/events").Events>;
     putLog(taskRunExternalId: string, log: string, level?: LogLevel, taskRetryCount?: number, metadata?: Record<string, unknown>): Promise<void>;
     putStream(taskRunExternalId: string, data: string | Uint8Array, index: number | undefined): Promise<void>;

package/clients/event/event-client.js

@@ -30,6 +30,10 @@ class EventClient {
         this.api = api;
         this.tenantId = config.tenant_id;
     }
+    /**
+     * @important This method is instrumented by HatchetInstrumentor._patchPushEvent.
+     * Keep the signature in sync with the instrumentor wrapper.
+     */
     push(type, input, options = {}) {
         const namespacedType = (0, apply_namespace_1.applyNamespace)(type, this.config.namespace);
         const req = {
@@ -51,6 +55,10 @@ class EventClient {
             throw (0, hatchet_error_1.toHatchetError)(e);
         }
     }
+    /**
+     * @important This method is instrumented by HatchetInstrumentor._patchBulkPushEvent.
+     * Keep the signature in sync with the instrumentor wrapper.
+     */
     bulkPush(type, inputs, options = {}) {
         const namespacedType = (0, apply_namespace_1.applyNamespace)(type, this.config.namespace);
         const events = inputs.map((input) => {

package/clients/hatchet-client/client-config.d.ts

@@ -21,6 +21,25 @@ declare const ClientTLSConfigSchema: z.ZodObject<{
     key_file?: string | undefined;
     server_name?: string | undefined;
 }>;
+export declare const OpenTelemetryConfigSchema: z.ZodObject<{
+    /**
+     * List of attribute keys to exclude from spans.
+     * Useful for filtering sensitive or verbose data like payloads.
+     */
+    excludedAttributes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /**
+     * If true, includes the task name in the span name for task run spans.
+     * e.g., "hatchet.start_step_run.my_task" instead of "hatchet.start_step_run"
+     */
+    includeTaskNameInSpanName: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    excludedAttributes: string[];
+    includeTaskNameInSpanName: boolean;
+}, {
+    excludedAttributes?: string[] | undefined;
+    includeTaskNameInSpanName?: boolean | undefined;
+}>;
+export type OpenTelemetryConfig = z.infer<typeof OpenTelemetryConfigSchema>;
 export declare const ClientConfigSchema: z.ZodObject<{
     token: z.ZodString;
     tls_config: z.ZodObject<{
@@ -57,6 +76,24 @@ export declare const ClientConfigSchema: z.ZodObject<{
     log_level: z.ZodOptional<z.ZodEnum<["OFF", "DEBUG", "INFO", "WARN", "ERROR"]>>;
     tenant_id: z.ZodString;
     namespace: z.ZodOptional<z.ZodString>;
+    otel: z.ZodOptional<z.ZodObject<{
+        /**
+         * List of attribute keys to exclude from spans.
+         * Useful for filtering sensitive or verbose data like payloads.
+         */
+        excludedAttributes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /**
+         * If true, includes the task name in the span name for task run spans.
+         * e.g., "hatchet.start_step_run.my_task" instead of "hatchet.start_step_run"
+         */
+        includeTaskNameInSpanName: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        excludedAttributes: string[];
+        includeTaskNameInSpanName: boolean;
+    }, {
+        excludedAttributes?: string[] | undefined;
+        includeTaskNameInSpanName?: boolean | undefined;
+    }>>;
     middleware: z.ZodOptional<z.ZodObject<{
         before: z.ZodOptional<z.ZodAny>;
         after: z.ZodOptional<z.ZodAny>;
@@ -89,6 +126,10 @@ export declare const ClientConfigSchema: z.ZodObject<{
     } | undefined;
     log_level?: "OFF" | "DEBUG" | "INFO" | "WARN" | "ERROR" | undefined;
     namespace?: string | undefined;
+    otel?: {
+        excludedAttributes: string[];
+        includeTaskNameInSpanName: boolean;
+    } | undefined;
     middleware?: {
         before?: any;
         after?: any;
@@ -111,6 +152,10 @@ export declare const ClientConfigSchema: z.ZodObject<{
     } | undefined;
     log_level?: "OFF" | "DEBUG" | "INFO" | "WARN" | "ERROR" | undefined;
     namespace?: string | undefined;
+    otel?: {
+        excludedAttributes?: string[] | undefined;
+        includeTaskNameInSpanName?: boolean | undefined;
+    } | undefined;
     middleware?: {
         before?: any;
         after?: any;

package/clients/hatchet-client/client-config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClientConfigSchema = void 0;
+exports.ClientConfigSchema = exports.OpenTelemetryConfigSchema = void 0;
 const zod_1 = require("zod");
 const ClientTLSConfigSchema = zod_1.z.object({
     tls_strategy: zod_1.z.enum(['tls', 'mtls', 'none']).optional(),
@@ -13,6 +13,18 @@ const HealthcheckConfigSchema = zod_1.z.object({
     enabled: zod_1.z.boolean().optional().default(false),
     port: zod_1.z.number().optional().default(8001),
 });
+exports.OpenTelemetryConfigSchema = zod_1.z.object({
+    /**
+     * List of attribute keys to exclude from spans.
+     * Useful for filtering sensitive or verbose data like payloads.
+     */
+    excludedAttributes: zod_1.z.array(zod_1.z.string()).optional().default([]),
+    /**
+     * If true, includes the task name in the span name for task run spans.
+     * e.g., "hatchet.start_step_run.my_task" instead of "hatchet.start_step_run"
+     */
+    includeTaskNameInSpanName: zod_1.z.boolean().optional().default(false),
+});
 const TaskMiddlewareSchema = zod_1.z
     .object({
     before: zod_1.z.any().optional(),
@@ -29,6 +41,7 @@ exports.ClientConfigSchema = zod_1.z.object({
     log_level: zod_1.z.enum(['OFF', 'DEBUG', 'INFO', 'WARN', 'ERROR']).optional(),
     tenant_id: zod_1.z.string(),
     namespace: zod_1.z.string().optional(),
+    otel: exports.OpenTelemetryConfigSchema.optional(),
     middleware: TaskMiddlewareSchema,
     cancellation_grace_period: DurationMsSchema.optional().default(1000),
     cancellation_warning_threshold: DurationMsSchema.optional().default(300),

package/opentelemetry/hatchet-exporter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Hatchet OTLP Exporter
+ *
+ * Creates an OTLP gRPC trace exporter that sends spans to the Hatchet engine's
+ * collector endpoint, and a SpanProcessor that injects hatchet.* attributes
+ * into all child spans so they are queryable by the same attributes as the parent.
+ *
+ * This mirrors the Go SDK's EnableHatchetCollector() and the Python SDK's
+ * enable_hatchet_otel_collector option.
+ */
+import type { ClientConfig } from '../clients/hatchet-client/client-config';
+declare const BatchSpanProcessor: typeof import("@opentelemetry/sdk-trace-base").BatchSpanProcessor;
+type ReadableSpan = import('@opentelemetry/sdk-trace-base').ReadableSpan;
+type SdkSpan = import('@opentelemetry/sdk-trace-base').Span;
+/**
+ * HatchetAttributeSpanProcessor wraps a BatchSpanProcessor and injects
+ * hatchet.* attributes into every span created within a step run context.
+ * This ensures child spans are queryable by the same attributes (e.g.
+ * hatchet.step_run_id) as the parent span.
+ */
+declare class HatchetAttributeSpanProcessor extends BatchSpanProcessor {
+    onStart(span: SdkSpan): void;
+    onEnd(span: ReadableSpan): void;
+}
+export interface HatchetBspConfig {
+    scheduledDelayMillis?: number;
+    maxExportBatchSize?: number;
+    maxQueueSize?: number;
+}
+/**
+ * Creates a SpanProcessor that sends spans to the Hatchet engine's
+ * collector endpoint using the same connection settings as the Hatchet client.
+ * Pass the returned processor to BasicTracerProvider's `spanProcessors` option.
+ */
+export declare function createHatchetSpanProcessor(config: ClientConfig, bspConfig?: HatchetBspConfig): InstanceType<typeof HatchetAttributeSpanProcessor>;
+export {};

package/opentelemetry/hatchet-exporter.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Hatchet OTLP Exporter
+ *
+ * Creates an OTLP gRPC trace exporter that sends spans to the Hatchet engine's
+ * collector endpoint, and a SpanProcessor that injects hatchet.* attributes
+ * into all child spans so they are queryable by the same attributes as the parent.
+ *
+ * This mirrors the Go SDK's EnableHatchetCollector() and the Python SDK's
+ * enable_hatchet_otel_collector option.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHatchetSpanProcessor = createHatchetSpanProcessor;
+const hatchet_span_context_1 = require("./hatchet-span-context");
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let otelDiag;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    otelDiag = require('@opentelemetry/api').diag;
+}
+catch (_a) {
+    // best-effort
+}
+try {
+    require.resolve('@opentelemetry/exporter-trace-otlp-grpc');
+    require.resolve('@opentelemetry/sdk-trace-base');
+    require.resolve('@opentelemetry/core');
+}
+catch (_b) {
+    throw new Error('To use HatchetInstrumentor with enableHatchetCollector, you must install: ' +
+        'npm install @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/sdk-trace-base @opentelemetry/core');
+}
+/* eslint-disable @typescript-eslint/no-require-imports */
+// prettier-ignore
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
+// prettier-ignore
+const sdkTraceBase = require('@opentelemetry/sdk-trace-base');
+// prettier-ignore
+const { ExportResultCode } = require('@opentelemetry/core');
+/* eslint-enable @typescript-eslint/no-require-imports */
+const { BatchSpanProcessor } = sdkTraceBase;
+const GRPC_STATUS_UNIMPLEMENTED = 12;
+const RETRY_AFTER_MS = 5 * 60 * 1000;
+class HatchetExporterWrapper {
+    constructor(inner) {
+        this.retryAt = 0;
+        this.inner = inner;
+    }
+    export(spans, resultCallback) {
+        var _a;
+        if (this.retryAt > 0 && Date.now() < this.retryAt) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        try {
+            this.inner.export(spans, (result) => {
+                var _a;
+                if (result.code !== ExportResultCode.SUCCESS && result.error) {
+                    const err = result.error;
+                    if (err.code === GRPC_STATUS_UNIMPLEMENTED ||
+                        ((_a = err.message) === null || _a === void 0 ? void 0 : _a.toString().includes('UNIMPLEMENTED'))) {
+                        this.retryAt = Date.now() + RETRY_AFTER_MS;
+                        resultCallback({ code: ExportResultCode.SUCCESS });
+                        return;
+                    }
+                }
+                this.retryAt = 0;
+                resultCallback(result);
+            });
+        }
+        catch (e) {
+            if (e instanceof TypeError && ((_a = e.message) === null || _a === void 0 ? void 0 : _a.includes("reading 'name'"))) {
+                otelDiag === null || otelDiag === void 0 ? void 0 : otelDiag.error('hatchet instrumentation: OpenTelemetry package version mismatch. ' +
+                    '@opentelemetry/exporter-trace-otlp-grpc and @opentelemetry/sdk-trace-base must be ' +
+                    'from the same release set (1.x + 0.5x.x, or 2.x + 0.20x.x). ' +
+                    'See https://github.com/open-telemetry/opentelemetry-js#version-compatibility');
+                resultCallback({ code: ExportResultCode.SUCCESS });
+                return;
+            }
+            throw e;
+        }
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    forceFlush() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.inner).forceFlush) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+}
+/**
+ * HatchetAttributeSpanProcessor wraps a BatchSpanProcessor and injects
+ * hatchet.* attributes into every span created within a step run context.
+ * This ensures child spans are queryable by the same attributes (e.g.
+ * hatchet.step_run_id) as the parent span.
+ */
+class HatchetAttributeSpanProcessor extends BatchSpanProcessor {
+    onStart(span) {
+        const attrs = hatchet_span_context_1.hatchetSpanAttributes.getStore();
+        if (attrs) {
+            span.setAttributes(attrs);
+        }
+        super.onStart(span, undefined);
+    }
+    onEnd(span) {
+        super.onEnd(span);
+    }
+}
+function createHatchetExporter(config) {
+    const insecure = config.tls_config.tls_strategy === 'none';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const opts = {
+        url: `${insecure ? 'http' : 'https'}://${config.host_port}`,
+        metadata: { authorization: `Bearer ${config.token}` },
+    };
+    if (!insecure && config.tls_config.ca_file) {
+        try {
+            /* eslint-disable @typescript-eslint/no-require-imports */
+            const fs = require('fs');
+            const { ChannelCredentials } = require('nice-grpc');
+            /* eslint-enable @typescript-eslint/no-require-imports */
+            const rootCerts = fs.readFileSync(config.tls_config.ca_file);
+            opts.credentials = ChannelCredentials.createSsl(rootCerts);
+        }
+        catch (_a) {
+            // Fall through to default TLS handling
+        }
+    }
+    return new OTLPTraceExporter(opts);
+}
+/**
+ * Creates a SpanProcessor that sends spans to the Hatchet engine's
+ * collector endpoint using the same connection settings as the Hatchet client.
+ * Pass the returned processor to BasicTracerProvider's `spanProcessors` option.
+ */
+function createHatchetSpanProcessor(config, bspConfig) {
+    const inner = createHatchetExporter(config);
+    const exporter = new HatchetExporterWrapper(inner);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new HatchetAttributeSpanProcessor(exporter, {
+        scheduledDelayMillis: bspConfig === null || bspConfig === void 0 ? void 0 : bspConfig.scheduledDelayMillis,
+        maxExportBatchSize: bspConfig === null || bspConfig === void 0 ? void 0 : bspConfig.maxExportBatchSize,
+        maxQueueSize: bspConfig === null || bspConfig === void 0 ? void 0 : bspConfig.maxQueueSize,
+    });
+}

package/opentelemetry/hatchet-span-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared async context for propagating hatchet.* attributes to child spans.
+ *
+ * Uses AsyncLocalStorage to store hatchet attributes from the active task run
+ * span so that HatchetAttributeSpanProcessor can inject them into all child
+ * spans created within the same async context.
+ *
+ * This mirrors the Go SDK's context.WithValue approach and the Python SDK's
+ * ContextVar approach.
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+import type { Attributes } from '@opentelemetry/api';
+/**
+ * AsyncLocalStorage that holds hatchet.* attributes from the active
+ * hatchet task run span so they can be injected into child spans.
+ */
+export declare const hatchetSpanAttributes: AsyncLocalStorage<Attributes>;
+/**
+ * Store hatchet attributes in async context so the SpanProcessor
+ * can inject them into child spans.
+ */
+export declare function setHatchetSpanAttributes(attrs: Attributes): void;

package/opentelemetry/hatchet-span-context.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Shared async context for propagating hatchet.* attributes to child spans.
+ *
+ * Uses AsyncLocalStorage to store hatchet attributes from the active task run
+ * span so that HatchetAttributeSpanProcessor can inject them into all child
+ * spans created within the same async context.
+ *
+ * This mirrors the Go SDK's context.WithValue approach and the Python SDK's
+ * ContextVar approach.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hatchetSpanAttributes = void 0;
+exports.setHatchetSpanAttributes = setHatchetSpanAttributes;
+const async_hooks_1 = require("async_hooks");
+/**
+ * AsyncLocalStorage that holds hatchet.* attributes from the active
+ * hatchet task run span so they can be injected into child spans.
+ */
+exports.hatchetSpanAttributes = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Store hatchet attributes in async context so the SpanProcessor
+ * can inject them into child spans.
+ */
+function setHatchetSpanAttributes(attrs) {
+    exports.hatchetSpanAttributes.enterWith(attrs);
+}

package/opentelemetry/index.d.ts

@@ -0,0 +1,3 @@
+export { HatchetInstrumentor } from './instrumentor';
+export type { OpenTelemetryConfig } from './types';
+export { OTelAttribute, OTelAttributeType } from '../util/opentelemetry';

package/opentelemetry/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OTelAttribute = exports.HatchetInstrumentor = void 0;
+var instrumentor_1 = require("./instrumentor");
+Object.defineProperty(exports, "HatchetInstrumentor", { enumerable: true, get: function () { return instrumentor_1.HatchetInstrumentor; } });
+var opentelemetry_1 = require("../util/opentelemetry");
+Object.defineProperty(exports, "OTelAttribute", { enumerable: true, get: function () { return opentelemetry_1.OTelAttribute; } });

package/opentelemetry/instrumentor.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Hatchet OpenTelemetry Instrumentor
+ *
+ * This module provides automatic instrumentation for Hatchet SDK operations
+ * including workflow runs, event pushes, and step executions.
+ *
+ * The instrumentor follows the OpenTelemetry instrumentation pattern,
+ * patching module prototypes to automatically instrument all instances.
+ */
+import type { InstrumentationConfig } from '@opentelemetry/instrumentation';
+import type { ClientConfig } from '../clients/hatchet-client/client-config';
+import { OpenTelemetryConfig } from './types';
+import type { HatchetBspConfig } from './hatchet-exporter';
+declare const InstrumentationBase: typeof import("@opentelemetry/instrumentation").InstrumentationBase, InstrumentationNodeModuleDefinition: typeof import("@opentelemetry/instrumentation").InstrumentationNodeModuleDefinition;
+type HatchetInstrumentationConfig = OpenTelemetryConfig & InstrumentationConfig & {
+    /**
+     * Enable sending traces to the Hatchet engine's OTLP collector (default: true).
+     * Requires @opentelemetry/exporter-trace-otlp-grpc and @opentelemetry/sdk-trace-base.
+     * Connection settings (endpoint, token, TLS) are read from the provided clientConfig
+     * or from the same environment variables used by the Hatchet client.
+     * Set to false to disable.
+     */
+    enableHatchetCollector?: boolean;
+    /**
+     * The Hatchet ClientConfig to use for the collector connection.
+     * If not provided and enableHatchetCollector is true, config will be loaded
+     * from environment variables / .hatchet.yaml.
+     */
+    clientConfig?: ClientConfig;
+    /**
+     * Configuration for the BatchSpanProcessor that sends spans to the Hatchet collector.
+     */
+    bspConfig?: HatchetBspConfig;
+};
+/**
+ * HatchetInstrumentor provides OpenTelemetry instrumentation for Hatchet SDK v1.
+ *
+ * It automatically instruments:
+ * - Workflow runs (runWorkflow, runWorkflows)
+ * - Scheduled workflow runs (schedules.create)
+ * - Event pushes (push, bulkPush)
+ * - Step executions (handleStartStepRun, handleCancelStepRun)
+ *
+ * Traceparent context is automatically propagated through metadata.
+ *
+ * The instrumentor uses the global tracer/meter providers by default.
+ * Use `setTracerProvider()` and `setMeterProvider()` to configure custom providers.
+ */
+export declare class HatchetInstrumentor extends InstrumentationBase<HatchetInstrumentationConfig> {
+    constructor(config?: Partial<HatchetInstrumentationConfig>);
+    /**
+     * Sets up the Hatchet OTLP exporter on the current TracerProvider.
+     * Loads client config from environment if not provided.
+     */
+    private _setupHatchetCollector;
+    setConfig(config?: Partial<HatchetInstrumentationConfig>): void;
+    private readonly _getConfig;
+    protected init(): InstanceType<typeof InstrumentationNodeModuleDefinition>[];
+    private patchEventClient;
+    private unpatchEventClient;
+    private _patchPushEvent;
+    private _patchBulkPushEvent;
+    private patchAdminClient;
+    private unpatchAdminClient;
+    private _patchRunWorkflow;
+    private _patchRunWorkflows;
+    private patchWorker;
+    private unpatchWorker;
+    private _patchHandleStartStepRun;
+    private _patchHandleCancelStepRun;
+    private patchScheduleClient;
+    private unpatchScheduleClient;
+    private _patchScheduleCreate;
+    private patchDurableContext;
+    private unpatchDurableContext;
+    private _patchWaitFor;
+}
+export default HatchetInstrumentor;