@glassflow-ai/rius 0.7.0 → 1.0.0

package/README.md

@@ -98,6 +98,38 @@ const handleQuery2 = observe(
 await handleQuery("hello");
 ```
 
+That is the CHAIN case, the default. On every other kind the span is named
+the way the GenAI conventions say to, `{operation} {target}`, and the
+wrapped function's name is used as the target only where it IS the target —
+a tool:
+
+```ts
+const getWeather = observe(async function getWeather(city: string) { ... }, {
+  kind: SpanKind.TOOL,
+});
+await getWeather("Berlin"); // span "execute_tool getWeather", gen_ai.tool.name "getWeather"
+```
+
+An AGENT wrapper is named after the agent it invokes (`agentName`, or the
+one `init()` was given), a RETRIEVER after its `dataSourceId`. A function
+name is not an agent or an index, so it is never used as one. Pass `{ name }`
+to override any of this.
+
+An AGENT span (from `observe`, `startSpan` or `startAsCurrentSpan`) can also
+carry `agentId` and `agentVersion`, which describe the agent it *invoked*, as
+`gen_ai.agent.id` and `gen_ai.agent.version`. Both are taken verbatim — the
+conventions' own version examples are `1.0.0` and `2025-05-01` — and both are
+ignored on every other kind.
+
+An AGENT wrapper also scopes the calls it makes: TOOL spans opened while it
+runs, local or MCP, carry that agent as `gen_ai.agent.name` — on an
+execute-tool span the conventions define that key as the agent *executing*
+the tool, where on an invoke-agent span it is the agent being *invoked*.
+Outside any agent, a tool span falls back to the agent `init()` was given.
+The scope follows async calls, so any nesting depth works; only
+`startAsCurrentSpan` and `observe` open it, since `startSpan` does not make
+its span current.
+
 ### `startSpan` / `startAsCurrentSpan`: manual spans
 
 For finer control than `observe`, create spans directly:
@@ -118,8 +150,70 @@ automatically and recording any thrown exception. The options argument is
 optional in both, so `startAsCurrentSpan("step", async (span) => { ... })`
 works when you have nothing to configure.
 
+**The name is optional too.** Omit it and the span is named the way the
+OpenTelemetry GenAI conventions say to — `{operation} {target}` — composed
+from the attributes the span already carries. The callback still comes last,
+so `startAsCurrentSpan(options, fn)` and `startAsCurrentSpan(fn)` are both
+valid:
+
+| Kind | Default span name | Without the target |
+| --- | --- | --- |
+| LLM | `chat gpt-4o` (`{operation} {gen_ai.request.model}`) | `chat` |
+| EMBEDDING | `embeddings text-embedding-3-small` | `embeddings` |
+| TOOL | `execute_tool get_weather` | `execute_tool` |
+| AGENT | `invoke_agent planner` | `invoke_agent` |
+| RETRIEVER | `retrieval docs-index` | `retrieval` |
+| CHAIN | the function name for `observe`, else `chain` | — |
+
+```ts
+// Named "execute_tool get_weather", with gen_ai.tool.name "get_weather".
+await startAsCurrentSpan(
+  { kind: SpanKind.TOOL, toolName: "get_weather", input: city },
+  async (span) => { ... },
+);
+```
+
+A name you pass always wins; this changes the default, not your ability to
+choose. The LLM name uses the REQUEST model, never the response model: the
+span is named when it starts, and a partial-span snapshot has to carry the
+same name as the span that replaces it. CHAIN has no operation to compose
+from, so an unnamed CHAIN span is called `chain`.
+
+`kind` sets the span's taxonomy (`openinference.span.kind`, our `SpanKind`
+enum: CHAIN by default, or TOOL, RETRIEVER, EMBEDDING, AGENT, LLM). A TOOL
+span also carries `gen_ai.tool.name`, set to the span name unless you pass
+`toolName` (and unset if you pass neither), which both the span helpers and `observe` accept for the case
+where the span name is not the bare tool name. It also takes `toolCallId`
+(`gen_ai.tool.call.id`, the id of the model tool-call this execution answers)
+and `toolType` (`gen_ai.tool.type`: `function`, `extension`, `datastore`).
+Both are yours to pass or omit, never derived, and neither changes the span
+name. The MCP wrapper sets neither on purpose: a tool call id belongs to the
+model's message, not to the protocol exchange, and the wrapper never sees it.
+A RETRIEVER span carries
+`gen_ai.data_source.id` when you pass `dataSourceId`, naming the index or
+collection it searched, and `gen_ai.retrieval.top_k` when you pass `topK`.
+Each kind also
+decides the OpenTelemetry `SpanKind` field the conventions expect: LLM,
+EMBEDDING and RETRIEVER spans are CLIENT, everything else INTERNAL. Pass
+`otelKind` to override it, for example CLIENT for a call to a hosted agent.
+Note the name collision: `SpanKind` exported by this package is the taxonomy
+enum; the value for `otelKind` is `SpanKind` from `@opentelemetry/api`, so
+import that one under an alias.
+
+```ts
+import { SpanKind as OtelSpanKind } from "@opentelemetry/api";
+import { SpanKind, startAsCurrentSpan } from "@glassflow-ai/rius";
+
+await startAsCurrentSpan(
+  "delegate-to-planner",
+  { kind: SpanKind.AGENT, otelKind: OtelSpanKind.CLIENT, input: task },
+  async (span) => { ... },
+);
+```
+
 On the manual path, `recordException()` does what the scoped form does for
-you: it records the error and sets ERROR status.
+you: it records the error, sets ERROR status and sets `error.type` to the
+error's name.
 
 ```ts
 const span = startSpan("fetch-documents");
@@ -162,9 +256,27 @@ await startAsCurrentGeneration(
 );
 ```
 
-Each `modelParameters` entry is recorded as `gen_ai.request.<key>`, so use the
-provider's own parameter names. `setFinishReasons` accepts one reason or a
-list.
+`modelParameters` are recorded when the span opens, so they also show up on
+the live (pending) view of a call that is still running. A parameter the
+GenAI conventions define is recorded under its canonical `gen_ai.request.*`
+key, and the provider spellings for it are recognised too:
+`max_completion_tokens`, `maxOutputTokens` and `maxTokens` all become
+`gen_ai.request.max_tokens`, `stop` becomes `gen_ai.request.stop_sequences`,
+and `n` becomes `gen_ai.request.choice.count`. Any other parameter is recorded
+under `rius.request.<key>` with its key unchanged. Tool definitions passed as a
+parameter (`tools`, `functions`) are treated as content and are dropped under
+`captureContent: false`. `setFinishReasons` accepts one reason or a list.
+
+Two more conventions keys sit on either side of the call. `outputType`
+(`gen_ai.output.type`: `text`, `json`, `image` or `speech`) is an option,
+because the output modality is something the request asks for and so is known
+before the span starts. `setResponseId` (`gen_ai.response.id`) is a setter
+alongside `setModel`, because the provider's id for the completion only exists
+once the completion does.
+
+The name is optional here as well: `startAsCurrentGeneration({ model:
+"gpt-4o" }, fn)` names the span `chat gpt-4o`, and an `operation` override
+names it after that operation instead (`embeddings text-embedding-3-small`).
 
 ## Auto-instrumentation
 
@@ -181,8 +293,8 @@ Install only the ones you use:
 - **`openai`** wraps the OpenAI SDK, via `@arizeai/openinference-instrumentation-openai`, turning provider calls into spans.
 - **`anthropic`** wraps the Anthropic SDK, via `@arizeai/openinference-instrumentation-anthropic`, turning Messages calls into LLM spans with model, messages and token counts.
 - **`langchain`** traces LangChain.js chains, models, tools and retrievers, via `@arizeai/openinference-instrumentation-langchain`. It patches the callback manager in `@langchain/core`, which every LangChain.js application already has, and the SDK resolves that module for you so nothing has to be passed in at `init()`.
-- **`vercel-ai`** attaches to spans the Vercel AI SDK's own OpenTelemetry integration produces, via `@arizeai/openinference-vercel`, adding OpenInference attributes to them. This package requires Node 22 or newer.
-- **`mcp`** patches `@modelcontextprotocol/sdk`'s `Client.callTool` so every MCP tool call becomes a TOOL span, carrying the tool name, arguments, result, latency, and error status.
+- **`vercel-ai`** attaches to spans the Vercel AI SDK's own OpenTelemetry integration produces, via `@arizeai/openinference-vercel`, adding OpenInference attributes to them. It touches only spans in the AI SDK's `ai.*` dialect (v5/v6, recognised by their `ai.operationId`): your own spans, other instrumentations' spans and the GenAI-native spans of AI SDK v7's `@ai-sdk/otel` integration are exported exactly as they would be without it. This package requires Node 22 or newer.
+- **`mcp`** patches `@modelcontextprotocol/sdk`'s `Client.callTool` so every MCP tool call becomes a TOOL span named `execute_tool <tool>`, carrying the tool name, arguments, result, latency, and error status. The span follows the OpenTelemetry MCP conventions: OTel `SpanKind` CLIENT, `mcp.method.name` set to `tools/call`, `mcp.protocol.version` set to the negotiated version when the transport exposes it (Streamable HTTP does; stdio and SSE do not), and `error.type` set to `tool_error` when the server returns an `isError` result.
 
 There is no selection option: `init()` always attempts every bundled
 integration, so which ones actually attach is determined entirely by
@@ -230,6 +342,7 @@ variables, then the defaults below.
 | `endpoint`        | `RIUS_ENDPOINT`          | `https://ingest.eu.console.rius-glassflow.com` |
 | `apiKey`           | `RIUS_API_KEY`           | none                                          |
 | `serviceName`      | `RIUS_SERVICE_NAME`      | `unknown_service`                             |
+| `serviceVersion`   | `RIUS_SERVICE_VERSION`   | none (also read from `service.version` in `OTEL_RESOURCE_ATTRIBUTES`; left off the resource when unset, never defaulted) |
 | `disabled`         | `RIUS_DISABLED`          | `false`                                       |
 | `sampleRate`       | `RIUS_SAMPLE_RATE`       | `1.0`                                         |
 | `captureContent`   | `RIUS_CAPTURE_CONTENT`   | `true`                                        |
@@ -237,12 +350,52 @@ variables, then the defaults below.
 | `heartbeat`        | `RIUS_HEARTBEAT`         | `true`                                        |
 | `heartbeatInterval` | `RIUS_HEARTBEAT_INTERVAL` | `15` (seconds; clamped 5-300)               |
 | `agentName`        | `RIUS_AGENT_NAME`        | `serviceName`                                 |
+| `mainAgentId`      | `RIUS_MAIN_AGENT_ID`     | none (a STABLE id for the agent this process is; never a transient in-memory id) |
+| `mainAgentDescription` | `RIUS_MAIN_AGENT_DESCRIPTION` | none                                |
+| `mainAgentVersion` | `RIUS_MAIN_AGENT_VERSION` | none (the version of the AGENT DEFINITION, never derived from `serviceVersion`) |
 | `partialSpans`     | `RIUS_PARTIAL_SPANS`     | `false`                                       |
 | `partialSpansDelay` | `RIUS_PARTIAL_SPANS_DELAY` | `0` (seconds; clamped 0-60)                |
 | `sessionId`        | `RIUS_SESSION_ID`        | none (process-wide session default; `withSession` overrides it) |
+| `bridgeForeignProvider` | `RIUS_BRIDGE_FOREIGN_PROVIDER` | `false` (also export the spans of another OpenTelemetry SDK that owns the global provider; see below) |
 
 Traces are posted to `<endpoint>/v1/traces`.
 
+`serviceVersion` is stamped on the resource as `service.version`, so the
+console can tell one build of an agent from another. It has no default on
+purpose: an invented version would put every unversioned process under the
+same wrong number, the way `unknown_service` does for unnamed ones, so the
+key is simply absent until you supply one. This SDK builds its resource
+explicitly, which in OpenTelemetry for JavaScript means the OTel environment
+is not merged into it, so `OTEL_RESOURCE_ATTRIBUTES=service.version=...` is
+read here by hand as the last tier after the option and `RIUS_SERVICE_VERSION`.
+
+The agent this process *is* is described on the resource under
+`rius.main_agent.*`: `rius.main_agent.name` (the resolved `agentName`, absent
+when nothing was named and it is still the `unknown_service` placeholder),
+plus the optional `rius.main_agent.id`, `.description` and `.version`.
+`gen_ai.agent.name` is still stamped alongside them, unchanged: the new keys
+are additive so that no deployment loses its agent identity between an SDK
+upgrade and a backend one. The vendor namespace exists because
+`gen_ai.agent.name` has no resource-level meaning in the conventions and on a
+span means the agent being *invoked*, so one key was answering two questions.
+
+`mainAgentId` must be a **stable** identifier — a registry id, a hosted
+agent's ARN. A uuid minted at startup or another process-local id identifies
+a *run*, not an agent, and would split one agent into a fresh bucket per
+restart; `service.instance.id` already answers "which process".
+
+Three versions travel separately and none is ever derived from another:
+
+| Key                        | Answers                                             |
+| -------------------------- | --------------------------------------------------- |
+| `service.version`          | which build of the deployment is running             |
+| `rius.main_agent.version`  | which version of the agent *definition* it runs — its prompt, tools and policy |
+| `gen_ai.agent.version`     | which version of the agent a given AGENT span *invoked* |
+
+A service can sit at `2.3.1` while the agent definition it runs is at `7` and
+the agent it calls out to is at `1.0.0`; a prompt change moves the second
+without touching the first.
+
 `captureContent` controls whether input/output content (prompts,
 completions, tool arguments) is attached to spans. It defaults to
 `true`. Set it to `false`, or supply a `mask` function, if your spans
@@ -267,6 +420,27 @@ optional integration is loaded, so no third-party module is patched in your
 process. `client.ready` resolves to an empty list. Spans can still be
 created and are simply dropped.
 
+### Running next to another OpenTelemetry SDK
+
+OpenTelemetry has one global tracer provider per process, and the first
+registration wins. If another SDK (Langfuse v3, for one) claims it before
+`init()`, your own job and tool spans go to that SDK only, while the LLM spans
+inside them still reach Rius — so Rius receives traces whose parents it never
+gets. Rius detects this whatever you configure: those LLM spans carry
+`rius.parent.foreign=true`, the resource records
+`rius.sdk.global_provider=foreign:<class>`, and the first one logs a warning.
+
+To send the other SDK's spans to Rius as well, opt in with
+`init({ bridgeForeignProvider: true })` or `RIUS_BRIDGE_FOREIGN_PROVIDER=true`.
+Rius then attaches its own pipeline to that provider and exports its spans too,
+subject to Rius's `sampleRate`, `captureContent` and `mask`, under the Rius
+resource identity. It never modifies what the other SDK exports: that vendor
+receives exactly what it would without Rius.
+
+```typescript
+init({ bridgeForeignProvider: true }) // export the other SDK's spans as well
+```
+
 ## Agent liveness
 
 Traces only leave the process when a span ends, so an idle-but-alive agent
@@ -293,8 +467,9 @@ graceful exit if you want that distinction to show up.
 
 The heartbeat never keeps the process alive, its timer is unref'd, and never
 throws into your code; delivery failures are logged once per client and
-silent after that. `agentName` identifies the agent in heartbeat payloads
-and defaults to `serviceName`.
+silent after that. `agentName` identifies the agent in heartbeat payloads and
+on every span, where it is stamped on the resource as `gen_ai.agent.name`. It
+defaults to `serviceName`, so the two agree unless you set it.
 
 ### Partial spans
 
@@ -346,6 +521,27 @@ Batching is tunable via the standard OpenTelemetry env vars:
 `OTEL_BSP_SCHEDULE_DELAY` (default 5000 ms), `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
 (default 512), and `OTEL_BSP_EXPORT_TIMEOUT` (default 30000 ms).
 
+### Span attribute limit
+
+OpenTelemetry caps a span at 128 attributes by default, and a span that
+reaches the cap silently refuses every new key. OpenInference writes one
+attribute per message field and per tool field, so an agent loop with ten
+tools passes 128 after about nine turns, and the keys written last are
+the ones that matter most: the token usage (so cost), the output messages,
+`output.value` and the finish reason.
+
+`init()` therefore raises the span attribute count limit to 4096. The
+standard variables still win: if `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` or
+`OTEL_ATTRIBUTE_COUNT_LIMIT` is set to a number, `init()` leaves the limit
+to OpenTelemetry, which applies that value. The attribute value-length
+limit is not changed.
+
+If you run the OpenInference instrumentations **without** this SDK, on a
+tracer provider of your own, set the limit yourself, for example
+`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT=4096`, or pass
+`spanLimits: { attributeCountLimit: 4096 }` to your provider. Otherwise
+long agent calls lose their usage and output.
+
 ## Development
 
 ```bash