@cloudbase/agent-observability 1.0.1-alpha.10

package/src/core/spanWrapper.ts

@@ -0,0 +1,417 @@
+import { Span, TimeInput } from "@opentelemetry/api";
+
+import { createObservationAttributes, createTraceAttributes } from "./attributes.js";
+import { getTracer } from "./tracerProvider.js";
+import {
+  BaseSpanAttributes,
+  LLMAttributes,
+  TraceAttributes,
+  ObservationType,
+} from "../types.js";
+import type {
+  ToolAttributes,
+  AgentAttributes,
+  ChainAttributes,
+  RetrieverAttributes,
+  RerankerAttributes,
+  EvaluatorAttributes,
+  GuardrailAttributes,
+  EmbeddingAttributes,
+  ObservationAttributes,
+} from "../types.js";
+
+/**
+ * Union type representing any observation wrapper.
+ *
+ * @public
+ */
+export type Observation =
+  | ObservationSpan
+  | ObservationLLM
+  | ObservationEmbedding
+  | ObservationAgent
+  | ObservationTool
+  | ObservationChain
+  | ObservationRetriever
+  | ObservationReranker
+  | ObservationEvaluator
+  | ObservationGuardrail;
+
+/**
+ * Parameters for creating an observation wrapper.
+ *
+ * @internal
+ */
+type ObservationParams = {
+  otelSpan: Span;
+  type: ObservationType;
+  attributes?: BaseSpanAttributes | LLMAttributes;
+};
+
+/**
+ * Base class for all observation wrappers.
+ *
+ * Provides common functionality for all observation types including:
+ * - OpenTelemetry span integration
+ * - Unique identification (span ID, trace ID)
+ * - Lifecycle management (update, end)
+ * - Trace context management
+ * - Child observation creation
+ *
+ * @internal
+ */
+abstract class BaseObservation {
+  /** The underlying OpenTelemetry span */
+  public readonly otelSpan: Span;
+  /** The observation type */
+  public readonly type: ObservationType;
+  /** The span ID from the OpenTelemetry span context */
+  public id: string;
+  /** The trace ID from the OpenTelemetry span context */
+  public traceId: string;
+
+  constructor(params: ObservationParams) {
+    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 */
+  protected get tracer() {
+    return getTracer();
+  }
+
+  /**
+   * Ends the observation, marking it as complete.
+   *
+   * @param endTime - Optional end time, defaults to current time
+   */
+  public end(endTime?: TimeInput) {
+    this.otelSpan.end(endTime);
+  }
+
+  /**
+   * Updates the OTEL span attributes.
+   *
+   * @param attributes - Attributes to update
+   * @internal
+   */
+  updateOtelSpanAttributes(attributes: ObservationAttributes) {
+    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
+   */
+  public updateTrace(attributes: TraceAttributes) {
+    this.otelSpan.setAttributes(createTraceAttributes(attributes));
+    return this;
+  }
+
+  /**
+   * Creates a new child observation within this observation's context.
+   *
+   * @param name - Name for the child observation
+   * @param attributes - Type-specific attributes
+   * @param options - Configuration including observation type
+   * @returns Child observation instance
+   */
+  public startObservation(
+    name: string,
+    attributes: LLMAttributes,
+    options: { asType: "llm" },
+  ): ObservationLLM;
+  public startObservation(
+    name: string,
+    attributes: EmbeddingAttributes,
+    options: { asType: "embedding" },
+  ): ObservationEmbedding;
+  public startObservation(
+    name: string,
+    attributes: AgentAttributes,
+    options: { asType: "agent" },
+  ): ObservationAgent;
+  public startObservation(
+    name: string,
+    attributes: ToolAttributes,
+    options: { asType: "tool" },
+  ): ObservationTool;
+  public startObservation(
+    name: string,
+    attributes: ChainAttributes,
+    options: { asType: "chain" },
+  ): ObservationChain;
+  public startObservation(
+    name: string,
+    attributes: RetrieverAttributes,
+    options: { asType: "retriever" },
+  ): ObservationRetriever;
+  public startObservation(
+    name: string,
+    attributes: RerankerAttributes,
+    options: { asType: "reranker" },
+  ): ObservationReranker;
+  public startObservation(
+    name: string,
+    attributes: EvaluatorAttributes,
+    options: { asType: "evaluator" },
+  ): ObservationEvaluator;
+  public startObservation(
+    name: string,
+    attributes: GuardrailAttributes,
+    options: { asType: "guardrail" },
+  ): ObservationGuardrail;
+  public startObservation(
+    name: string,
+    attributes?: BaseSpanAttributes,
+    options?: { asType?: "span" },
+  ): ObservationSpan;
+  public startObservation(
+    name: string,
+    attributes?:
+      | BaseSpanAttributes
+      | LLMAttributes
+      | ToolAttributes
+      | AgentAttributes
+      | ChainAttributes
+      | RetrieverAttributes
+      | RerankerAttributes
+      | EvaluatorAttributes
+      | GuardrailAttributes
+      | EmbeddingAttributes,
+    options?: { asType?: ObservationType },
+  ): Observation {
+    // Import here to avoid circular dependency
+    const { startObservation: startObs } = require("../index.js");
+    const { asType = "span" } = options || {};
+
+    return startObs(name, attributes, {
+      asType: asType as "span",
+      parentSpanContext: this.otelSpan.spanContext(),
+    });
+  }
+}
+
+// Type-specific observation classes
+
+type ObservationSpanParams = {
+  otelSpan: Span;
+  attributes?: BaseSpanAttributes;
+};
+
+/**
+ * General-purpose observation for tracking operations.
+ *
+ * @public
+ */
+export class ObservationSpan extends BaseObservation {
+  constructor(params: ObservationSpanParams) {
+    super({ ...params, type: "span" });
+  }
+
+  public update(attributes: BaseSpanAttributes): ObservationSpan {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationLLMParams = {
+  otelSpan: Span;
+  attributes?: LLMAttributes;
+};
+
+/**
+ * LLM observation for tracking language model calls.
+ *
+ * @public
+ */
+export class ObservationLLM extends BaseObservation {
+  constructor(params: ObservationLLMParams) {
+    super({ ...params, type: "llm" });
+  }
+
+  public update(attributes: LLMAttributes): ObservationLLM {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationEmbeddingParams = {
+  otelSpan: Span;
+  attributes?: EmbeddingAttributes;
+};
+
+/**
+ * Embedding observation for tracking embedding operations.
+ *
+ * @public
+ */
+export class ObservationEmbedding extends BaseObservation {
+  constructor(params: ObservationEmbeddingParams) {
+    super({ ...params, type: "embedding" });
+  }
+
+  public update(attributes: EmbeddingAttributes): ObservationEmbedding {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationAgentParams = {
+  otelSpan: Span;
+  attributes?: AgentAttributes;
+};
+
+/**
+ * Agent observation for tracking AI agent workflows.
+ *
+ * @public
+ */
+export class ObservationAgent extends BaseObservation {
+  constructor(params: ObservationAgentParams) {
+    super({ ...params, type: "agent" });
+  }
+
+  public update(attributes: AgentAttributes): ObservationAgent {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationToolParams = {
+  otelSpan: Span;
+  attributes?: ToolAttributes;
+};
+
+/**
+ * Tool observation for tracking tool calls.
+ *
+ * @public
+ */
+export class ObservationTool extends BaseObservation {
+  constructor(params: ObservationToolParams) {
+    super({ ...params, type: "tool" });
+  }
+
+  public update(attributes: ToolAttributes): ObservationTool {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationChainParams = {
+  otelSpan: Span;
+  attributes?: ChainAttributes;
+};
+
+/**
+ * Chain observation for tracking multi-step workflows.
+ *
+ * @public
+ */
+export class ObservationChain extends BaseObservation {
+  constructor(params: ObservationChainParams) {
+    super({ ...params, type: "chain" });
+  }
+
+  public update(attributes: ChainAttributes): ObservationChain {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationRetrieverParams = {
+  otelSpan: Span;
+  attributes?: RetrieverAttributes;
+};
+
+/**
+ * Retriever observation for tracking document retrieval.
+ *
+ * @public
+ */
+export class ObservationRetriever extends BaseObservation {
+  constructor(params: ObservationRetrieverParams) {
+    super({ ...params, type: "retriever" });
+  }
+
+  public update(attributes: RetrieverAttributes): ObservationRetriever {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationRerankerParams = {
+  otelSpan: Span;
+  attributes?: RerankerAttributes;
+};
+
+/**
+ * Reranker observation for tracking reranking operations.
+ *
+ * @public
+ */
+export class ObservationReranker extends BaseObservation {
+  constructor(params: ObservationRerankerParams) {
+    super({ ...params, type: "reranker" });
+  }
+
+  public update(attributes: RerankerAttributes): ObservationReranker {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationEvaluatorParams = {
+  otelSpan: Span;
+  attributes?: EvaluatorAttributes;
+};
+
+/**
+ * Evaluator observation for tracking evaluation operations.
+ *
+ * @public
+ */
+export class ObservationEvaluator extends BaseObservation {
+  constructor(params: ObservationEvaluatorParams) {
+    super({ ...params, type: "evaluator" });
+  }
+
+  public update(attributes: EvaluatorAttributes): ObservationEvaluator {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}
+
+type ObservationGuardrailParams = {
+  otelSpan: Span;
+  attributes?: GuardrailAttributes;
+};
+
+/**
+ * Guardrail observation for tracking safety checks.
+ *
+ * @public
+ */
+export class ObservationGuardrail extends BaseObservation {
+  constructor(params: ObservationGuardrailParams) {
+    super({ ...params, type: "guardrail" });
+  }
+
+  public update(attributes: GuardrailAttributes): ObservationGuardrail {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+}

package/src/core/tracerProvider.ts

@@ -0,0 +1,136 @@
+import { TracerProvider, trace, context } from "@opentelemetry/api";
+
+const OBSERVABILITY_GLOBAL_SYMBOL = Symbol.for("observability");
+
+type ObservabilityGlobalState = {
+  isolatedTracerProvider: TracerProvider | null;
+};
+
+function createState(): ObservabilityGlobalState {
+  return {
+    isolatedTracerProvider: null,
+  };
+}
+
+interface GlobalThis {
+  [OBSERVABILITY_GLOBAL_SYMBOL]?: ObservabilityGlobalState;
+}
+
+/**
+ * Gets the global state for tracing observability.
+ *
+ * @returns The global state object
+ * @internal
+ */
+function getObservabilityGlobalState(): ObservabilityGlobalState {
+  const initialState = createState();
+
+  try {
+    const g = globalThis as typeof globalThis & 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;
+  }
+}
+
+/**
+ * Sets an isolated TracerProvider for tracing tracing operations.
+ *
+ * This allows tracing to use its own TracerProvider instance, separate from
+ * the global OpenTelemetry TracerProvider.
+ *
+ * Note: While this isolates span processing and export, it does NOT provide
+ * complete trace isolation. OpenTelemetry context (trace IDs, parent spans)
+ * is still shared between the global and isolated providers.
+ *
+ * @param provider - The TracerProvider instance to use, or null to clear
+ *
+ * @example
+ * ```typescript
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * import { setTracerProvider } from './observability';
+ *
+ * const provider = new NodeTracerProvider();
+ * setTracerProvider(provider);
+ * ```
+ *
+ * @public
+ */
+export function setTracerProvider(provider: TracerProvider | null) {
+  getObservabilityGlobalState().isolatedTracerProvider = provider;
+}
+
+/**
+ * Gets the TracerProvider for tracing tracing operations.
+ *
+ * Returns the isolated TracerProvider if one has been set via setTracerProvider(),
+ * otherwise falls back to the global OpenTelemetry TracerProvider.
+ *
+ * @returns The TracerProvider instance to use for tracing tracing
+ *
+ * @example
+ * ```typescript
+ * import { getTracerProvider } from './observability';
+ *
+ * const provider = getTracerProvider();
+ * const tracer = provider.getTracer('my-tracer', '1.0.0');
+ * ```
+ *
+ * @public
+ */
+export function getTracerProvider(): TracerProvider {
+  const { isolatedTracerProvider } = getObservabilityGlobalState();
+
+  if (isolatedTracerProvider) return isolatedTracerProvider;
+
+  return trace.getTracerProvider();
+}
+
+/**
+ * Gets the OpenTelemetry tracer instance for tracing.
+ *
+ * Returns a tracer specifically configured for tracing with the correct
+ * tracer name and version.
+ *
+ * @returns The tracing OpenTelemetry tracer instance
+ *
+ * @example
+ * ```typescript
+ * import { getTracer } from './observability';
+ *
+ * const tracer = getTracer();
+ * const span = tracer.startSpan('my-operation');
+ * ```
+ *
+ * @public
+ */
+export function getTracer() {
+  return getTracerProvider().getTracer(
+    OBSERVABILITY_SDK_NAME,
+    OBSERVABILITY_SDK_VERSION
+  );
+}
+
+// SDK version - could be read from package.json in production
+const OBSERVABILITY_SDK_NAME = "ag-kit-observability";
+const OBSERVABILITY_SDK_VERSION = "0.1.0";