@cloudbase/agent-observability 1.0.1-alpha.9

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@cloudbase/agent-observability",
+  "version": "1.0.1-alpha.9",
+  "description": "OpenInference-compatible observability for AG-Kit",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./langchain": {
+      "import": {
+        "types": "./dist/langchain.d.mts",
+        "default": "./dist/langchain.mjs"
+      },
+      "require": {
+        "types": "./dist/langchain.d.ts",
+        "default": "./dist/langchain.js"
+      }
+    },
+    "./core": {
+      "import": {
+        "types": "./dist/core.d.mts",
+        "default": "./dist/core.mjs"
+      },
+      "require": {
+        "types": "./dist/core.d.ts",
+        "default": "./dist/core.js"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.mts",
+        "default": "./dist/server.mjs"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ag-kit",
+    "observability",
+    "opentelemetry",
+    "openinference",
+    "langfuse",
+    "tracing"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@arizeai/openinference-semantic-conventions": "^2.1.7",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/semantic-conventions": "^1.39.0"
+  },
+  "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"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.0.2",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/core/attributes.ts

@@ -0,0 +1,233 @@
+import { OBSERVABILITY_TRACER_NAME, OtelSpanAttributes } from "./constants.js";
+import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";
+import { ObservationAttributes, TraceAttributes, ObservationType } from "../types.js";
+import { type Attributes } from "@opentelemetry/api";
+
+/**
+ * Creates OpenTelemetry attributes from trace attributes.
+ *
+ * Converts user-friendly trace attributes into OpenTelemetry attribute format
+ * using OpenInference semantic conventions where applicable.
+ *
+ * @param attributes - Trace attributes to convert
+ * @returns OpenTelemetry attributes object
+ *
+ * @example
+ * ```typescript
+ * const otelAttributes = createTraceAttributes({
+ *   name: 'user-workflow',
+ *   userId: 'user-123',
+ *   sessionId: 'session-456',
+ *   tags: ['checkout', 'payment']
+ * });
+ * ```
+ *
+ * @public
+ */
+export function createTraceAttributes({
+  name,
+  userId,
+  sessionId,
+  version,
+  release,
+  input,
+  output,
+  metadata,
+  tags,
+  environment,
+  public: isPublic,
+}: TraceAttributes = {}): Attributes {
+  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),
+  );
+}
+
+/**
+ * Creates OpenTelemetry attributes from observation attributes.
+ *
+ * Maps observation attributes to OpenInference semantic conventions:
+ * - Uses `openinference.span.kind` for span type
+ * - Uses `llm.*` for LLM-specific attributes
+ * - Uses `tool.*` for tool-specific attributes
+ * - Falls back to `agkit.observation.*` for non-standard attributes
+ *
+ * @param type - Observation type (llm, tool, chain, etc.)
+ * @param attributes - Observation attributes to convert
+ * @returns OpenTelemetry attributes object
+ *
+ * @public
+ */
+export function createObservationAttributes(
+  type: ObservationType,
+  attributes: ObservationAttributes,
+): Attributes {
+  const {
+    metadata,
+    input,
+    output,
+    level,
+    statusMessage,
+    version,
+    completionStartTime,
+    model,
+    modelParameters,
+    usageDetails,
+  } = attributes;
+
+  // Base attributes for all observation types
+  const otelAttributes: Attributes = {
+    [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
+    [SemanticConventions.INPUT_VALUE]: _serialize(input),
+    // Also set legacy agkit.observation.input for compatibility
+    [OtelSpanAttributes.OBSERVATION_INPUT]: _serialize(input),
+    // Use OpenInference output.value convention
+    [SemanticConventions.OUTPUT_VALUE]: _serialize(output),
+    // Also set legacy agkit.observation.output for compatibility
+    [OtelSpanAttributes.OBSERVATION_OUTPUT]: _serialize(output),
+  };
+
+  // LLM-specific attributes
+  if (type === "llm") {
+    if (model) {
+      otelAttributes[SemanticConventions.LLM_MODEL_NAME] = model;
+    }
+    if (modelParameters) {
+      otelAttributes[SemanticConventions.LLM_INVOCATION_PARAMETERS] =
+        _serialize(modelParameters);
+      // Also set agkit.llm.model_parameters for compatibility
+      otelAttributes[OtelSpanAttributes.LLM_MODEL_PARAMETERS] =
+        _serialize(modelParameters);
+    }
+    if (usageDetails) {
+      // Map to OpenInference llm.token_count.* attributes
+      if (typeof usageDetails === "object") {
+        const usage = usageDetails as Record<string, number>;
+        if (usage.promptTokens !== undefined) {
+          otelAttributes[SemanticConventions.LLM_TOKEN_COUNT_PROMPT] =
+            usage.promptTokens;
+        }
+        if (usage.completionTokens !== undefined) {
+          otelAttributes[SemanticConventions.LLM_TOKEN_COUNT_COMPLETION] =
+            usage.completionTokens;
+        }
+        if (usage.totalTokens !== undefined) {
+          otelAttributes[SemanticConventions.LLM_TOKEN_COUNT_TOTAL] =
+            usage.totalTokens;
+        }
+      }
+      // Also set legacy agkit.llm.usage_details for compatibility
+      otelAttributes[OtelSpanAttributes.LLM_USAGE_DETAILS] =
+        _serialize(usageDetails);
+    }
+    if (completionStartTime) {
+      otelAttributes[OtelSpanAttributes.LLM_COMPLETION_START_TIME] =
+        _serialize(completionStartTime);
+    }
+  }
+
+  // Embedding-specific attributes
+  if (type === "embedding") {
+    if (model) {
+      otelAttributes[SemanticConventions.EMBEDDING_MODEL_NAME] = model;
+    }
+    if (modelParameters) {
+      otelAttributes[SemanticConventions.LLM_INVOCATION_PARAMETERS] =
+        _serialize(modelParameters);
+    }
+  }
+
+  // Add metadata (use OpenInference metadata convention)
+  const metadataAttrs = _flattenAndSerializeMetadata(
+    metadata,
+    SemanticConventions.METADATA,
+  );
+  Object.assign(otelAttributes, metadataAttrs);
+
+  // Also add agkit.observation.metadata for compatibility
+  const obsetvabilityMetadataAttrs = _flattenAndSerializeMetadata(
+    metadata,
+    OtelSpanAttributes.OBSERVATION_METADATA
+  );
+  Object.assign(otelAttributes, obsetvabilityMetadataAttrs);
+
+  // Filter out null/undefined values
+  return Object.fromEntries(
+    Object.entries(otelAttributes).filter(([_, v]) => v != null),
+  );
+}
+
+/**
+ * Safely serializes an object to JSON string.
+ *
+ * @param obj - Object to serialize
+ * @returns JSON string or undefined if null/undefined
+ * @internal
+ */
+function _serialize(obj: unknown): string | undefined {
+  try {
+    if (typeof obj === "string") return obj;
+    if (obj instanceof Date) return obj.toISOString();
+    return obj != null ? JSON.stringify(obj) : undefined;
+  } catch {
+    return "<failed to serialize>";
+  }
+}
+
+/**
+ * Flattens and serializes metadata into OpenTelemetry attribute format.
+ *
+ * Converts nested metadata objects into dot-notation attribute keys.
+ * For example, `{ database: { host: 'localhost' } }` becomes
+ * `{ 'metadata.database.host': 'localhost' }` (or 'agkit.observation.metadata.database.host').
+ *
+ * @param metadata - Metadata object to flatten
+ * @param prefix - Attribute prefix (e.g., 'metadata' or 'agkit.observation.metadata')
+ * @returns Flattened metadata attributes
+ * @internal
+ */
+function _flattenAndSerializeMetadata(
+  metadata: unknown,
+  prefix: string,
+): Record<string, string> {
+  const metadataAttributes: Record<string, string> = {};
+
+  if (metadata === undefined || 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;
+}

package/src/core/constants.ts

@@ -0,0 +1,75 @@
+/**
+ * OTEL attribute constants for AG-Kit observability.
+ *
+ * Uses OpenInference semantic conventions where applicable:
+ * https://github.com/Arize-ai/openinference/tree/main/spec
+ *
+ * Falls back to AG-Kit specific attributes where OpenInference
+ * doesn't define a standard.
+ *
+ * @module
+ */
+
+import {
+  SemanticConventions,
+  OpenInferenceSpanKind,
+} from "@arizeai/openinference-semantic-conventions";
+
+// Re-export OpenInference types for convenience
+export { OpenInferenceSpanKind };
+
+/**
+ * SDK information
+ */
+export const OBSERVABILITY_TRACER_NAME = "agkit-tracer";
+export const OBSERVABILITY_SDK_NAME = "@agkit/observability";
+// Version will be injected from package.json
+
+/**
+ * Combined attribute namespace for internal use
+ * Provides a single namespace for all OTEL attributes used by AG-Kit
+ *
+ * Combines OpenInference SemanticConventions with AG-Kit specific attributes
+ */
+export const OtelSpanAttributes = {
+  // OpenInference - re-export all standard 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",
+} as const;
+
+/**
+ * Type for the OtelSpanAttributes object values
+ */
+export type OtelSpanAttributeValues = typeof OtelSpanAttributes[keyof typeof OtelSpanAttributes];