@cloudbase/agent-observability 1.0.1-alpha.9

package/dist/index.js

@@ -0,0 +1,732 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+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);
+
+// src/core/constants.ts
+var import_openinference_semantic_conventions, OtelSpanAttributes;
+var init_constants = __esm({
+  "src/core/constants.ts"() {
+    "use strict";
+    import_openinference_semantic_conventions = require("@arizeai/openinference-semantic-conventions");
+    OtelSpanAttributes = {
+      // OpenInference - re-export all standard conventions
+      ...import_openinference_semantic_conventions.SemanticConventions,
+      // AG-Kit Trace attributes (non-standard)
+      TRACE_NAME: "trace.name",
+      TRACE_TAGS: "trace.tags",
+      TRACE_PUBLIC: "trace.public",
+      TRACE_METADATA: "trace.metadata",
+      TRACE_INPUT: "trace.input",
+      TRACE_OUTPUT: "trace.output",
+      // AG-Kit Observation attributes (non-standard)
+      OBSERVATION_TYPE: "observation.type",
+      OBSERVATION_LEVEL: "observation.level",
+      OBSERVATION_STATUS_MESSAGE: "observation.status_message",
+      OBSERVATION_INPUT: "observation.input",
+      OBSERVATION_OUTPUT: "observation.output",
+      OBSERVATION_METADATA: "observation.metadata",
+      // AG-Kit LLM-specific (non-standard)
+      LLM_COMPLETION_START_TIME: "llm.completion_start_time",
+      LLM_MODEL_PARAMETERS: "llm.model_parameters",
+      LLM_USAGE_DETAILS: "llm.usage_details",
+      LLM_COST_DETAILS: "llm.cost_details",
+      // AG-Kit Retriever-specific (non-standard)
+      RETRIEVER_NAME: "retriever.name",
+      RETRIEVER_QUERY: "retriever.query",
+      RETRIEVER_INDEX_ID: "retriever.index_id",
+      RETRIEVER_TOP_K: "retriever.top_k",
+      // AG-Kit General (non-standard)
+      ENVIRONMENT: "environment",
+      RELEASE: "release",
+      VERSION: "version"
+    };
+  }
+});
+
+// src/core/attributes.ts
+function createTraceAttributes({
+  name,
+  userId,
+  sessionId,
+  version,
+  release,
+  input,
+  output,
+  metadata,
+  tags,
+  environment,
+  public: isPublic
+} = {}) {
+  const attributes = {
+    [OtelSpanAttributes.TRACE_NAME]: name,
+    // Use OpenInference standard attributes for user and session
+    [OtelSpanAttributes.USER_ID]: userId,
+    [OtelSpanAttributes.SESSION_ID]: sessionId,
+    [OtelSpanAttributes.VERSION]: version,
+    [OtelSpanAttributes.RELEASE]: release,
+    [OtelSpanAttributes.TRACE_INPUT]: _serialize(input),
+    [OtelSpanAttributes.TRACE_OUTPUT]: _serialize(output),
+    [OtelSpanAttributes.TRACE_TAGS]: tags,
+    [OtelSpanAttributes.ENVIRONMENT]: environment,
+    [OtelSpanAttributes.TRACE_PUBLIC]: isPublic,
+    ..._flattenAndSerializeMetadata(metadata, OtelSpanAttributes.TRACE_METADATA)
+  };
+  return Object.fromEntries(
+    Object.entries(attributes).filter(([_, v]) => v != null)
+  );
+}
+function createObservationAttributes(type, attributes) {
+  const {
+    metadata,
+    input,
+    output,
+    level,
+    statusMessage,
+    version,
+    completionStartTime,
+    model,
+    modelParameters,
+    usageDetails
+  } = attributes;
+  const otelAttributes = {
+    [import_openinference_semantic_conventions2.SemanticConventions.OPENINFERENCE_SPAN_KIND]: type.toUpperCase(),
+    [OtelSpanAttributes.OBSERVATION_TYPE]: type,
+    [OtelSpanAttributes.OBSERVATION_LEVEL]: level,
+    [OtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: statusMessage,
+    [OtelSpanAttributes.VERSION]: version,
+    // Use OpenInference input.value convention
+    [import_openinference_semantic_conventions2.SemanticConventions.INPUT_VALUE]: _serialize(input),
+    // Also set legacy agkit.observation.input for compatibility
+    [OtelSpanAttributes.OBSERVATION_INPUT]: _serialize(input),
+    // Use OpenInference output.value convention
+    [import_openinference_semantic_conventions2.SemanticConventions.OUTPUT_VALUE]: _serialize(output),
+    // Also set legacy agkit.observation.output for compatibility
+    [OtelSpanAttributes.OBSERVATION_OUTPUT]: _serialize(output)
+  };
+  if (type === "llm") {
+    if (model) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_MODEL_NAME] = model;
+    }
+    if (modelParameters) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_INVOCATION_PARAMETERS] = _serialize(modelParameters);
+      otelAttributes[OtelSpanAttributes.LLM_MODEL_PARAMETERS] = _serialize(modelParameters);
+    }
+    if (usageDetails) {
+      if (typeof usageDetails === "object") {
+        const usage = usageDetails;
+        if (usage.promptTokens !== void 0) {
+          otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_TOKEN_COUNT_PROMPT] = usage.promptTokens;
+        }
+        if (usage.completionTokens !== void 0) {
+          otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_TOKEN_COUNT_COMPLETION] = usage.completionTokens;
+        }
+        if (usage.totalTokens !== void 0) {
+          otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_TOKEN_COUNT_TOTAL] = usage.totalTokens;
+        }
+      }
+      otelAttributes[OtelSpanAttributes.LLM_USAGE_DETAILS] = _serialize(usageDetails);
+    }
+    if (completionStartTime) {
+      otelAttributes[OtelSpanAttributes.LLM_COMPLETION_START_TIME] = _serialize(completionStartTime);
+    }
+  }
+  if (type === "embedding") {
+    if (model) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.EMBEDDING_MODEL_NAME] = model;
+    }
+    if (modelParameters) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_INVOCATION_PARAMETERS] = _serialize(modelParameters);
+    }
+  }
+  const metadataAttrs = _flattenAndSerializeMetadata(
+    metadata,
+    import_openinference_semantic_conventions2.SemanticConventions.METADATA
+  );
+  Object.assign(otelAttributes, metadataAttrs);
+  const obsetvabilityMetadataAttrs = _flattenAndSerializeMetadata(
+    metadata,
+    OtelSpanAttributes.OBSERVATION_METADATA
+  );
+  Object.assign(otelAttributes, obsetvabilityMetadataAttrs);
+  return Object.fromEntries(
+    Object.entries(otelAttributes).filter(([_, v]) => v != null)
+  );
+}
+function _serialize(obj) {
+  try {
+    if (typeof obj === "string") return obj;
+    if (obj instanceof Date) return obj.toISOString();
+    return obj != null ? JSON.stringify(obj) : void 0;
+  } catch {
+    return "<failed to serialize>";
+  }
+}
+function _flattenAndSerializeMetadata(metadata, prefix) {
+  const metadataAttributes = {};
+  if (metadata === void 0 || metadata === null) {
+    return metadataAttributes;
+  }
+  if (typeof metadata !== "object" || Array.isArray(metadata)) {
+    const serialized = _serialize(metadata);
+    if (serialized) {
+      metadataAttributes[prefix] = serialized;
+    }
+  } else {
+    for (const [key, value] of Object.entries(metadata)) {
+      const serialized = typeof value === "string" ? value : _serialize(value);
+      if (serialized) {
+        metadataAttributes[`${prefix}.${key}`] = serialized;
+      }
+    }
+  }
+  return metadataAttributes;
+}
+var import_openinference_semantic_conventions2;
+var init_attributes = __esm({
+  "src/core/attributes.ts"() {
+    "use strict";
+    init_constants();
+    import_openinference_semantic_conventions2 = require("@arizeai/openinference-semantic-conventions");
+  }
+});
+
+// src/core/tracerProvider.ts
+function createState() {
+  return {
+    isolatedTracerProvider: null
+  };
+}
+function getObservabilityGlobalState() {
+  const initialState = createState();
+  try {
+    const g = globalThis;
+    if (typeof g !== "object" || g === null) {
+      console.warn(
+        "[Observability] globalThis is not available, using fallback state"
+      );
+      return initialState;
+    }
+    if (!g[OBSERVABILITY_GLOBAL_SYMBOL]) {
+      Object.defineProperty(g, OBSERVABILITY_GLOBAL_SYMBOL, {
+        value: initialState,
+        writable: false,
+        configurable: false,
+        enumerable: false
+      });
+    }
+    return g[OBSERVABILITY_GLOBAL_SYMBOL];
+  } catch (err) {
+    console.error(
+      `[Observability] Failed to access global state: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return initialState;
+  }
+}
+function setTracerProvider(provider) {
+  getObservabilityGlobalState().isolatedTracerProvider = provider;
+}
+function getTracerProvider() {
+  const { isolatedTracerProvider } = getObservabilityGlobalState();
+  if (isolatedTracerProvider) return isolatedTracerProvider;
+  return import_api.trace.getTracerProvider();
+}
+function getTracer() {
+  return getTracerProvider().getTracer(
+    OBSERVABILITY_SDK_NAME,
+    OBSERVABILITY_SDK_VERSION
+  );
+}
+var import_api, OBSERVABILITY_GLOBAL_SYMBOL, OBSERVABILITY_SDK_NAME, OBSERVABILITY_SDK_VERSION;
+var init_tracerProvider = __esm({
+  "src/core/tracerProvider.ts"() {
+    "use strict";
+    import_api = require("@opentelemetry/api");
+    OBSERVABILITY_GLOBAL_SYMBOL = /* @__PURE__ */ Symbol.for("observability");
+    OBSERVABILITY_SDK_NAME = "ag-kit-observability";
+    OBSERVABILITY_SDK_VERSION = "0.1.0";
+  }
+});
+
+// src/core/spanWrapper.ts
+var BaseObservation, ObservationSpan, ObservationLLM, ObservationEmbedding, ObservationAgent, ObservationTool, ObservationChain, ObservationRetriever, ObservationReranker, ObservationEvaluator, ObservationGuardrail;
+var init_spanWrapper = __esm({
+  "src/core/spanWrapper.ts"() {
+    "use strict";
+    init_attributes();
+    init_tracerProvider();
+    BaseObservation = class {
+      /** The underlying OpenTelemetry span */
+      otelSpan;
+      /** The observation type */
+      type;
+      /** The span ID from the OpenTelemetry span context */
+      id;
+      /** The trace ID from the OpenTelemetry span context */
+      traceId;
+      constructor(params) {
+        this.otelSpan = params.otelSpan;
+        this.id = params.otelSpan.spanContext().spanId;
+        this.traceId = params.otelSpan.spanContext().traceId;
+        this.type = params.type;
+        if (params.attributes) {
+          this.otelSpan.setAttributes(
+            createObservationAttributes(params.type, params.attributes)
+          );
+        }
+      }
+      /** Gets the AG-Kit OpenTelemetry tracer instance */
+      get tracer() {
+        return getTracer();
+      }
+      /**
+       * Ends the observation, marking it as complete.
+       *
+       * @param endTime - Optional end time, defaults to current time
+       */
+      end(endTime) {
+        this.otelSpan.end(endTime);
+      }
+      /**
+       * Updates the OTEL span attributes.
+       *
+       * @param attributes - Attributes to update
+       * @internal
+       */
+      updateOtelSpanAttributes(attributes) {
+        this.otelSpan.setAttributes(
+          createObservationAttributes(this.type, attributes)
+        );
+      }
+      /**
+       * Updates the parent trace with new attributes.
+       *
+       * @param attributes - Trace attributes to set
+       * @returns This observation for method chaining
+       */
+      updateTrace(attributes) {
+        this.otelSpan.setAttributes(createTraceAttributes(attributes));
+        return this;
+      }
+      startObservation(name, attributes, options) {
+        const { startObservation: startObs } = (init_src(), __toCommonJS(src_exports));
+        const { asType = "span" } = options || {};
+        return startObs(name, attributes, {
+          asType,
+          parentSpanContext: this.otelSpan.spanContext()
+        });
+      }
+    };
+    ObservationSpan = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "span" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationLLM = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "llm" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationEmbedding = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "embedding" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationAgent = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "agent" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationTool = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "tool" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationChain = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "chain" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationRetriever = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "retriever" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationReranker = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "reranker" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationEvaluator = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "evaluator" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+    ObservationGuardrail = class extends BaseObservation {
+      constructor(params) {
+        super({ ...params, type: "guardrail" });
+      }
+      update(attributes) {
+        super.updateOtelSpanAttributes(attributes);
+        return this;
+      }
+    };
+  }
+});
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ObservationAgent: () => ObservationAgent,
+  ObservationChain: () => ObservationChain,
+  ObservationEmbedding: () => ObservationEmbedding,
+  ObservationEvaluator: () => ObservationEvaluator,
+  ObservationGuardrail: () => ObservationGuardrail,
+  ObservationLLM: () => ObservationLLM,
+  ObservationReranker: () => ObservationReranker,
+  ObservationRetriever: () => ObservationRetriever,
+  ObservationSpan: () => ObservationSpan,
+  ObservationTool: () => ObservationTool,
+  createObservationAttributes: () => createObservationAttributes,
+  createTraceAttributes: () => createTraceAttributes,
+  getActiveSpanId: () => getActiveSpanId,
+  getActiveTraceId: () => getActiveTraceId,
+  getTracer: () => getTracer,
+  getTracerProvider: () => getTracerProvider,
+  observe: () => observe,
+  setTracerProvider: () => setTracerProvider,
+  startActiveObservation: () => startActiveObservation,
+  startObservation: () => startObservation,
+  updateActiveObservation: () => updateActiveObservation,
+  updateActiveTrace: () => updateActiveTrace
+});
+module.exports = __toCommonJS(src_exports);
+function createOtelSpan(params) {
+  return getTracer().startSpan(
+    params.name,
+    { startTime: params.startTime },
+    createParentContext(params.parentSpanContext)
+  );
+}
+function createParentContext(parentSpanContext) {
+  if (!parentSpanContext) return;
+  return import_api2.trace.setSpanContext(import_api2.context.active(), parentSpanContext);
+}
+function startObservation(name, attributes, options) {
+  const { asType = "span", ...observationOptions } = options || {};
+  const otelSpan = createOtelSpan({
+    name,
+    ...observationOptions
+  });
+  switch (asType) {
+    case "llm":
+      return new ObservationLLM({
+        otelSpan,
+        attributes
+      });
+    case "embedding":
+      return new ObservationEmbedding({
+        otelSpan,
+        attributes
+      });
+    case "agent":
+      return new ObservationAgent({
+        otelSpan,
+        attributes
+      });
+    case "tool":
+      return new ObservationTool({
+        otelSpan,
+        attributes
+      });
+    case "chain":
+      return new ObservationChain({
+        otelSpan,
+        attributes
+      });
+    case "retriever":
+      return new ObservationRetriever({
+        otelSpan,
+        attributes
+      });
+    case "reranker":
+      return new ObservationReranker({
+        otelSpan,
+        attributes
+      });
+    case "evaluator":
+      return new ObservationEvaluator({
+        otelSpan,
+        attributes
+      });
+    case "guardrail":
+      return new ObservationGuardrail({
+        otelSpan,
+        attributes
+      });
+    case "span":
+    default:
+      return new ObservationSpan({
+        otelSpan,
+        attributes
+      });
+  }
+}
+function updateActiveTrace(attributes) {
+  const span = import_api2.trace.getActiveSpan();
+  if (!span) {
+    console.warn(
+      "[Observability] No active OTEL span in context. Skipping trace update."
+    );
+    return;
+  }
+  span.setAttributes(createTraceAttributes(attributes));
+}
+function getActiveTraceId() {
+  return import_api2.trace.getActiveSpan()?.spanContext().traceId;
+}
+function getActiveSpanId() {
+  return import_api2.trace.getActiveSpan()?.spanContext().spanId;
+}
+function wrapPromise(promise, span, endOnExit) {
+  return promise.then(
+    (value) => {
+      if (endOnExit !== false) {
+        span.end();
+      }
+      return value;
+    },
+    (err) => {
+      span.setStatus({
+        code: import_api2.SpanStatusCode.ERROR,
+        message: err instanceof Error ? err.message : "Unknown error"
+      });
+      if (endOnExit !== false) {
+        span.end();
+      }
+      throw err;
+    }
+  );
+}
+function startActiveObservation(name, fn, options) {
+  const { asType = "span", endOnExit, ...observationOptions } = options || {};
+  return getTracer().startActiveSpan(
+    name,
+    { startTime: observationOptions?.startTime },
+    createParentContext(observationOptions?.parentSpanContext) ?? import_api2.context.active(),
+    (span) => {
+      try {
+        let observation;
+        switch (asType) {
+          case "llm":
+            observation = new ObservationLLM({ otelSpan: span });
+            break;
+          case "embedding":
+            observation = new ObservationEmbedding({ otelSpan: span });
+            break;
+          case "agent":
+            observation = new ObservationAgent({ otelSpan: span });
+            break;
+          case "tool":
+            observation = new ObservationTool({ otelSpan: span });
+            break;
+          case "chain":
+            observation = new ObservationChain({ otelSpan: span });
+            break;
+          case "retriever":
+            observation = new ObservationRetriever({ otelSpan: span });
+            break;
+          case "reranker":
+            observation = new ObservationReranker({ otelSpan: span });
+            break;
+          case "evaluator":
+            observation = new ObservationEvaluator({ otelSpan: span });
+            break;
+          case "guardrail":
+            observation = new ObservationGuardrail({ otelSpan: span });
+            break;
+          case "span":
+          default:
+            observation = new ObservationSpan({ otelSpan: span });
+        }
+        const result = fn(observation);
+        if (result instanceof Promise) {
+          return wrapPromise(
+            result,
+            span,
+            endOnExit
+          );
+        } else {
+          if (endOnExit !== false) {
+            span.end();
+          }
+          return result;
+        }
+      } catch (err) {
+        span.setStatus({
+          code: import_api2.SpanStatusCode.ERROR,
+          message: err instanceof Error ? err.message : "Unknown error"
+        });
+        if (endOnExit !== false) {
+          span.end();
+        }
+        throw err;
+      }
+    }
+  );
+}
+function updateActiveObservation(attributes) {
+  const span = import_api2.trace.getActiveSpan();
+  if (!span) {
+    console.warn(
+      "[Observability] No active OTEL span in context. Skipping observation update."
+    );
+    return;
+  }
+  span.setAttributes(createObservationAttributes("span", attributes));
+}
+function _captureArguments(args) {
+  if (args.length === 0) return {};
+  if (args.length === 1) return { arg: args[0] };
+  return { args };
+}
+function observe(fn, options = {}) {
+  const {
+    asType = "span",
+    captureInput = true,
+    captureOutput = true,
+    ...observationOptions
+  } = options;
+  const wrappedFunction = function(...args) {
+    const name = fn.name || "anonymous-function";
+    const inputData = captureInput ? _captureArguments(args) : void 0;
+    const observation = startObservation(
+      name,
+      inputData ? { input: inputData } : {},
+      {
+        ...observationOptions,
+        asType
+      }
+    );
+    const activeContext = import_api2.trace.setSpan(import_api2.context.active(), observation.otelSpan);
+    const result = import_api2.context.with(activeContext, () => fn.apply(this, args));
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => {
+          if (captureOutput) {
+            observation.update({ output: value });
+          }
+          observation.end();
+          return value;
+        },
+        (err) => {
+          observation.update({
+            level: "ERROR",
+            statusMessage: err instanceof Error ? err.message : "Unknown error"
+          });
+          observation.end();
+          throw err;
+        }
+      );
+    }
+    if (captureOutput) {
+      observation.update({ output: result });
+    }
+    observation.end();
+    return result;
+  };
+  Object.defineProperty(wrappedFunction, "name", { value: fn.name });
+  Object.defineProperty(wrappedFunction, "length", { value: fn.length });
+  return wrappedFunction;
+}
+var import_api2;
+var init_src = __esm({
+  "src/index.ts"() {
+    import_api2 = require("@opentelemetry/api");
+    init_attributes();
+    init_spanWrapper();
+    init_tracerProvider();
+    init_attributes();
+    init_tracerProvider();
+  }
+});
+init_src();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ObservationAgent,
+  ObservationChain,
+  ObservationEmbedding,
+  ObservationEvaluator,
+  ObservationGuardrail,
+  ObservationLLM,
+  ObservationReranker,
+  ObservationRetriever,
+  ObservationSpan,
+  ObservationTool,
+  createObservationAttributes,
+  createTraceAttributes,
+  getActiveSpanId,
+  getActiveTraceId,
+  getTracer,
+  getTracerProvider,
+  observe,
+  setTracerProvider,
+  startActiveObservation,
+  startObservation,
+  updateActiveObservation,
+  updateActiveTrace
+});
+//# sourceMappingURL=index.js.map