@cloudbase/agent-observability 0.0.20 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/agent-observability",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "OpenInference-compatible observability for AG-Kit",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -64,19 +64,16 @@
   "dependencies": {
     "@arizeai/openinference-semantic-conventions": "^2.1.7",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",
+    "@opentelemetry/resources": "^2.5.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.0",
+    "@opentelemetry/sdk-trace-node": "^2.5.0",
     "@opentelemetry/semantic-conventions": "^1.39.0",
-    "@cloudbase/agent-shared": "^0.0.20"
-  },
-  "optionalDependencies": {
-    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
-    "@opentelemetry/resources": "^2.4.0",
-    "@opentelemetry/sdk-node": "^0.210.0",
-    "@opentelemetry/sdk-trace-base": "^2.4.0",
-    "@opentelemetry/sdk-trace-node": "^2.4.0"
+    "@cloudbase/agent-shared": "^0.0.21"
   },
   "devDependencies": {
     "@langchain/core": "^1.0.2",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",
     "@types/node": "^20.0.0",
     "tsup": "^8.5.0",
     "typescript": "^5.0.0"

package/src/index.ts

@@ -4,7 +4,10 @@
  * @packageDocumentation
  */
 
-import { trace, context, TimeInput, SpanStatusCode, Span, SpanContext, Link } from "@opentelemetry/api";
+import { trace, context, TimeInput, SpanStatusCode, Span, SpanContext, Link, INVALID_SPAN_CONTEXT } from "@opentelemetry/api";
+
+// Re-export SpanContext type for adapters to use without depending on @opentelemetry/api directly
+export type { SpanContext } from "@opentelemetry/api";
 
 import {
   createObservationAttributes,
@@ -164,6 +167,50 @@ function createParentContext(
   return trace.setSpanContext(context.active(), parentSpanContext);
 }
 
+/**
+ * Creates a NonRecordingSpan that safely accepts all Span operations as no-ops.
+ * Used as a fallback when observation creation fails, ensuring observability
+ * never blocks business logic.
+ *
+ * @internal
+ */
+function createNoopSpan(): Span {
+  return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+}
+
+/**
+ * Creates a no-op observation of the specified type.
+ * All methods (update, end, setErrorStatus, etc.) are safe to call but do nothing.
+ *
+ * @param asType - The observation type to create
+ * @returns A no-op observation instance
+ * @internal
+ */
+function createNoopObservation(asType: ObservationType = "chain"): Observation {
+  const otelSpan = createNoopSpan();
+  switch (asType) {
+    case "llm":
+      return new ObservationLLM({ otelSpan });
+    case "embedding":
+      return new ObservationEmbedding({ otelSpan });
+    case "agent":
+      return new ObservationAgent({ otelSpan });
+    case "tool":
+      return new ObservationTool({ otelSpan });
+    case "retriever":
+      return new ObservationRetriever({ otelSpan });
+    case "reranker":
+      return new ObservationReranker({ otelSpan });
+    case "evaluator":
+      return new ObservationEvaluator({ otelSpan });
+    case "guardrail":
+      return new ObservationGuardrail({ otelSpan });
+    case "chain":
+    default:
+      return new ObservationChain({ otelSpan });
+  }
+}
+
 // Function overloads for proper type inference
 // Generic overload for dynamic asType (returns Observation union)
 export function startObservation(
@@ -284,71 +331,80 @@ export function startObservation(
 ): Observation {
   const { asType = "chain", ...observationOptions } = options || {};
 
-  const otelSpan = createOtelSpan({
-    name,
-    ...observationOptions,
-  });
-
-  switch (asType) {
-    case "llm":
-      return new ObservationLLM({
-        otelSpan,
-        attributes: attributes as LLMAttributes,
-      });
+  try {
+    const otelSpan = createOtelSpan({
+      name,
+      ...observationOptions,
+    });
+
+    switch (asType) {
+      case "llm":
+        return new ObservationLLM({
+          otelSpan,
+          attributes: attributes as LLMAttributes,
+        });
 
-    case "embedding":
-      return new ObservationEmbedding({
-        otelSpan,
-        attributes: attributes as EmbeddingAttributes,
-      });
+      case "embedding":
+        return new ObservationEmbedding({
+          otelSpan,
+          attributes: attributes as EmbeddingAttributes,
+        });
 
-    case "agent":
-      return new ObservationAgent({
-        otelSpan,
-        attributes: attributes as AgentAttributes,
-      });
+      case "agent":
+        return new ObservationAgent({
+          otelSpan,
+          attributes: attributes as AgentAttributes,
+        });
 
-    case "tool":
-      return new ObservationTool({
-        otelSpan,
-        attributes: attributes as ToolAttributes,
-      });
+      case "tool":
+        return new ObservationTool({
+          otelSpan,
+          attributes: attributes as ToolAttributes,
+        });
 
-    case "chain":
-      return new ObservationChain({
-        otelSpan,
-        attributes: attributes as ChainAttributes,
-      });
+      case "chain":
+        return new ObservationChain({
+          otelSpan,
+          attributes: attributes as ChainAttributes,
+        });
 
-    case "retriever":
-      return new ObservationRetriever({
-        otelSpan,
-        attributes: attributes as RetrieverAttributes,
-      });
+      case "retriever":
+        return new ObservationRetriever({
+          otelSpan,
+          attributes: attributes as RetrieverAttributes,
+        });
 
-    case "reranker":
-      return new ObservationReranker({
-        otelSpan,
-        attributes: attributes as RerankerAttributes,
-      });
+      case "reranker":
+        return new ObservationReranker({
+          otelSpan,
+          attributes: attributes as RerankerAttributes,
+        });
 
-    case "evaluator":
-      return new ObservationEvaluator({
-        otelSpan,
-        attributes: attributes as EvaluatorAttributes,
-      });
+      case "evaluator":
+        return new ObservationEvaluator({
+          otelSpan,
+          attributes: attributes as EvaluatorAttributes,
+        });
 
-    case "guardrail":
-      return new ObservationGuardrail({
-        otelSpan,
-        attributes: attributes as GuardrailAttributes,
-      });
+      case "guardrail":
+        return new ObservationGuardrail({
+          otelSpan,
+          attributes: attributes as GuardrailAttributes,
+        });
 
-    default:
-      return new ObservationChain({
-        otelSpan,
-        attributes: attributes as BaseSpanAttributes,
-      });
+      default:
+        return new ObservationChain({
+          otelSpan,
+          attributes: attributes as BaseSpanAttributes,
+        });
+    }
+  } catch (err) {
+    // Observability must never block business logic - return a no-op observation
+    console.warn(
+      `[Observability] Failed to create observation "${name}":`,
+      err instanceof Error ? err.message : err,
+    );
+    return createNoopObservation(asType);
   }
 }
 
@@ -547,71 +603,92 @@ export function startActiveObservation<
 >(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F> {
   const { asType = "chain", endOnExit, ...observationOptions } = options || {};
 
-  return getTracer().startActiveSpan(
-    name,
-    { startTime: observationOptions?.startTime },
-    createParentContext(observationOptions?.parentSpanContext) ??
-      context.active(),
-    (span) => {
-      try {
-        let observation: 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 "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 "chain":
-          default:
-            observation = new ObservationChain({ otelSpan: span });
-        }
+  // Track whether fn has been called to distinguish observability errors from business errors.
+  // If fn was called and threw, we must re-throw (business error).
+  // If fn was never called, the error is from observability infrastructure and we can fall back.
+  let fnCalled = false;
 
-        const result = fn(observation as Parameters<F>[0]);
+  try {
+    return getTracer().startActiveSpan(
+      name,
+      { startTime: observationOptions?.startTime },
+      createParentContext(observationOptions?.parentSpanContext) ??
+        context.active(),
+      (span) => {
+        try {
+          let observation: 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 "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 "chain":
+            default:
+              observation = new ObservationChain({ otelSpan: span });
+          }
 
-        if (result instanceof Promise) {
-          return wrapPromise(
-            result,
-            span,
-            endOnExit,
-          ) as ReturnType<F>;
-        } else {
+          fnCalled = true;
+          const result = fn(observation as Parameters<F>[0]);
+
+          if (result instanceof Promise) {
+            return wrapPromise(
+              result,
+              span,
+              endOnExit,
+            ) as ReturnType<F>;
+          } else {
+            if (endOnExit !== false) {
+              span.end();
+            }
+            return result as ReturnType<F>;
+          }
+        } catch (err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err instanceof Error ? err.message : "Unknown error",
+          });
           if (endOnExit !== false) {
             span.end();
           }
-          return result as ReturnType<F>;
-        }
-      } catch (err) {
-        span.setStatus({
-          code: SpanStatusCode.ERROR,
-          message: err instanceof Error ? err.message : "Unknown error",
-        });
-        if (endOnExit !== false) {
-          span.end();
+          throw err;
         }
-        throw err;
-      }
-    },
-  );
+      },
+    );
+  } catch (err) {
+    // If fn was already called, the error is from business logic - re-throw
+    if (fnCalled) {
+      throw err;
+    }
+    // Error is from observability infrastructure (getTracer, startActiveSpan) -
+    // fall back to executing fn with a no-op observation
+    console.warn(
+      `[Observability] startActiveObservation "${name}" failed, falling back to no-op:`,
+      err instanceof Error ? err.message : err,
+    );
+    const noopObservation = createNoopObservation(asType);
+    return fn(noopObservation as Parameters<F>[0]) as ReturnType<F>;
+  }
 }
 
 /**
@@ -732,53 +809,75 @@ export function observe<T extends (...args: any[]) => any>(
   ): ReturnType<T> {
     const name = fn.name || "anonymous-function";
 
-    // Prepare input data
-    const inputData = captureInput ? _captureArguments(args) : undefined;
-
-    // Create the observation
-    const observation = startObservation(
-      name,
-      inputData ? { input: inputData } : {},
-      {
-        ...observationOptions,
-        asType: asType as "chain",
-      },
-    );
-
-    // Set the observation span as active in the context
-    const activeContext = trace.setSpan(context.active(), observation.otelSpan);
-
-    // Execute the function within the observation context
-    const result = context.with(activeContext, () => fn.apply(this, args));
-
-    // Handle promises
-    if (result instanceof Promise) {
-      return result.then(
-        (value) => {
-          if (captureOutput) {
-            observation.update({ output: value });
-          }
-          observation.end();
-          return value;
+    let observation: Observation;
+    let fnCalled = false;
+    try {
+      // Prepare input data
+      const inputData = captureInput ? _captureArguments(args) : undefined;
+
+      // Create the observation (safe - returns no-op on failure)
+      observation = startObservation(
+        name,
+        inputData ? { input: inputData } : {},
+        {
+          ...observationOptions,
+          asType: asType as "chain",
         },
-        (err: unknown) => {
-          observation.update({
-            level: "ERROR",
-            statusMessage: err instanceof Error ? err.message : "Unknown error",
-          });
-          observation.end();
-          throw err;
-        },
-      ) as ReturnType<T>;
-    }
+      );
+
+      // Set the observation span as active in the context
+      const activeContext = trace.setSpan(context.active(), observation.otelSpan);
+
+      // Execute the function within the observation context
+      fnCalled = true;
+      const result = context.with(activeContext, () => fn.apply(this, args));
+
+      // Handle promises
+      if (result instanceof Promise) {
+        return result.then(
+          (value) => {
+            if (captureOutput) {
+              observation.update({ output: value });
+            }
+            observation.end();
+            return value;
+          },
+          (err: unknown) => {
+            observation.update({
+              level: "ERROR",
+              statusMessage: err instanceof Error ? err.message : "Unknown error",
+            });
+            observation.end();
+            throw err;
+          },
+        ) as ReturnType<T>;
+      }
 
-    // Handle synchronous functions
-    if (captureOutput) {
-      observation.update({ output: result });
-    }
-    observation.end();
+      // Handle synchronous functions
+      if (captureOutput) {
+        observation.update({ output: result });
+      }
+      observation.end();
 
-    return result as ReturnType<T>;
+      return result as ReturnType<T>;
+    } catch (err) {
+      // If fn was already called, the error is from business logic - re-throw
+      if (fnCalled) {
+        throw err;
+      }
+      // Observability infra error (trace.setSpan, context.with) -
+      // fall back to calling fn directly without observability context
+      console.warn(
+        `[Observability] observe "${name}" failed, falling back to direct call:`,
+        err instanceof Error ? (err as Error).message : err,
+      );
+      try {
+        observation!?.end();
+      } catch {
+        // Ignore end() failures on cleanup
+      }
+      return fn.apply(this, args);
+    }
   };
 
   // Preserve function properties

package/src/langchain/CallbackHandler.ts

@@ -766,6 +766,12 @@ export class CallbackHandler extends BaseCallbackHandler {
     );
     this.runMap.set(runId, observation);
 
+    if (this.runMap.size > 1000) {
+      this.logger.warn?.(
+        `runMap size (${this.runMap.size}) exceeds 1000. Possible missing end callbacks.`
+      );
+    }
+
     return observation;
   }
 

package/dist/chunk-NFEGQTCC.mjs

@@ -1,27 +0,0 @@
-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);
-
-export {
-  __esm,
-  __export,
-  __toCommonJS
-};
-//# sourceMappingURL=chunk-NFEGQTCC.mjs.map

package/dist/chunk-NFEGQTCC.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}