@cloudbase/agent-observability 0.0.16 → 0.0.18

package/README.md

@@ -1,9 +1,11 @@
-# AG-Kit TypeScript Observability
+# TypeScript Observability
 
-OpenTelemetry-based observability for AG-Kit with OpenInference semantic conventions.
+OpenTelemetry-based observability for the TypeScript SDK with OpenInference semantic conventions.
 
 ## Installation
 
+### Standalone Usage
+
 ```bash
 # Core package
 npm install @cloudbase/agent-observability
@@ -12,6 +14,20 @@ npm install @cloudbase/agent-observability
 npm install @cloudbase/agent-observability @langchain/core
 ```
 
+### With AG-Kit Server (Optional)
+
+When using `@cloudbase/agent-server` or `@cloudbase/agent-adapter-langgraph`, observability is an **optional peer dependency**. You need to explicitly install it if you want tracing capabilities:
+
+```bash
+# Using with @cloudbase/agent-server
+npm install @cloudbase/agent-server @cloudbase/agent-observability
+
+# Using with @cloudbase/agent-adapter-langgraph
+npm install @cloudbase/agent-adapter-langgraph @cloudbase/agent-observability
+```
+
+Without installing `@cloudbase/agent-observability`, the packages will work normally but no traces will be generated.
+
 ## Architecture Overview
 
 This package provides a callback-based observability system that integrates with LangChain/LangGraph through the standard `BaseCallbackHandler` mechanism.
@@ -20,7 +36,7 @@ This package provides a callback-based observability system that integrates with
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│                      AG-Kit Application                          │
+│                      Application                                 │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                  │
 │  ┌──────────────────────────────────────────────────────────┐  │
@@ -134,7 +150,7 @@ const agent = new LangGraphAgent({ graph: workflow });
 
 ## Span Hierarchy Example
 
-When using LangGraph with AG-Kit server:
+When using LangGraph with the server:
 
 ```
 AG-UI.Server (Request entry point)
@@ -213,7 +229,6 @@ interface CallbackHandlerOptions {
 
 ### Span Types
 
-- `ObservationSpan`: General spans
 - `ObservationLLM`: LLM generation spans
 - `ObservationTool`: Tool invocation spans
 - `ObservationChain`: Chain/workflow spans

package/dist/chunk-5EXUNUGP.mjs

@@ -0,0 +1,60 @@
+import {
+  __esm
+} from "./chunk-NFEGQTCC.mjs";
+
+// src/core/constants.ts
+import {
+  SemanticConventions,
+  OpenInferenceSpanKind
+} from "@arizeai/openinference-semantic-conventions";
+var OBSERVABILITY_TRACER_NAME, OBSERVABILITY_SDK_NAME, OBSERVABILITY_SDK_VERSION, OtelSpanAttributes;
+var init_constants = __esm({
+  "src/core/constants.ts"() {
+    "use strict";
+    OBSERVABILITY_TRACER_NAME = "agui-tracer";
+    OBSERVABILITY_SDK_NAME = "observability";
+    OBSERVABILITY_SDK_VERSION = "0.1.0";
+    OtelSpanAttributes = {
+      // OpenInference - re-export all standard conventions
+      ...SemanticConventions,
+      // 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",
+      // 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",
+      // 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",
+      // Retriever-specific (non-standard)
+      RETRIEVER_NAME: "retriever.name",
+      RETRIEVER_QUERY: "retriever.query",
+      RETRIEVER_INDEX_ID: "retriever.index_id",
+      RETRIEVER_TOP_K: "retriever.top_k",
+      // General (non-standard)
+      ENVIRONMENT: "environment",
+      RELEASE: "release",
+      VERSION: "version"
+    };
+  }
+});
+
+export {
+  OpenInferenceSpanKind,
+  OBSERVABILITY_TRACER_NAME,
+  OBSERVABILITY_SDK_NAME,
+  OBSERVABILITY_SDK_VERSION,
+  OtelSpanAttributes,
+  init_constants
+};
+//# sourceMappingURL=chunk-5EXUNUGP.mjs.map

package/dist/chunk-5EXUNUGP.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/constants.ts"],"sourcesContent":["/**\n * OTEL attribute constants for observability.\n *\n * Uses OpenInference semantic conventions where applicable:\n * https://github.com/Arize-ai/openinference/tree/main/spec\n *\n * Falls back to non-standard attributes where OpenInference\n * doesn't define a standard.\n *\n * @module\n */\n\nimport {\n  SemanticConventions,\n  OpenInferenceSpanKind,\n} from \"@arizeai/openinference-semantic-conventions\";\n\n// Re-export OpenInference types for convenience\nexport { OpenInferenceSpanKind };\n\n/**\n * SDK information\n */\n// Brandless defaults: avoid emitting project-specific identifiers into traces.\n// Users can still override service.name via OTEL_SERVICE_NAME.\nexport const OBSERVABILITY_TRACER_NAME = \"agui-tracer\";\nexport const OBSERVABILITY_SDK_NAME = \"observability\";\nexport const OBSERVABILITY_SDK_VERSION = \"0.1.0\";\n\n/**\n * Combined attribute namespace for internal use\n * Provides a single namespace for all OTEL attributes used internally.\n *\n * Combines OpenInference SemanticConventions with non-standard attributes\n */\nexport const OtelSpanAttributes = {\n  // OpenInference - re-export all standard conventions\n  ...SemanticConventions,\n\n  // Trace attributes (non-standard)\n  TRACE_NAME: \"trace.name\",\n  TRACE_TAGS: \"trace.tags\",\n  TRACE_PUBLIC: \"trace.public\",\n  TRACE_METADATA: \"trace.metadata\",\n  TRACE_INPUT: \"trace.input\",\n  TRACE_OUTPUT: \"trace.output\",\n\n  // Observation attributes (non-standard)\n  OBSERVATION_TYPE: \"observation.type\",\n  OBSERVATION_LEVEL: \"observation.level\",\n  OBSERVATION_STATUS_MESSAGE: \"observation.status_message\",\n  OBSERVATION_INPUT: \"observation.input\",\n  OBSERVATION_OUTPUT: \"observation.output\",\n  OBSERVATION_METADATA: \"observation.metadata\",\n\n  // LLM-specific (non-standard)\n  LLM_COMPLETION_START_TIME: \"llm.completion_start_time\",\n  LLM_MODEL_PARAMETERS: \"llm.model_parameters\",\n  LLM_USAGE_DETAILS: \"llm.usage_details\",\n  LLM_COST_DETAILS: \"llm.cost_details\",\n\n  // Retriever-specific (non-standard)\n  RETRIEVER_NAME: \"retriever.name\",\n  RETRIEVER_QUERY: \"retriever.query\",\n  RETRIEVER_INDEX_ID: \"retriever.index_id\",\n  RETRIEVER_TOP_K: \"retriever.top_k\",\n\n  // General (non-standard)\n  ENVIRONMENT: \"environment\",\n  RELEASE: \"release\",\n  VERSION: \"version\",\n} as const;\n\n"],"mappings":";;;;;AAYA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAfP,IAyBa,2BACA,wBACA,2BAQA;AAnCb;AAAA;AAAA;AAyBO,IAAM,4BAA4B;AAClC,IAAM,yBAAyB;AAC/B,IAAM,4BAA4B;AAQlC,IAAM,qBAAqB;AAAA;AAAA,MAEhC,GAAG;AAAA;AAAA,MAGH,YAAY;AAAA,MACZ,YAAY;AAAA,MACZ,cAAc;AAAA,MACd,gBAAgB;AAAA,MAChB,aAAa;AAAA,MACb,cAAc;AAAA;AAAA,MAGd,kBAAkB;AAAA,MAClB,mBAAmB;AAAA,MACnB,4BAA4B;AAAA,MAC5B,mBAAmB;AAAA,MACnB,oBAAoB;AAAA,MACpB,sBAAsB;AAAA;AAAA,MAGtB,2BAA2B;AAAA,MAC3B,sBAAsB;AAAA,MACtB,mBAAmB;AAAA,MACnB,kBAAkB;AAAA;AAAA,MAGlB,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,oBAAoB;AAAA,MACpB,iBAAiB;AAAA;AAAA,MAGjB,aAAa;AAAA,MACb,SAAS;AAAA,MACT,SAAS;AAAA,IACX;AAAA;AAAA;","names":[]}