@telemetry-dev/tanstack-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telemetry.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @telemetry-dev/tanstack-ai
+
+TanStack AI telemetry integration for [telemetry.dev](https://telemetry.dev). A `chat()` middleware
+that streams every run to the telemetry.dev ingest API. Each `chat()` call is its own OTel trace: a
+root span (operation `chat`, or `invoke_agent` once tools are used), a `chat` span per agent-loop
+iteration, and an `execute_tool` span per tool call — spans are typed by `gen_ai.operation.name`.
+Conversations are carried by `gen_ai.conversation.id` (lifted from `metadata.sessionId`, falling
+back to the chat's `threadId`), not by sharing one trace.
+
+## Install
+
+```sh
+npm install @telemetry-dev/tanstack-ai @tanstack/ai
+```
+
+Requires `@tanstack/ai >= 0.28.0 < 1`.
+
+## Environment
+
+| Variable                    | Required | Default                        | Notes                                                                  |
+| --------------------------- | -------- | ------------------------------ | ---------------------------------------------------------------------- |
+| `TELEMETRY_DEV_API_KEY`     | yes      | —                              | Ingest key (`td_live_…`). No key ⇒ the middleware is a complete no-op. |
+| `TELEMETRY_DEV_BASE_URL`    | no       | `https://ingest.telemetry.dev` | Trailing slashes are stripped.                                         |
+| `TELEMETRY_DEV_ENVIRONMENT` | no       | `production`                   | Environment label on every trace.                                      |
+| `OTEL_SERVICE_NAME`         | no       | `unknown_service`              | Service name on every trace.                                           |
+
+All four are also settable via `telemetryDev({ apiKey, baseUrl, environment, serviceName })`, which
+takes precedence over the environment.
+
+## Usage
+
+```ts
+import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+import { telemetryDev } from "@telemetry-dev/tanstack-ai";
+
+const stream = chat({
+  adapter: openaiText("gpt-4o"),
+  messages,
+  metadata: { userId: "u_123", sessionId: "s_456", tenant: "acme" },
+  middleware: [telemetryDev()],
+});
+```
+
+`metadata.userId` is recorded as the `user.id` span attribute and `metadata.sessionId` as
+`gen_ai.conversation.id` (when absent, the chat's `threadId` is used); any remaining metadata keys
+ride along as `td.metadata.<key>` attributes. Each call is its own trace — `sessionId` only
+correlates calls through `gen_ai.conversation.id`, it never merges them into a single trace.
+
+A single `telemetryDev()` instance is **concurrency-safe**: per-run state is keyed by the chat's
+middleware context, so you can create one at module scope and share it across overlapping `chat()`
+calls:
+
+```ts
+const telemetry = telemetryDev();
+
+// reuse in every handler
+chat({ adapter, messages, middleware: [telemetry] });
+```
+
+### Serverless (Cloudflare Workers etc.)
+
+By default the terminal hook awaits the ingest POST so the runtime doesn't tear down before it
+flushes. Supply `waitUntil` to hand the POST off to the platform instead:
+
+```ts
+telemetryDev({ waitUntil: (p) => ctx.waitUntil(p) });
+```
+
+## What gets captured
+
+- **Tokens:** input/output per iteration, plus cache-read, cache-write, and reasoning token
+  breakdowns and provider-reported cost when the adapter supplies them
+  (`gen_ai.usage.cache_read.input_tokens`, `gen_ai.usage.cache_creation.input_tokens`,
+  `gen_ai.usage.reasoning.output_tokens`, `gen_ai.usage.cost`). Absent fields are omitted, never
+  zeroed; when no provider cost is reported, cost is computed server-side from pricing tables.
+- **Content:** the per-iteration request messages (`gen_ai.input.messages`, exactly what the
+  adapter sends) and the assistant text (`gen_ai.output.messages`); tool calls carry
+  `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result`.
+- **Sampling:** `gen_ai.request.temperature` / `top_p` / `max_tokens`, read across provider-native
+  spellings (including Ollama's nested `options`).
+- **Errors:** a run that errors or aborts is still flushed — open spans are closed with
+  `status: "error"` and an `error.type` attribute (`"cancelled"` for aborts); failed tool calls get
+  an `exception` event.
+- **Structured output:** when `chat({ outputSchema })` finalizes through a separate
+  structured-output model call, that call gets its own span (`gen_ai.output.type: "json"`, output
+  set to the raw JSON) and its usage is counted alongside — never instead of — the agent loop's.
+- **Metrics:** `gen_ai.client.operation.duration` per iteration and tool call, and
+  `gen_ai.client.token.usage` per iteration, both following the OTel GenAI semantic conventions.
+
+## Limitations
+
+- **TTFT:** time-to-first-chunk is not currently reported.
+- Middleware hook exceptions are wrapped in `try/catch` and routed to the optional `onError`
+  callback so instrumentation can never break your chat.

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import { Attributes } from "@opentelemetry/api";
+import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { ChatMiddleware } from "@tanstack/ai";
+
+//#region src/config.d.ts
+interface TelemetryDevOptions {
+  /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the integration is a no-op. */
+  apiKey?: string;
+  /** Ingest base URL. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
+  environment?: string;
+  /** Service name attached to every trace. Falls back to `OTEL_SERVICE_NAME`, then `unknown_service`. */
+  serviceName?: string;
+  /** Injected fetch implementation. Defaults to `globalThis.fetch`. */
+  fetch?: typeof fetch;
+  /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `onFinish` does not await the POST. */
+  waitUntil?: (p: Promise<unknown>) => void;
+  /** Receives any error raised while emitting telemetry; the integration never throws into the SDK. */
+  onError?: (error: unknown) => void;
+}
+//#endregion
+//#region src/otel.d.ts
+interface EmitterOverrides {
+  sendSpans?: (spans: ReadableSpan[]) => Promise<void>;
+  recordDuration?: (seconds: number, attributes: Attributes) => void;
+  recordTokens?: (tokenType: "input" | "output", count: number, attributes: Attributes) => void;
+}
+//#endregion
+//#region src/middleware.d.ts
+/**
+ * Build a TanStack AI chat middleware that streams `chat()` runs to telemetry.dev as
+ * OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call, one CLIENT
+ * span per agent-loop iteration, and one span per tool execution. Per-run state is keyed by the
+ * middleware context in a WeakMap, so a single `telemetryDev()` instance is safe to share across
+ * concurrent and overlapping `chat()` calls (e.g. registered once at module scope).
+ */
+declare function telemetryDev(options?: TelemetryDevOptions, overrides?: EmitterOverrides): ChatMiddleware;
+//#endregion
+export { type TelemetryDevOptions, telemetryDev };