@dexto/core 1.1.10 → 1.2.0

package/dist/telemetry/decorators.js

@@ -0,0 +1,157 @@
+import "../chunk-C6A6W6XS.js";
+import {
+  trace,
+  context,
+  SpanStatusCode,
+  SpanKind,
+  propagation
+} from "@opentelemetry/api";
+import { logger } from "../logger/index.js";
+import { hasActiveTelemetry, getBaggageValues } from "./utils.js";
+import { safeStringify } from "../utils/safe-stringify.js";
+function withSpan(options) {
+  return function(_target, propertyKey, descriptor) {
+    if (!descriptor || typeof descriptor === "number") return;
+    const originalMethod = descriptor.value;
+    const methodName = String(propertyKey);
+    descriptor.value = function(...args) {
+      if (options?.skipIfNoTelemetry && (!globalThis.__TELEMETRY__ || !hasActiveTelemetry())) {
+        return originalMethod.apply(this, args);
+      }
+      const tracer = trace.getTracer(options?.tracerName ?? "dexto");
+      let spanName = methodName;
+      let spanKind;
+      if (options) {
+        spanName = options.spanName ?? methodName;
+        if (options.spanKind !== void 0) {
+          spanKind = options.spanKind;
+        }
+      }
+      const spanOptions = {};
+      if (spanKind !== void 0) {
+        spanOptions.kind = spanKind;
+      }
+      const span = tracer.startSpan(spanName, spanOptions);
+      let ctx = trace.setSpan(context.active(), span);
+      args.forEach((arg, index) => {
+        span.setAttribute(`${spanName}.argument.${index}`, safeStringify(arg, 8192));
+      });
+      const { requestId, componentName, runId, threadId, resourceId } = getBaggageValues(ctx);
+      if (requestId) {
+        span.setAttribute("http.request_id", requestId);
+      }
+      if (threadId) {
+        span.setAttribute("threadId", threadId);
+      }
+      if (resourceId) {
+        span.setAttribute("resourceId", resourceId);
+      }
+      if (componentName) {
+        span.setAttribute("componentName", componentName);
+        if (runId !== void 0) {
+          span.setAttribute("runId", String(runId));
+        }
+      } else if (this && typeof this === "object") {
+        const contextObj = this;
+        const inferredName = contextObj.name ?? contextObj.constructor?.name;
+        if (inferredName) {
+          span.setAttribute("componentName", inferredName);
+        }
+        if (contextObj.runId) {
+          span.setAttribute("runId", contextObj.runId);
+        }
+        const baggageEntries = {};
+        if (inferredName !== void 0) {
+          baggageEntries.componentName = { value: String(inferredName) };
+        }
+        if (contextObj.runId !== void 0) {
+          baggageEntries.runId = { value: String(contextObj.runId) };
+        }
+        if (requestId !== void 0) {
+          baggageEntries["http.request_id"] = { value: String(requestId) };
+        }
+        if (threadId !== void 0) {
+          baggageEntries.threadId = { value: String(threadId) };
+        }
+        if (resourceId !== void 0) {
+          baggageEntries.resourceId = { value: String(resourceId) };
+        }
+        if (Object.keys(baggageEntries).length > 0) {
+          ctx = propagation.setBaggage(ctx, propagation.createBaggage(baggageEntries));
+        }
+      }
+      let result;
+      try {
+        result = context.with(ctx, () => originalMethod.apply(this, args));
+        if (result instanceof Promise) {
+          return result.then((resolvedValue) => {
+            span.setAttribute(
+              `${spanName}.result`,
+              safeStringify(resolvedValue, 8192)
+            );
+            return resolvedValue;
+          }).catch((error) => {
+            span.recordException(error);
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: error?.toString()
+            });
+            throw error;
+          }).finally(() => {
+            span.end();
+          });
+        }
+        span.setAttribute(`${spanName}.result`, safeStringify(result, 8192));
+        return result;
+      } catch (error) {
+        logger.error(
+          `withSpan: Error in method '${methodName}': ${error instanceof Error ? error.message : String(error)}`
+        );
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: error instanceof Error ? error.message : "Unknown error"
+        });
+        if (error instanceof Error) {
+          span.recordException(error);
+        }
+        throw error;
+      } finally {
+        if (!(result instanceof Promise)) {
+          span.end();
+        }
+      }
+    };
+    return descriptor;
+  };
+}
+function InstrumentClass(options) {
+  return function(target) {
+    const methods = Object.getOwnPropertyNames(target.prototype);
+    methods.forEach((method) => {
+      if (options?.excludeMethods?.includes(method) || method === "constructor") {
+        return;
+      }
+      if (options?.methodFilter && !options.methodFilter(method)) return;
+      const descriptor = Object.getOwnPropertyDescriptor(target.prototype, method);
+      if (descriptor && typeof descriptor.value === "function") {
+        Object.defineProperty(
+          target.prototype,
+          method,
+          withSpan({
+            spanName: options?.prefix ? `${options.prefix}.${method}` : method,
+            skipIfNoTelemetry: true,
+            spanKind: options?.spanKind || SpanKind.INTERNAL,
+            ...options?.tracerName !== void 0 && {
+              tracerName: options.tracerName
+            }
+          })(target, method, descriptor)
+        );
+      }
+    });
+    return target;
+  };
+}
+export {
+  InstrumentClass,
+  withSpan
+};

package/dist/telemetry/exporters.cjs

@@ -0,0 +1,108 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var exporters_exports = {};
+__export(exporters_exports, {
+  CompositeExporter: () => CompositeExporter
+});
+module.exports = __toCommonJS(exporters_exports);
+var import_core = require("@opentelemetry/core");
+function normalizeUrlPath(url) {
+  try {
+    const parsedUrl = new URL(url);
+    let pathname = parsedUrl.pathname.toLowerCase().trim();
+    if (pathname.endsWith("/")) {
+      pathname = pathname.slice(0, -1);
+    }
+    return pathname;
+  } catch (_e) {
+    let path = url.toLowerCase().trim();
+    if (path.endsWith("/")) {
+      path = path.slice(0, -1);
+    }
+    return path;
+  }
+}
+class CompositeExporter {
+  exporters;
+  constructor(exporters) {
+    this.exporters = exporters;
+  }
+  export(spans, resultCallback) {
+    const telemetryTraceIds = new Set(
+      spans.filter((span) => {
+        const attrs = span.attributes || {};
+        const relevantHttpAttributes = [
+          attrs["http.target"],
+          attrs["http.route"],
+          attrs["http.url"],
+          attrs["url.path"],
+          attrs["http.request_path"]
+        ];
+        const isTelemetrySpan = relevantHttpAttributes.some((attr) => {
+          if (typeof attr === "string") {
+            const normalizedPath = normalizeUrlPath(attr);
+            return normalizedPath === "/api/telemetry" || normalizedPath.startsWith("/api/telemetry/");
+          }
+          return false;
+        });
+        return isTelemetrySpan;
+      }).map((span) => span.spanContext().traceId)
+    );
+    const filteredSpans = spans.filter(
+      (span) => !telemetryTraceIds.has(span.spanContext().traceId)
+    );
+    if (filteredSpans.length === 0) {
+      resultCallback({ code: import_core.ExportResultCode.SUCCESS });
+      return;
+    }
+    void Promise.all(
+      this.exporters.map(
+        (exporter) => new Promise((resolve) => {
+          if (exporter.export) {
+            exporter.export(filteredSpans, resolve);
+          } else {
+            resolve({ code: import_core.ExportResultCode.FAILED });
+          }
+        })
+      )
+    ).then((results) => {
+      const hasError = results.some((r) => r.code === import_core.ExportResultCode.FAILED);
+      resultCallback({
+        code: hasError ? import_core.ExportResultCode.FAILED : import_core.ExportResultCode.SUCCESS
+      });
+    }).catch((error) => {
+      console.error("[CompositeExporter] Export error:", error);
+      resultCallback({ code: import_core.ExportResultCode.FAILED });
+    });
+  }
+  shutdown() {
+    return Promise.all(this.exporters.map((e) => e.shutdown?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+  forceFlush() {
+    return Promise.all(this.exporters.map((e) => e.forceFlush?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CompositeExporter
+});

package/dist/telemetry/exporters.d.ts

@@ -0,0 +1,29 @@
+import type { ExportResult } from '@opentelemetry/core';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+/**
+ * CompositeExporter wraps multiple span exporters and provides two key features:
+ *
+ * 1. **Multi-exporter support**: Exports spans to multiple destinations in parallel
+ *    (e.g., console for development + OTLP for production monitoring)
+ *
+ * 2. **Recursive telemetry filtering**: Prevents telemetry infinity loops by filtering
+ *    out spans from `/api/telemetry` endpoints. Without this, telemetry API calls would
+ *    generate spans, which would be exported via HTTP to `/api/telemetry`, generating
+ *    more spans, creating an infinite loop.
+ *
+ * @example
+ * ```typescript
+ * const exporter = new CompositeExporter([
+ *   new ConsoleSpanExporter(),
+ *   new OTLPHttpExporter({ url: 'http://localhost:4318/v1/traces' })
+ * ]);
+ * ```
+ */
+export declare class CompositeExporter implements SpanExporter {
+    private exporters;
+    constructor(exporters: SpanExporter[]);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=exporters.d.ts.map

package/dist/telemetry/exporters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporters.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA0BhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IAClD,OAAO,CAAC,SAAS,CAAiB;gBAEtB,SAAS,EAAE,YAAY,EAAE;IAIrC,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAiEnF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAK9B"}

package/dist/telemetry/exporters.js

@@ -0,0 +1,85 @@
+import "../chunk-C6A6W6XS.js";
+import { ExportResultCode } from "@opentelemetry/core";
+function normalizeUrlPath(url) {
+  try {
+    const parsedUrl = new URL(url);
+    let pathname = parsedUrl.pathname.toLowerCase().trim();
+    if (pathname.endsWith("/")) {
+      pathname = pathname.slice(0, -1);
+    }
+    return pathname;
+  } catch (_e) {
+    let path = url.toLowerCase().trim();
+    if (path.endsWith("/")) {
+      path = path.slice(0, -1);
+    }
+    return path;
+  }
+}
+class CompositeExporter {
+  exporters;
+  constructor(exporters) {
+    this.exporters = exporters;
+  }
+  export(spans, resultCallback) {
+    const telemetryTraceIds = new Set(
+      spans.filter((span) => {
+        const attrs = span.attributes || {};
+        const relevantHttpAttributes = [
+          attrs["http.target"],
+          attrs["http.route"],
+          attrs["http.url"],
+          attrs["url.path"],
+          attrs["http.request_path"]
+        ];
+        const isTelemetrySpan = relevantHttpAttributes.some((attr) => {
+          if (typeof attr === "string") {
+            const normalizedPath = normalizeUrlPath(attr);
+            return normalizedPath === "/api/telemetry" || normalizedPath.startsWith("/api/telemetry/");
+          }
+          return false;
+        });
+        return isTelemetrySpan;
+      }).map((span) => span.spanContext().traceId)
+    );
+    const filteredSpans = spans.filter(
+      (span) => !telemetryTraceIds.has(span.spanContext().traceId)
+    );
+    if (filteredSpans.length === 0) {
+      resultCallback({ code: ExportResultCode.SUCCESS });
+      return;
+    }
+    void Promise.all(
+      this.exporters.map(
+        (exporter) => new Promise((resolve) => {
+          if (exporter.export) {
+            exporter.export(filteredSpans, resolve);
+          } else {
+            resolve({ code: ExportResultCode.FAILED });
+          }
+        })
+      )
+    ).then((results) => {
+      const hasError = results.some((r) => r.code === ExportResultCode.FAILED);
+      resultCallback({
+        code: hasError ? ExportResultCode.FAILED : ExportResultCode.SUCCESS
+      });
+    }).catch((error) => {
+      console.error("[CompositeExporter] Export error:", error);
+      resultCallback({ code: ExportResultCode.FAILED });
+    });
+  }
+  shutdown() {
+    return Promise.all(this.exporters.map((e) => e.shutdown?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+  forceFlush() {
+    return Promise.all(this.exporters.map((e) => e.forceFlush?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+}
+export {
+  CompositeExporter
+};

package/dist/telemetry/index.cjs

@@ -0,0 +1,28 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var telemetry_exports = {};
+__export(telemetry_exports, {
+  Telemetry: () => import_telemetry.Telemetry
+});
+module.exports = __toCommonJS(telemetry_exports);
+var import_telemetry = require("./telemetry.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Telemetry
+});

package/dist/telemetry/index.d.ts

@@ -0,0 +1,2 @@
+export { Telemetry } from './telemetry.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,5 @@
+import "../chunk-C6A6W6XS.js";
+import { Telemetry } from "./telemetry.js";
+export {
+  Telemetry
+};

package/dist/telemetry/schemas.cjs

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schemas_exports = {};
+__export(schemas_exports, {
+  OtelConfigurationSchema: () => OtelConfigurationSchema
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_zod = require("zod");
+const OtelConfigurationSchema = import_zod.z.object({
+  serviceName: import_zod.z.string().optional(),
+  enabled: import_zod.z.boolean().optional(),
+  tracerName: import_zod.z.string().optional(),
+  // TODO (Telemetry): Implement sampling support in Phase 5
+  // Currently sampling schema is defined but not implemented in telemetry.ts
+  // See feature-plans/telemetry.md Phase 5 for implementation details
+  // sampling: z
+  //     .discriminatedUnion('type', [
+  //         z.object({
+  //             type: z.literal('ratio'),
+  //             probability: z.number().min(0).max(1),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_on'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_off'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('parent_based'),
+  //             root: z.object({
+  //                 probability: z.number().min(0).max(1),
+  //             }),
+  //         }),
+  //     ])
+  //     .optional(),
+  export: import_zod.z.union([
+    import_zod.z.object({
+      type: import_zod.z.literal("otlp"),
+      protocol: import_zod.z.enum(["grpc", "http"]).optional(),
+      endpoint: import_zod.z.union([
+        import_zod.z.string().url(),
+        import_zod.z.string().regex(/^[\w.-]+:\d+$/)
+        // host:port
+      ]).optional(),
+      headers: import_zod.z.record(import_zod.z.string()).optional()
+    }),
+    import_zod.z.object({
+      type: import_zod.z.literal("console")
+    })
+  ]).optional()
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OtelConfigurationSchema
+});

package/dist/telemetry/schemas.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const OtelConfigurationSchema: z.ZodObject<{
+    serviceName: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    tracerName: z.ZodOptional<z.ZodString>;
+    export: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"otlp">;
+        protocol: z.ZodOptional<z.ZodEnum<["grpc", "http"]>>;
+        endpoint: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString]>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    }, {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"console">;
+    }, "strip", z.ZodTypeAny, {
+        type: "console";
+    }, {
+        type: "console";
+    }>]>>;
+}, "strip", z.ZodTypeAny, {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    tracerName?: string | undefined;
+    export?: {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    } | {
+        type: "console";
+    } | undefined;
+}, {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    tracerName?: string | undefined;
+    export?: {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    } | {
+        type: "console";
+    } | undefined;
+}>;
+export type OtelConfiguration = z.output<typeof OtelConfigurationSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/telemetry/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/telemetry/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6ClC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/telemetry/schemas.js

@@ -0,0 +1,48 @@
+import "../chunk-C6A6W6XS.js";
+import { z } from "zod";
+const OtelConfigurationSchema = z.object({
+  serviceName: z.string().optional(),
+  enabled: z.boolean().optional(),
+  tracerName: z.string().optional(),
+  // TODO (Telemetry): Implement sampling support in Phase 5
+  // Currently sampling schema is defined but not implemented in telemetry.ts
+  // See feature-plans/telemetry.md Phase 5 for implementation details
+  // sampling: z
+  //     .discriminatedUnion('type', [
+  //         z.object({
+  //             type: z.literal('ratio'),
+  //             probability: z.number().min(0).max(1),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_on'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_off'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('parent_based'),
+  //             root: z.object({
+  //                 probability: z.number().min(0).max(1),
+  //             }),
+  //         }),
+  //     ])
+  //     .optional(),
+  export: z.union([
+    z.object({
+      type: z.literal("otlp"),
+      protocol: z.enum(["grpc", "http"]).optional(),
+      endpoint: z.union([
+        z.string().url(),
+        z.string().regex(/^[\w.-]+:\d+$/)
+        // host:port
+      ]).optional(),
+      headers: z.record(z.string()).optional()
+    }),
+    z.object({
+      type: z.literal("console")
+    })
+  ]).optional()
+});
+export {
+  OtelConfigurationSchema
+};