Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions .github/workflows/fi-core-tanstack.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
name: Core TanStack AI tracing

on:
pull_request:
branches: [main, dev]
paths:
- 'typescript/packages/fi-core/**'
- 'typescript/packages/fi-semantic-conventions/**'
- 'typescript/pnpm-lock.yaml'
- '.github/workflows/fi-core-tanstack.yml'
push:
branches: [dev]
paths:
- 'typescript/packages/fi-core/**'
- 'typescript/packages/fi-semantic-conventions/**'
- 'typescript/pnpm-lock.yaml'
- '.github/workflows/fi-core-tanstack.yml'
workflow_dispatch:

permissions:
contents: read

jobs:
tanstack:
# floor: @tanstack/ai 0.69.0 + OTel SDK 2.0.1; current: 1.0.1 + 2.12.0
name: TanStack AI native tracing (${{ matrix.mode }})
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
mode: [floor, current]
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
persist-credentials: false
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: '22.23.4'
- name: Install, build and pack core; install the packed fixture
working-directory: typescript
run: |
mkdir -p "$RUNNER_TEMP/corepack-bin" "$RUNNER_TEMP/packages"
corepack enable --install-directory "$RUNNER_TEMP/corepack-bin" pnpm
export PATH="$RUNNER_TEMP/corepack-bin:$PATH"
echo "$RUNNER_TEMP/corepack-bin" >> "$GITHUB_PATH"
corepack pnpm --filter @traceai/fi-core... install --frozen-lockfile --ignore-scripts
corepack pnpm --filter @traceai/fi-core... run build
corepack pnpm --dir packages/fi-semantic-conventions pack --pack-destination "$RUNNER_TEMP/packages"
corepack pnpm --dir packages/fi-core pack --pack-destination "$RUNNER_TEMP/packages"
node packages/fi-core/test/install-tanstack-fixture.cjs "$RUNNER_TEMP/fixture" '${{ matrix.mode }}' \
"$RUNNER_TEMP"/packages/traceai-fi-core-*.tgz \
"$RUNNER_TEMP"/packages/traceai-fi-semantic-conventions-*.tgz
- name: Runtime and OTLP wire tests with loopback-only networking
working-directory: typescript
run: |
sudo unshare --net bash -c '
set -euo pipefail
ip link set lo up
export TANSTACK_FIXTURE="$1"
node --test packages/fi-core/test/tanstack.test.mjs
node node_modules/jest/bin/jest.js --config packages/fi-core/jest.config.js --runInBand
' bash "$RUNNER_TEMP/fixture"
28 changes: 28 additions & 0 deletions typescript/packages/fi-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,34 @@ span.setAttributes({
span.end();
```

## TanStack AI

TanStack AI creates the spans with its own `otelMiddleware`. The `@traceai/fi-core/tanstack` subpath supplies the options for that middleware and an isolated Future AGI provider, so you don't add a second instrumentation:

```ts
import { chat } from "@tanstack/ai";
import { otelMiddleware } from "@tanstack/ai/middlewares/otel";
import { flushTraces, registerTanStackTracing, tanStackOtelOptions } from "@traceai/fi-core/tanstack";

const provider = registerTanStackTracing({ projectName: "my-chatbot" });
const tracer = provider.getTracer("tanstack-ai");

const stream = chat({
adapter,
messages,
threadId, // optional: an opaque conversation id
middleware: [otelMiddleware(tanStackOtelOptions(tracer, { threadIdAsSession: Boolean(threadId) }))],
});
```

- **Privacy.** Messages, tool arguments and results, error text and stack traces are not exported by default. `captureContent: true` exports content and error text through your `redact` function; a redactor that throws yields `[redaction_failed]`. Stack traces are never exported.
- **Tokens are counted once.** TanStack also writes the sum of every model call's usage onto the chat span. In the Future AGI export only, that sum moves to `tanstack.ai.root_usage.*` when the model-call spans carry usage. Other exporters on the same provider receive TanStack's spans with the Future AGI enrichment attributes, and the root keeps its usage there.
- **Sessions.** `threadIdAsSession: true` exports the `threadId` you pass to `chat()` as `session.id`. Use an opaque id, never an email address or user name.
- **Existing OpenTelemetry apps.** `registerTanStackTracing()` never replaces the global provider, and each chat starts a new trace unless you pass `joinActiveTrace: true`. To export through a provider you already own instead, wrap your exporter: `new TransformingSpanExporter(exporter, normalizeTanStackSpan)`.
- **Serverless.** `await flushTraces(provider)` waits at most 2 seconds and never throws. In a long-lived server, call `shutdownTraces(provider)` when the process stops.

To test against packed builds (floor `@tanstack/ai` 0.69.0 with OpenTelemetry SDK 2.0.1, and current 1.0.1 with SDK 2.12.0), prepare a fixture with `node test/install-tanstack-fixture.cjs DIR floor|current CORE_TGZ SEMCONV_TGZ`, then run `TANSTACK_FIXTURE=DIR pnpm test:tanstack`.

## Development

### Building
Expand Down
8 changes: 7 additions & 1 deletion typescript/packages/fi-core/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@
"types": "./dist/src/index.d.ts",
"import": "./dist/esm/index.js",
"require": "./dist/src/index.js"
},
"./tanstack": {
"types": "./dist/src/tanstack.d.ts",
"import": "./dist/esm/tanstack.js",
"require": "./dist/src/tanstack.js"
}
},
"scripts": {
Expand All @@ -21,7 +26,8 @@
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"lint": "eslint . --ext .ts",
"prepare": "pnpm run build"
"prepare": "pnpm run build",
"test:tanstack": "node --test test/tanstack.test.mjs"
},
"files": [
"dist",
Expand Down
1 change: 1 addition & 0 deletions typescript/packages/fi-core/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ export * from "./utils";
export type * from "./utils/types";
export * from "./otel";
export * from "./fi_types";
export * from "./spanTransform";
7 changes: 7 additions & 0 deletions typescript/packages/fi-core/src/otel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
SpanStatusCode,
} from "@opentelemetry/api";
import { ProjectType, EvalTag, prepareEvalTags } from "./fi_types";
import { SpanTransform, TransformingSpanExporter } from "./spanTransform";
import { ExportResult, ExportResultCode } from "@opentelemetry/core";
import {
ReadableSpan,
Expand Down Expand Up @@ -345,6 +346,7 @@ interface FITracerProviderOptions {
endpoint?: string; // Custom endpoint (can be base or full, _constructFullEndpoint will handle)
headers?: FIHeaders;
transport?: Transport; // Transport type
spanTransform?: SpanTransform;
}

class FITracerProvider extends BasicTracerProvider {
Expand Down Expand Up @@ -382,6 +384,7 @@ class FITracerProvider extends BasicTracerProvider {
exporter = new _OTLPHTTPTraceExporter({ url: endpoint, headers });
}

if (config.spanTransform) exporter = new TransformingSpanExporter(exporter, config.spanTransform);
const defaultProcessor = new OTelSimpleSpanProcessor(exporter);
super({ resource: config.resource, idGenerator, spanProcessors: [defaultProcessor] });
this.defaultProcessorAttached = true;
Expand Down Expand Up @@ -472,6 +475,8 @@ export interface RegisterOptions {
endpoint?: string; // Can be a base URL or a full URL. _constructFullEndpoint will resolve.
idGenerator?: IdGenerator;
transport?: Transport; // Transport type: HTTP or GRPC
/** Transform the export view without mutating SDK spans. Failures drop the batch. */
spanTransform?: SpanTransform;
}

function register(options: RegisterOptions = {}): FITracerProvider {
Expand Down Expand Up @@ -578,6 +583,7 @@ if (!projectName) {
endpoint: optEndpoint,
headers: exporterHeaders,
transport,
spanTransform: options.spanTransform,
});

if (batch) {
Expand All @@ -594,6 +600,7 @@ if (!projectName) {
headers: exporterHeaders,
});
}
if (options.spanTransform) batchExporter = new TransformingSpanExporter(batchExporter, options.spanTransform);
const batchProcessor = new OTelBatchSpanProcessor(batchExporter);

(tracerProvider as any)._registeredSpanProcessors = [];
Expand Down
61 changes: 61 additions & 0 deletions typescript/packages/fi-core/src/spanTransform.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
import { ExportResult, ExportResultCode } from "@opentelemetry/core";
import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";

/** Return an export view; never mutate the SDK's ReadableSpan or its attributes. */
export type SpanTransform = (span: ReadableSpan) => ReadableSpan;

/** Compose a normalization/privacy boundary with any standard OTel exporter. */
export class TransformingSpanExporter implements SpanExporter {
constructor(
private readonly exporter: SpanExporter,
private readonly transform: SpanTransform,
) {}

export(spans: ReadableSpan[], callback: (result: ExportResult) => void): void {
let transformed: ReadableSpan[];
try {
transformed = spans.map(this.transform);
} catch {
// A failed privacy transform must not fall back to the original payload.
callback({ code: ExportResultCode.FAILED, error: new Error("Span transformation failed") });
return;
}
this.exporter.export(transformed, callback);
}

forceFlush(): Promise<void> {
return this.exporter.forceFlush?.() ?? Promise.resolve();
}

shutdown(): Promise<void> {
return this.exporter.shutdown();
}
}

/** Preserve SDK getters and method receivers without changing its span. */
export function spanWithAttributes(
span: ReadableSpan,
attributes: ReadableSpan["attributes"],
): ReadableSpan {
const descriptor = Object.getOwnPropertyDescriptor(span, "attributes");
if (descriptor && !descriptor.configurable && !descriptor.writable && !descriptor.set) {
// A frozen span cannot be proxied with different attributes; copy its
// public ReadableSpan fields instead.
return {
name: span.name, kind: span.kind, spanContext: () => span.spanContext(),
parentSpanContext: span.parentSpanContext, startTime: span.startTime,
endTime: span.endTime, status: span.status, attributes, links: span.links,
events: span.events, duration: span.duration, ended: span.ended,
resource: span.resource, instrumentationScope: span.instrumentationScope,
droppedAttributesCount: span.droppedAttributesCount,
droppedEventsCount: span.droppedEventsCount, droppedLinksCount: span.droppedLinksCount,
};
}
return new Proxy(span, {
get(target, property) {
if (property === "attributes") return attributes;
const value = Reflect.get(target, property, target);
return typeof value === "function" ? value.bind(target) : value;
},
});
}
Loading
Loading