diff --git a/.github/workflows/fireworks-typescript-tests.yml b/.github/workflows/fireworks-typescript-tests.yml new file mode 100644 index 000000000..dcbfacc09 --- /dev/null +++ b/.github/workflows/fireworks-typescript-tests.yml @@ -0,0 +1,102 @@ +name: Fireworks TypeScript contracts + +on: + pull_request: + branches: [dev, main] + paths: + - 'typescript/packages/traceai_fireworks/**' + - 'typescript/packages/traceai_openai/**' + - 'typescript/packages/fi-core/**' + - 'typescript/packages/fi-semantic-conventions/**' + - 'typescript/pnpm-lock.yaml' + - '.github/workflows/fireworks-typescript-tests.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + contracts: + name: Fireworks OpenAI SDK ${{ matrix.sdk }} + runs-on: ubuntu-24.04 + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + # Declared floor, each supported major, and the current release. + sdk: ['4.0.0', '5.23.2', '6.0.0', '7.47.0'] + defaults: + run: + shell: bash + working-directory: typescript + 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 pinned workspace dependencies + run: | + mkdir -p "$RUNNER_TEMP/corepack-bin" + corepack enable --install-directory "$RUNNER_TEMP/corepack-bin" pnpm + echo "$RUNNER_TEMP/corepack-bin" >> "$GITHUB_PATH" + corepack pnpm --filter @traceai/fireworks... install --frozen-lockfile --ignore-scripts + - name: Build both packages and install their tarballs in a clean consumer + run: | + pnpm run build:deps + pnpm --filter @traceai/openai --filter @traceai/fireworks run build + pnpm --dir packages/traceai_openai pack --out "$RUNNER_TEMP/openai.tgz" + pnpm --dir packages/traceai_fireworks pack --out "$RUNNER_TEMP/fireworks.tgz" + npm install --prefix "$RUNNER_TEMP/consumer" --ignore-scripts --no-audit --no-fund \ + "$RUNNER_TEMP/openai.tgz" "$RUNNER_TEMP/fireworks.tgz" "openai@${{ matrix.sdk }}" \ + @traceai/fi-core@1.1.0 @traceai/fi-semantic-conventions@1.0.0 \ + @opentelemetry/sdk-trace-base@2.0.1 @opentelemetry/exporter-trace-otlp-http@0.202.0 \ + typescript@5.8.3 @types/node@22.15.29 + - name: Network-isolated automatic, manual and dual-instrumentor contracts + env: + FIREWORKS_CONSUMER_DIR: ${{ runner.temp }}/consumer + run: | + for manual in false true; do + for both in false true; do + sudo unshare --net -- bash -c 'ip link set lo up; exec "$@"' bash \ + env PATH="$PATH" FIREWORKS_CONSUMER_DIR="$FIREWORKS_CONSUMER_DIR" \ + FIREWORKS_TEST_MANUAL="$manual" FIREWORKS_TEST_BOTH="$both" \ + node --test packages/traceai_fireworks/test/sharedRoute.cjs + done + done + - name: Run and typecheck the README recipe + # OpenAI 4.0 sends requests through its node-fetch shim, which the recipe's + # synthetic global fetch cannot intercept. + if: matrix.sdk != '4.0.0' + env: + FIREWORKS_CONSUMER_DIR: ${{ runner.temp }}/consumer + run: | + sudo unshare --net -- bash -c 'ip link set lo up; exec "$@"' bash \ + env PATH="$PATH" FIREWORKS_CONSUMER_DIR="$FIREWORKS_CONSUMER_DIR" \ + node --test packages/traceai_fireworks/test/readme.cjs + "$FIREWORKS_CONSUMER_DIR/node_modules/.bin/tsc" --noEmit --module nodenext --target es2022 \ + "$FIREWORKS_CONSUMER_DIR/fireworks.mts" + - name: Load the ESM build + working-directory: ${{ runner.temp }}/consumer + run: | + node --input-type=module -e " + import { FireworksInstrumentation, isPatched } from '@traceai/fireworks'; + new FireworksInstrumentation().manuallyInstrument(await import('openai')); + if (!isPatched()) throw new Error('ESM SDK module was not instrumented'); + " + - name: Network-isolated package and ownership tests + env: + OPENAI_TEST_MODULE: ${{ runner.temp }}/consumer/node_modules/openai + run: | + sudo unshare --net -- bash -c 'ip link set lo up; exec "$@"' bash \ + env PATH="$PATH" OPENAI_TEST_MODULE="$OPENAI_TEST_MODULE" \ + node packages/traceai_fireworks/node_modules/jest/bin/jest.js \ + --config packages/traceai_fireworks/jest.config.js --runInBand + sudo unshare --net -- bash -c 'ip link set lo up; exec "$@"' bash \ + env PATH="$PATH" OPENAI_TEST_MODULE="$OPENAI_TEST_MODULE" \ + node packages/traceai_openai/node_modules/jest/bin/jest.js \ + --config packages/traceai_openai/jest.config.js --runInBand --runTestsByPath \ + packages/traceai_openai/src/__tests__/patchOwnership.test.ts \ + packages/traceai_openai/src/__tests__/provider.test.ts diff --git a/.github/workflows/openai-sdk-contracts.yml b/.github/workflows/openai-sdk-contracts.yml index 7b2e4ce24..08453fd5c 100644 --- a/.github/workflows/openai-sdk-contracts.yml +++ b/.github/workflows/openai-sdk-contracts.yml @@ -79,7 +79,8 @@ jobs: node packages/traceai_openai/node_modules/jest/bin/jest.js \ --config packages/traceai_openai/jest.config.js --runInBand --runTestsByPath \ packages/traceai_openai/src/__tests__/providerHostsWire.test.ts \ - packages/traceai_openai/src/__tests__/provider.test.ts + packages/traceai_openai/src/__tests__/provider.test.ts \ + packages/traceai_openai/src/__tests__/patchOwnership.test.ts - name: Run and typecheck the ESM README recipe if: matrix.sdk != '4.0.0' env: diff --git a/typescript/packages/traceai_fireworks/README.md b/typescript/packages/traceai_fireworks/README.md index 376922e82..60497e09f 100644 --- a/typescript/packages/traceai_fireworks/README.md +++ b/typescript/packages/traceai_fireworks/README.md @@ -1,138 +1,68 @@ -# @traceai/fireworks +# @traceai/fireworks (deprecated) -OpenTelemetry instrumentation for Fireworks AI - fast and affordable inference for open-source models. +Trace Fireworks AI with [`@traceai/openai`](../traceai_openai/README.md). Fireworks serves an [OpenAI-compatible API](https://docs.fireworks.ai/tools-sdks/openai-compatibility), so the shared OpenAI instrumentor traces it and sets `gen_ai.provider.name=fireworks` for requests sent to `api.fireworks.ai`. -## Installation +`FireworksInstrumentation` remains available for existing applications and delegates to the shared instrumentor. Constructing it emits one `DeprecationWarning` (code `TRACEAI_FIREWORKS_DEPRECATED`) per process. + +## Set up Fireworks tracing ```bash -npm install @traceai/fireworks +npm install @traceai/openai @traceai/fi-core@1.1.0 openai@7.47.0 +export FIREWORKS_API_KEY="your-fireworks-api-key" +export FIREWORKS_MODEL="accounts/fireworks/models/your-model-id" +export FI_API_KEY="your-futureagi-api-key" +export FI_SECRET_KEY="your-futureagi-secret-key" ``` -## Features - -- Automatic tracing of Fireworks AI API calls through OpenAI-compatible interface -- Support for chat completions, text completions, and embeddings -- Streaming response support -- Tool/function calling support -- Token usage tracking -- Full OpenTelemetry semantic conventions compliance - -## Usage - -### Basic Setup +Choose a model available to your Fireworks account. Save as `fireworks.mts` and run `node fireworks.mts` with Node.js 22.23.4 or later: ```typescript -import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; -import { SimpleSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base"; -import { FireworksInstrumentation } from "@traceai/fireworks"; import OpenAI from "openai"; +import { register, ProjectType } from "@traceai/fi-core"; +import { OpenAIInstrumentation } from "@traceai/openai"; -// Set up the tracer provider -const provider = new NodeTracerProvider(); -provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); -provider.register(); +const model = process.env.FIREWORKS_MODEL; +if (!model) throw new Error("Set FIREWORKS_MODEL to a Fireworks model ID."); -// Create and enable the instrumentation -const instrumentation = new FireworksInstrumentation(); +const provider = register({ + projectName: "fireworks-app", + projectType: ProjectType.OBSERVE, +}); +const instrumentation = new OpenAIInstrumentation(); instrumentation.setTracerProvider(provider); -instrumentation.enable(); - -// Manually instrument the OpenAI module -const openaiModule = await import("openai"); -instrumentation.manuallyInstrument(openaiModule); +instrumentation.manuallyInstrument(OpenAI); -// Create the Fireworks client const client = new OpenAI({ - baseURL: "https://api.fireworks.ai/inference/v1", apiKey: process.env.FIREWORKS_API_KEY, + baseURL: "https://api.fireworks.ai/inference/v1", }); - -// Make requests - they will be automatically traced -const response = await client.chat.completions.create({ - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [ - { role: "system", content: "You are a helpful assistant." }, - { role: "user", content: "Hello!" }, - ], -}); -``` - -### Streaming Responses - -```typescript -const stream = await client.chat.completions.create({ - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [{ role: "user", content: "Count to 5." }], - stream: true, -}); - -for await (const chunk of stream) { - process.stdout.write(chunk.choices[0]?.delta?.content || ""); +try { + const response = await client.chat.completions.create({ + model, + messages: [{ role: "user", content: "Say hello in one sentence." }], + }); + console.log(response.choices[0].message.content); +} finally { + instrumentation.disable(); + await provider.shutdown(); } ``` -### Text Completions - -```typescript -const completion = await client.completions.create({ - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - prompt: "The quick brown fox", - max_tokens: 50, -}); -``` - -### Embeddings +Open **Observe → fireworks-app** to see an **OpenAI Chat Completions** span with `gen_ai.provider.name=fireworks`, the model, latency and reported token usage. Chat completions, legacy completions and embeddings are traced, including streams and failed requests. Fully consume streams before shutting down the provider. -```typescript -const embedding = await client.embeddings.create({ - model: "nomic-ai/nomic-embed-text-v1.5", - input: "Hello, world!", -}); +For CommonJS, you can instead construct the instrumentation before `require("openai")` and skip `manuallyInstrument`. To keep prompts, completions and error messages out of telemetry, pass `traceConfig: { hideInputs: true, hideOutputs: true, hideErrorDetails: true }` to `OpenAIInstrumentation`. -console.log(`Embedding dimensions: ${embedding.data[0].embedding.length}`); -``` +## Migrate from FireworksInstrumentation -### Batch Embeddings +1. Install `@traceai/openai` and replace `FireworksInstrumentation` with `OpenAIInstrumentation`. The constructor options, `setTracerProvider`, `manuallyInstrument` and `disable` are the same. +2. Remove `@traceai/fireworks` from your dependencies. -```typescript -const embeddings = await client.embeddings.create({ - model: "nomic-ai/nomic-embed-text-v1.5", - input: ["Hello", "World", "How are you?"], -}); - -console.log(`Generated ${embeddings.data.length} embeddings`); -``` +Behavior to expect after upgrading `@traceai/fireworks`, before or after migrating: -## Configuration Options - -| Option | Type | Description | -|--------|------|-------------| -| `instrumentationConfig` | `InstrumentationConfig` | OpenTelemetry instrumentation config | -| `traceConfig` | `TraceConfigOptions` | TraceAI config (hideInputs, hideOutputs, etc.) | - -## Captured Attributes - -| Attribute | Description | -|-----------|-------------| -| `fi.span.kind` | "LLM" for chat/completions, "EMBEDDING" for embeddings | -| `llm.system` | "fireworks" | -| `llm.provider` | "fireworks" | -| `llm.model` | Model name | -| `llm.token_count.prompt` | Input token count | -| `llm.token_count.completion` | Output token count | -| `llm.token_count.total` | Total token count | -| `embedding.model` | Embedding model name | -| `embedding.embeddings.{n}.text` | Input text for embedding | -| `embedding.embeddings.{n}.vector` | Embedding vector (JSON string) | - -## Popular Models - -| Model | Description | -|-------|-------------| -| `accounts/fireworks/models/llama-v3p1-8b-instruct` | Llama 3.1 8B Instruct | -| `accounts/fireworks/models/llama-v3p1-70b-instruct` | Llama 3.1 70B Instruct | -| `accounts/fireworks/models/mixtral-8x7b-instruct` | Mixtral 8x7B Instruct | -| `nomic-ai/nomic-embed-text-v1.5` | Nomic embedding model | +- Every OpenAI SDK client in the process is traced, not only Fireworks clients. Each span's provider comes from its client's API host. Unknown hosts, such as custom proxies, keep the `openai` fallback. +- Span names are `OpenAI Chat Completions`, `OpenAI Completions` and `OpenAI Embeddings`. The instrumentation scope is the shared OpenAI instrumentor. +- If both `FireworksInstrumentation` and `OpenAIInstrumentation` are enabled, each request produces one span. The instrumentor that patched the SDK first applies its tracer provider and `traceConfig`. Disable both at shutdown. +- The supported OpenAI SDK range is `^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0`. ## License diff --git a/typescript/packages/traceai_fireworks/examples/example.ts b/typescript/packages/traceai_fireworks/examples/example.ts index ef964127f..b465deb06 100644 --- a/typescript/packages/traceai_fireworks/examples/example.ts +++ b/typescript/packages/traceai_fireworks/examples/example.ts @@ -1,24 +1,22 @@ /** - * Example: Using Fireworks AI instrumentation with TraceAI + * Example: trace Fireworks AI with the shared OpenAI instrumentor. * - * This example demonstrates how to set up and use the @traceai/fireworks - * instrumentation to trace Fireworks AI API calls. - * - * Fireworks AI uses OpenAI-compatible API, so you use the OpenAI SDK with a custom baseURL. + * Fireworks serves an OpenAI-compatible API, so the OpenAI SDK with a Fireworks + * baseURL is traced by @traceai/openai. Spans for api.fireworks.ai carry + * gen_ai.provider.name=fireworks. @traceai/fireworks is deprecated. */ -import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; -import { SimpleSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base"; -import { FireworksInstrumentation } from "@traceai/fireworks"; +import { BasicTracerProvider, SimpleSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base"; +import { OpenAIInstrumentation } from "@traceai/openai"; import OpenAI from "openai"; async function main() { // Step 1: Set up the tracer provider - const provider = new NodeTracerProvider(); - provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); - provider.register(); + const provider = new BasicTracerProvider({ + spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())], + }); - // Step 2: Create and enable the instrumentation - const instrumentation = new FireworksInstrumentation({ + // Step 2: Create the instrumentation + const instrumentation = new OpenAIInstrumentation({ traceConfig: { // Optional: Configure tracing options // hideInputs: true, // Hide input content in traces @@ -26,11 +24,9 @@ async function main() { }, }); instrumentation.setTracerProvider(provider); - instrumentation.enable(); - // Step 3: Import and patch the OpenAI module - const openaiModule = await import("openai"); - instrumentation.manuallyInstrument(openaiModule); + // Step 3: Patch the explicitly imported OpenAI SDK + instrumentation.manuallyInstrument(OpenAI); // Step 4: Create the Fireworks AI client (OpenAI SDK with custom baseURL) const client = new OpenAI({ @@ -99,7 +95,7 @@ async function main() { console.log("First 5 values:", embeddingResponse.data[0]?.embedding.slice(0, 5)); console.log("\n"); - // Shutdown provider + instrumentation.disable(); await provider.shutdown(); console.log("Done! Check the console output above for trace spans."); } diff --git a/typescript/packages/traceai_fireworks/examples/package.json b/typescript/packages/traceai_fireworks/examples/package.json index 36b615494..875d3918e 100644 --- a/typescript/packages/traceai_fireworks/examples/package.json +++ b/typescript/packages/traceai_fireworks/examples/package.json @@ -2,15 +2,14 @@ "name": "@traceai/fireworks-examples", "version": "0.1.0", "private": true, - "description": "Examples for @traceai/fireworks", + "description": "Example: trace Fireworks AI with @traceai/openai", "scripts": { "example": "ts-node example.ts" }, "dependencies": { - "@traceai/fireworks": "workspace:*", - "@opentelemetry/sdk-trace-node": "^1.21.0", - "@opentelemetry/sdk-trace-base": "^1.21.0", - "openai": "^4.0.0", + "@traceai/openai": "workspace:*", + "@opentelemetry/sdk-trace-base": "^2.0.1", + "openai": "^7.0.0", "dotenv": "^16.3.1" }, "devDependencies": { diff --git a/typescript/packages/traceai_fireworks/jest.config.js b/typescript/packages/traceai_fireworks/jest.config.js index 419110247..7b8631d89 100644 --- a/typescript/packages/traceai_fireworks/jest.config.js +++ b/typescript/packages/traceai_fireworks/jest.config.js @@ -4,6 +4,12 @@ module.exports = { testMatch: ["**/src/**/*.test.ts"], testPathIgnorePatterns: ["/node_modules/", "e2e\\.test\\.ts$"], moduleFileExtensions: ["ts", "js", "json"], + // Test against workspace sources so the shared route does not need a prior build. + moduleNameMapper: { + "^@traceai/openai$": "/../traceai_openai/src", + "^@traceai/fi-core$": "/../fi-core/src", + "^@traceai/fi-semantic-conventions$": "/../fi-semantic-conventions/src", + }, collectCoverageFrom: ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/__tests__/**"], coverageDirectory: "coverage", verbose: true, diff --git a/typescript/packages/traceai_fireworks/package.json b/typescript/packages/traceai_fireworks/package.json index 8b3a8aa3d..bfc36f32b 100644 --- a/typescript/packages/traceai_fireworks/package.json +++ b/typescript/packages/traceai_fireworks/package.json @@ -1,7 +1,7 @@ { "name": "@traceai/fireworks", "version": "0.1.1", - "description": "TraceAI instrumentation for Fireworks AI", + "description": "Deprecated: use @traceai/openai for Fireworks AI tracing", "main": "dist/cjs/index.js", "module": "dist/esm/index.js", "types": "dist/cjs/index.d.ts", @@ -41,15 +41,12 @@ "directory": "typescript/packages/traceai_fireworks" }, "dependencies": { - "@opentelemetry/api": "^1.9.0", - "@opentelemetry/core": "^1.29.0", - "@opentelemetry/instrumentation": "^0.56.0", - "@traceai/fi-core": "workspace:^", - "@traceai/fi-semantic-conventions": "workspace:^" + "@traceai/openai": "workspace:^" }, "devDependencies": { - "@opentelemetry/sdk-trace-base": "^1.29.0", - "@opentelemetry/sdk-trace-node": "^1.29.0", + "@opentelemetry/api": "^1.9.0", + "@opentelemetry/sdk-trace-base": "^2.0.1", + "@traceai/fi-core": "workspace:^", "@types/jest": "^29.5.14", "@types/node": "^22.10.5", "jest": "^29.7.0", @@ -60,12 +57,7 @@ "typescript": "^5.7.2" }, "peerDependencies": { - "openai": ">=4.0.0" - }, - "peerDependenciesMeta": { - "openai": { - "optional": true - } + "openai": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" }, "engines": { "node": ">=18.0.0" diff --git a/typescript/packages/traceai_fireworks/src/__tests__/instrumentation.test.ts b/typescript/packages/traceai_fireworks/src/__tests__/instrumentation.test.ts index 39e9d46c6..265ce47d0 100644 --- a/typescript/packages/traceai_fireworks/src/__tests__/instrumentation.test.ts +++ b/typescript/packages/traceai_fireworks/src/__tests__/instrumentation.test.ts @@ -1,438 +1,224 @@ -import { FireworksInstrumentation, isPatched } from "../instrumentation"; -import { InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"; -import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; -import { SemanticConventions, FISpanKind, MimeType, LLMSystem, LLMProvider } from "@traceai/fi-semantic-conventions"; - -describe("FireworksInstrumentation", () => { - let instrumentation: FireworksInstrumentation; - let memoryExporter: InMemorySpanExporter; - let provider: NodeTracerProvider; +import { SpanStatusCode, trace } from "@opentelemetry/api"; +import { + BasicTracerProvider, + InMemorySpanExporter, + ReadableSpan, + SimpleSpanProcessor, +} from "@opentelemetry/sdk-trace-base"; +import { OpenAIInstrumentation } from "@traceai/openai"; +import { FireworksInstrumentation, isPatched } from ".."; + +// Use the real SDK; matrix jobs may provide a separately installed version. +const sdk = require(process.env.OPENAI_TEST_MODULE || "openai"); +const OpenAI = sdk.OpenAI; + +const FIREWORKS = "https://api.fireworks.ai/inference/v1"; +const OPENAI = "https://api.openai.com/v1"; +const SECRET = "SYNTHETIC-PRIVATE-CONTENT"; +type Operation = "chat" | "completions" | "embeddings"; +type Outcome = "success" | "error" | "stream"; + +function payload(operation: Operation) { + if (operation === "embeddings") { + return { object: "list", model: "returned-model", data: [{ index: 0, object: "embedding", embedding: [0.1] }], usage: { prompt_tokens: 2, total_tokens: 2 } }; + } + return { + id: "synthetic-id", + created: 1, + model: "returned-model", + object: operation === "chat" ? "chat.completion" : "text_completion", + choices: [{ index: 0, message: { role: "assistant", content: SECRET }, text: SECRET, finish_reason: "stop" }], + usage: { prompt_tokens: 2, completion_tokens: 3, total_tokens: 5 }, + }; +} + +function chunk(operation: Operation) { + return { + id: "synthetic-id", + created: 1, + model: "returned-model", + object: operation === "chat" ? "chat.completion.chunk" : "text_completion", + choices: [{ index: 0, delta: { role: "assistant", content: SECRET }, text: SECRET, finish_reason: "stop" }], + }; +} + +// The configured host stays real, so provider attribution is exercised, but the +// transport never leaves the process. +function client(baseURL: string, outcome: Outcome, operation: Operation) { + return new OpenAI({ + apiKey: "synthetic-unused-key", + baseURL, + maxRetries: 0, + fetch: async () => { + if (outcome === "error") { + return new Response(JSON.stringify({ error: { message: "synthetic failure", type: "invalid_request_error" } }), { + status: 400, + headers: { "content-type": "application/json" }, + }); + } + if (outcome === "stream") { + return new Response(`data: ${JSON.stringify(chunk(operation))}\n\ndata: [DONE]\n\n`, { + headers: { "content-type": "text/event-stream" }, + }); + } + return new Response(JSON.stringify(payload(operation)), { headers: { "content-type": "application/json" } }); + }, + }); +} + +async function call(baseURL: string, operation: Operation, outcome: Outcome) { + const c = client(baseURL, outcome, operation); + const stream = outcome === "stream" ? { stream: true } : {}; + const request = + operation === "chat" + ? c.chat.completions.create({ model: "accounts/fireworks/models/synthetic", messages: [{ role: "user", content: SECRET }], ...stream }) + : operation === "completions" + ? c.completions.create({ model: "accounts/fireworks/models/synthetic", prompt: SECRET, ...stream }) + : c.embeddings.create({ model: "nomic-ai/synthetic", input: "synthetic embedding", encoding_format: "float" }); + if (outcome === "error") { + await expect(request).rejects.toThrow(); + return; + } + const result = await request; + if (outcome === "stream") { + // eslint-disable-next-line @typescript-eslint/no-unused-vars + for await (const _ of result) { + // Consume the stream so its span ends. + } + } +} + +const attr = (span: ReadableSpan, key: string) => span.attributes[key]; + +describe("FireworksInstrumentation (deprecated shared-route delegate)", () => { + const exporter = new InMemorySpanExporter(); + const provider = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] }); + let instrumentations: { disable(): void }[] = []; + let emitWarning: jest.SpyInstance; + + beforeAll(() => { + // The documented setup registers the provider before constructing instrumentation. + trace.setGlobalTracerProvider(provider); + }); beforeEach(() => { - memoryExporter = new InMemorySpanExporter(); - provider = new NodeTracerProvider({ - spanProcessors: [new SimpleSpanProcessor(memoryExporter)], - }); - provider.register(); + exporter.reset(); + emitWarning = jest.spyOn(process, "emitWarning").mockImplementation(() => undefined); + }); - instrumentation = new FireworksInstrumentation(); - instrumentation.setTracerProvider(provider); - instrumentation.enable(); + afterEach(() => { + for (const instrumentation of instrumentations.reverse()) instrumentation.disable(); + instrumentations = []; + emitWarning.mockRestore(); }); - afterEach(async () => { - memoryExporter.reset(); + afterAll(async () => { await provider.shutdown(); + trace.disable(); }); - describe("constructor", () => { - it("should create instrumentation with default config", () => { - const inst = new FireworksInstrumentation(); - expect(inst.instrumentationName).toBe("@traceai/fireworks"); - }); + function fireworks(traceConfig?: ConstructorParameters[0]) { + const instrumentation = new FireworksInstrumentation(traceConfig); + instrumentation.setTracerProvider(provider); + instrumentation.manuallyInstrument(sdk); + instrumentations.push(instrumentation); + return instrumentation; + } - it("should create instrumentation with custom config", () => { - const inst = new FireworksInstrumentation({ - instrumentationConfig: { enabled: true }, - traceConfig: { hideInputs: true }, - }); - expect(inst.instrumentationName).toBe("@traceai/fireworks"); - }); + function shared() { + const instrumentation = new OpenAIInstrumentation(); + instrumentation.setTracerProvider(provider); + instrumentation.manuallyInstrument(sdk); + instrumentations.push(instrumentation); + return instrumentation; + } + + const cases: [Operation, Outcome][] = [ + ["chat", "success"], + ["chat", "stream"], + ["chat", "error"], + ["completions", "success"], + ["completions", "stream"], + ["completions", "error"], + ["embeddings", "success"], + ["embeddings", "error"], + ]; + + it.each(cases)("exports one Fireworks-attributed span for %s %s", async (operation, outcome) => { + fireworks(); + await call(FIREWORKS, operation, outcome); + const spans = exporter.getFinishedSpans(); + expect(spans).toHaveLength(1); + expect(attr(spans[0], "gen_ai.provider.name")).toBe("fireworks"); + if (outcome === "error") expect(spans[0].status.code).toBe(SpanStatusCode.ERROR); + else expect(spans[0].status.code).not.toBe(SpanStatusCode.ERROR); + expect(isPatched()).toBe(true); }); - describe("isPatched", () => { - it("should return a boolean", () => { - expect(typeof isPatched()).toBe("boolean"); - }); + it("attributes each client in a mixed process by its own host", async () => { + fireworks(); + await call(FIREWORKS, "chat", "success"); + await call(OPENAI, "chat", "success"); + expect(exporter.getFinishedSpans().map((span) => attr(span, "gen_ai.provider.name"))).toEqual(["fireworks", "openai"]); }); - describe("isFireworksRequest", () => { - it("should identify Fireworks API requests", () => { - const isFireworksRequest = (instrumentation as unknown as { isFireworksRequest: (client: unknown) => boolean }).isFireworksRequest; - - expect(isFireworksRequest.call(instrumentation, { baseURL: "https://api.fireworks.ai/inference/v1" })).toBe(true); - expect(isFireworksRequest.call(instrumentation, { baseURL: "https://fireworks.example.com/v1" })).toBe(true); - expect(isFireworksRequest.call(instrumentation, { baseURL: "https://api.openai.com/v1" })).toBe(false); - }); + it("produces exactly one span when the shared instrumentor is also enabled", async () => { + fireworks(); + shared(); + await call(FIREWORKS, "chat", "stream"); + await call(FIREWORKS, "embeddings", "success"); + expect(exporter.getFinishedSpans().map((span) => attr(span, "gen_ai.provider.name"))).toEqual(["fireworks", "fireworks"]); }); - describe("chat.completions.create wrapper", () => { - let mockOriginal: jest.Mock; - let patchedFn: (body: Record, options?: Record) => Promise; - - beforeEach(() => { - mockOriginal = jest.fn().mockResolvedValue({ - id: "chatcmpl-123", - object: "chat.completion", - created: 1677652288, - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - choices: [ - { - index: 0, - message: { - role: "assistant", - content: "Hello! How can I help you today?", - }, - finish_reason: "stop", - }, - ], - usage: { - prompt_tokens: 10, - completion_tokens: 12, - total_tokens: 22, - }, - }); - - const wrapperFactory = (instrumentation as unknown as { - createChatCompletionWrapper: (inst: FireworksInstrumentation) => (original: jest.Mock) => typeof patchedFn; - }).createChatCompletionWrapper(instrumentation); - patchedFn = wrapperFactory(mockOriginal).bind({ baseURL: "https://api.fireworks.ai/inference/v1" }); - }); - - it("should create a span for chat completions", async () => { - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [ - { role: "user", content: "Hello!" }, - ], - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - expect(spans.length).toBe(1); - expect(spans[0].name).toBe("Fireworks Chat Completions"); - }); - - it("should set correct attributes for chat completion", async () => { - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [ - { role: "system", content: "You are a helpful assistant." }, - { role: "user", content: "Hello!" }, - ], - temperature: 0.7, - max_tokens: 100, - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[SemanticConventions.FI_SPAN_KIND]).toBe(FISpanKind.LLM); - expect(span.attributes[SemanticConventions.LLM_MODEL_NAME]).toBe("accounts/fireworks/models/llama-v3p1-8b-instruct"); - expect(span.attributes[SemanticConventions.LLM_PROVIDER]).toBe(LLMProvider.FIREWORKS); - expect(span.attributes[SemanticConventions.INPUT_MIME_TYPE]).toBe(MimeType.JSON); - }); - - it("should capture input messages", async () => { - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [ - { role: "system", content: "You are a helpful assistant." }, - { role: "user", content: "Hello!" }, - ], - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - const inputMessages = JSON.parse(span.attributes[SemanticConventions.LLM_INPUT_MESSAGES] as string); - expect(inputMessages[0].role).toBe("system"); - expect(inputMessages[0].content).toBe("You are a helpful assistant."); - }); - - it("should capture token usage", async () => { - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [ - { role: "user", content: "Hello!" }, - ], - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[SemanticConventions.LLM_TOKEN_COUNT_PROMPT]).toBe(10); - expect(span.attributes[SemanticConventions.LLM_TOKEN_COUNT_COMPLETION]).toBe(12); - expect(span.attributes[SemanticConventions.LLM_TOKEN_COUNT_TOTAL]).toBe(22); - }); - - it("should handle errors gracefully", async () => { - const error = new Error("API Error"); - mockOriginal.mockRejectedValueOnce(error); - - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [ - { role: "user", content: "Hello!" }, - ], - }; - - await expect(patchedFn(body)).rejects.toThrow("API Error"); - - const spans = memoryExporter.getFinishedSpans(); - expect(spans.length).toBe(1); - expect(spans[0].status.code).toBe(2); - }); + it("keeps tracing when the instrumentor that did not patch is disabled", async () => { + fireworks(); + const second = shared(); + second.disable(); + await call(FIREWORKS, "chat", "success"); + expect(exporter.getFinishedSpans()).toHaveLength(1); }); - describe("completions.create wrapper", () => { - let mockOriginal: jest.Mock; - let patchedFn: (body: Record, options?: Record) => Promise; - - beforeEach(() => { - mockOriginal = jest.fn().mockResolvedValue({ - id: "cmpl-123", - object: "text_completion", - created: 1677652288, - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - choices: [ - { - text: " jumped over the lazy dog.", - index: 0, - finish_reason: "stop", - }, - ], - usage: { - prompt_tokens: 5, - completion_tokens: 8, - total_tokens: 13, - }, - }); - - const wrapperFactory = (instrumentation as unknown as { - createCompletionWrapper: (inst: FireworksInstrumentation) => (original: jest.Mock) => typeof patchedFn; - }).createCompletionWrapper(instrumentation); - patchedFn = wrapperFactory(mockOriginal).bind({ baseURL: "https://api.fireworks.ai/inference/v1" }); - }); - - it("should create a span for completions", async () => { - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - prompt: "The quick brown fox", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - expect(spans.length).toBe(1); - expect(spans[0].name).toBe("Fireworks Completions"); - }); - - it("should capture output text", async () => { - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - prompt: "The quick brown fox", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[SemanticConventions.OUTPUT_VALUE]).toBe(" jumped over the lazy dog."); - expect(span.attributes[SemanticConventions.OUTPUT_MIME_TYPE]).toBe(MimeType.TEXT); - }); + it("stops tracing after disable", async () => { + const instrumentation = fireworks(); + instrumentation.disable(); + expect(isPatched()).toBe(false); + await call(FIREWORKS, "chat", "success"); + expect(exporter.getFinishedSpans()).toHaveLength(0); }); - describe("embeddings.create wrapper", () => { - let mockOriginal: jest.Mock; - let patchedFn: (body: Record, options?: Record) => Promise; - - beforeEach(() => { - mockOriginal = jest.fn().mockResolvedValue({ - object: "list", - data: [ - { - object: "embedding", - embedding: [0.1, 0.2, 0.3, 0.4, 0.5], - index: 0, - }, - ], - model: "nomic-ai/nomic-embed-text-v1.5", - usage: { - prompt_tokens: 8, - total_tokens: 8, - }, - }); - - const wrapperFactory = (instrumentation as unknown as { - createEmbeddingWrapper: (inst: FireworksInstrumentation) => (original: jest.Mock) => typeof patchedFn; - }).createEmbeddingWrapper(instrumentation); - patchedFn = wrapperFactory(mockOriginal).bind({ baseURL: "https://api.fireworks.ai/inference/v1" }); - }); - - it("should create a span for embeddings", async () => { - const body = { - model: "nomic-ai/nomic-embed-text-v1.5", - input: "Hello world", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - expect(spans.length).toBe(1); - expect(spans[0].name).toBe("Fireworks Embeddings"); - }); - - it("should set correct attributes for embeddings", async () => { - const body = { - model: "nomic-ai/nomic-embed-text-v1.5", - input: "Hello world", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[SemanticConventions.FI_SPAN_KIND]).toBe(FISpanKind.EMBEDDING); - expect(span.attributes[SemanticConventions.EMBEDDING_MODEL_NAME]).toBe("nomic-ai/nomic-embed-text-v1.5"); - expect(span.attributes[SemanticConventions.LLM_PROVIDER]).toBe(LLMProvider.FIREWORKS); - }); - - it("should capture input text", async () => { - const body = { - model: "nomic-ai/nomic-embed-text-v1.5", - input: "Hello world", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[`${SemanticConventions.EMBEDDING_EMBEDDINGS}.0.${SemanticConventions.EMBEDDING_TEXT}`]).toBe("Hello world"); - }); - - it("should capture embedding vector", async () => { - const body = { - model: "nomic-ai/nomic-embed-text-v1.5", - input: "Hello world", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - const vectorAttr = span.attributes[`${SemanticConventions.EMBEDDING_EMBEDDINGS}.0.${SemanticConventions.EMBEDDING_VECTOR}`]; - expect(vectorAttr).toBeDefined(); - expect(JSON.parse(vectorAttr as string)).toEqual([0.1, 0.2, 0.3, 0.4, 0.5]); - }); - - it("should handle batch embeddings", async () => { - mockOriginal.mockResolvedValueOnce({ - object: "list", - data: [ - { object: "embedding", embedding: [0.1, 0.2], index: 0 }, - { object: "embedding", embedding: [0.3, 0.4], index: 1 }, - ], - model: "nomic-ai/nomic-embed-text-v1.5", - usage: { prompt_tokens: 10, total_tokens: 10 }, - }); - - const body = { - model: "nomic-ai/nomic-embed-text-v1.5", - input: ["Hello", "World"], - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[`${SemanticConventions.EMBEDDING_EMBEDDINGS}.0.${SemanticConventions.EMBEDDING_TEXT}`]).toBe("Hello"); - expect(span.attributes[`${SemanticConventions.EMBEDDING_EMBEDDINGS}.1.${SemanticConventions.EMBEDDING_TEXT}`]).toBe("World"); - }); - - it("should capture token usage", async () => { - const body = { - model: "nomic-ai/nomic-embed-text-v1.5", - input: "Hello world", - }; - - await patchedFn(body); - - const spans = memoryExporter.getFinishedSpans(); - const span = spans[0]; - - expect(span.attributes[SemanticConventions.LLM_TOKEN_COUNT_PROMPT]).toBe(8); - expect(span.attributes[SemanticConventions.LLM_TOKEN_COUNT_TOTAL]).toBe(8); - }); + it("honors privacy options when the provider was registered first", async () => { + fireworks({ traceConfig: { hideInputs: true, hideOutputs: true, hideErrorDetails: true } }); + await call(FIREWORKS, "chat", "success"); + await call(FIREWORKS, "chat", "error"); + const spans = exporter.getFinishedSpans(); + expect(spans).toHaveLength(2); + expect(JSON.stringify(spans.map((span) => [span.attributes, span.events, span.status]))).not.toMatch( + /SYNTHETIC-PRIVATE-CONTENT|synthetic failure|synthetic-unused-key/, + ); }); - describe("streaming response handling", () => { - let mockOriginal: jest.Mock; - let patchedFn: (body: Record, options?: Record) => Promise; - - beforeEach(() => { - const wrapperFactory = (instrumentation as unknown as { - createChatCompletionWrapper: (inst: FireworksInstrumentation) => (original: jest.Mock) => typeof patchedFn; - }).createChatCompletionWrapper(instrumentation); - - mockOriginal = jest.fn(); - patchedFn = wrapperFactory(mockOriginal).bind({ baseURL: "https://api.fireworks.ai/inference/v1" }); - }); - - it("should handle streaming responses", async () => { - const chunks = [ - { - id: "chatcmpl-123", - object: "chat.completion.chunk", - created: 1677652288, - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - choices: [{ index: 0, delta: { content: "Hello" }, finish_reason: null }], - }, - { - id: "chatcmpl-123", - object: "chat.completion.chunk", - created: 1677652288, - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - choices: [{ index: 0, delta: { content: " world" }, finish_reason: null }], - }, - { - id: "chatcmpl-123", - object: "chat.completion.chunk", - created: 1677652288, - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - choices: [{ index: 0, delta: { content: "!" }, finish_reason: "stop" }], - usage: { prompt_tokens: 5, completion_tokens: 3, total_tokens: 8 }, - }, - ]; - - async function* mockStream() { - for (const chunk of chunks) { - yield chunk; - } - } - - mockOriginal.mockResolvedValueOnce(mockStream()); - - const body = { - model: "accounts/fireworks/models/llama-v3p1-8b-instruct", - messages: [{ role: "user", content: "Hello!" }], - stream: true, - }; - - const result = await patchedFn(body); - const collectedChunks: unknown[] = []; - - for await (const chunk of result as AsyncIterable) { - collectedChunks.push(chunk); - } + it("does not export the configured endpoint URL or credentials", async () => { + fireworks(); + await call("https://url-user:url-password@api.fireworks.ai/inference/v1?query-secret=value", "chat", "success"); + const spans = exporter.getFinishedSpans(); + expect(attr(spans[0], "gen_ai.provider.name")).toBe("fireworks"); + expect(JSON.stringify(spans.map((span) => span.attributes))).not.toMatch(/url-user|url-password|query-secret|synthetic-unused-key/); + }); - expect(collectedChunks.length).toBe(3); + it("does not treat look-alike hosts as Fireworks", async () => { + fireworks(); + await call("https://api.fireworks.ai.evil.test/inference/v1", "chat", "success"); + await call("https://fireworks.example/inference/v1", "chat", "success"); + expect(exporter.getFinishedSpans().map((span) => attr(span, "gen_ai.provider.name"))).toEqual(["openai", "openai"]); + }); - const spans = memoryExporter.getFinishedSpans(); - expect(spans.length).toBe(1); - expect(spans[0].attributes[SemanticConventions.OUTPUT_VALUE]).toBe("Hello world!"); + it("emits one deprecation warning per process", () => { + jest.isolateModules(() => { + const { FireworksInstrumentation: Fresh } = require(".."); + instrumentations.push(new Fresh(), new Fresh()); }); + const deprecations = emitWarning.mock.calls.filter(([, options]) => options?.type === "DeprecationWarning"); + expect(deprecations).toHaveLength(1); + expect(String(deprecations[0][0])).toContain("@traceai/openai"); }); }); diff --git a/typescript/packages/traceai_fireworks/src/instrumentation.ts b/typescript/packages/traceai_fireworks/src/instrumentation.ts index 011772c2a..38b4546fe 100644 --- a/typescript/packages/traceai_fireworks/src/instrumentation.ts +++ b/typescript/packages/traceai_fireworks/src/instrumentation.ts @@ -1,756 +1,41 @@ import { - InstrumentationBase, - InstrumentationConfig, - InstrumentationNodeModuleDefinition, - safeExecuteInTheMiddle, -} from "@opentelemetry/instrumentation"; -import { - diag, - context, - trace, - SpanKind, - Attributes, - SpanStatusCode, - Span, -} from "@opentelemetry/api"; -import { VERSION } from "./version"; -import { - SemanticConventions, - FISpanKind, - MimeType, - LLMSystem, - LLMProvider, -} from "@traceai/fi-semantic-conventions"; -import { isTracingSuppressed } from "@opentelemetry/core"; -import { - FITracer, - safelyJSONStringify, - TraceConfigOptions, -} from "@traceai/fi-core"; + OpenAIInstrumentation, + isPatched as isSharedRoutePatched, +} from "@traceai/openai"; -const MODULE_NAME = "openai"; - -/** - * Flag to check if the Fireworks module has been patched - */ -let _isFIPatched = false; +type SharedRouteOptions = ConstructorParameters[0]; +type SharedRouteModule = Parameters[0]; -/** - * Function to check if instrumentation is enabled / disabled - */ -export function isPatched() { - return _isFIPatched; -} +let warned = false; /** - * Resolves the execution context for the current span + * Whether the shared OpenAI-compatible route currently instruments the SDK. */ -function getExecContext(span: Span) { - const activeContext = context.active(); - const suppressTracing = isTracingSuppressed(activeContext); - const execContext = suppressTracing - ? trace.setSpan(context.active(), span) - : activeContext; - if (suppressTracing) { - trace.deleteSpan(activeContext); - } - return execContext; -} - -// Type definitions for OpenAI-compatible API -interface ChatMessage { - role: "system" | "user" | "assistant" | "tool"; - content: string | null; - tool_calls?: ToolCall[]; - tool_call_id?: string; -} - -interface ToolCall { - id: string; - type: "function"; - function: { - name: string; - arguments: string; - }; -} - -interface Tool { - type: "function"; - function: { - name: string; - description?: string; - parameters?: Record; - }; -} - -interface ChatCompletionRequest { - model: string; - messages: ChatMessage[]; - max_tokens?: number; - temperature?: number; - top_p?: number; - top_k?: number; - stop?: string | string[]; - stream?: boolean; - tools?: Tool[]; - tool_choice?: string | { type: string; function: { name: string } }; - [key: string]: unknown; -} - -interface ChatCompletionChoice { - index: number; - message: ChatMessage; - finish_reason: string; - delta?: { - content?: string; - role?: string; - tool_calls?: ToolCall[]; - }; -} - -interface ChatCompletion { - id: string; - object: string; - created: number; - model: string; - choices: ChatCompletionChoice[]; - usage?: { - prompt_tokens: number; - completion_tokens: number; - total_tokens: number; - }; -} - -interface CompletionRequest { - model: string; - prompt: string | string[]; - max_tokens?: number; - temperature?: number; - top_p?: number; - stop?: string | string[]; - stream?: boolean; - [key: string]: unknown; -} - -interface CompletionChoice { - text: string; - index: number; - finish_reason: string; -} - -interface Completion { - id: string; - object: string; - created: number; - model: string; - choices: CompletionChoice[]; - usage?: { - prompt_tokens: number; - completion_tokens: number; - total_tokens: number; - }; -} - -interface EmbeddingRequest { - model: string; - input: string | string[]; -} - -interface EmbeddingData { - object: string; - embedding: number[]; - index: number; -} - -interface EmbeddingResponse { - object: string; - data: EmbeddingData[]; - model: string; - usage?: { - prompt_tokens: number; - total_tokens: number; - }; -} - -interface StreamResponse { - [Symbol.asyncIterator](): AsyncIterator; +export function isPatched(): boolean { + return isSharedRoutePatched(); } /** - * @param instrumentationConfig The config for the instrumentation - * @param traceConfig The FI trace configuration for masking sensitive information + * @deprecated Use `OpenAIInstrumentation` from `@traceai/openai` with a + * Fireworks `baseURL`. This class delegates to that shared route: it traces + * every OpenAI SDK client and sets `gen_ai.provider.name=fireworks` for + * `api.fireworks.ai`. Enabling both produces one span per request. */ -export class FireworksInstrumentation extends InstrumentationBase { - private fiTracer!: FITracer; - private _traceConfig?: TraceConfigOptions; - - constructor({ - instrumentationConfig, - traceConfig, - }: { - instrumentationConfig?: InstrumentationConfig; - traceConfig?: TraceConfigOptions; - } = {}) { - super( - "@traceai/fireworks", - VERSION, - Object.assign({}, instrumentationConfig), - ); - this._traceConfig = traceConfig; - } - - public override enable(): void { - super.enable(); - this.fiTracer = new FITracer({ tracer: this.tracer, traceConfig: this._traceConfig }); - } - - public readonly instrumentationName = "@traceai/fireworks"; - - protected init() { - const module = new InstrumentationNodeModuleDefinition( - "openai", - [">=4.0.0"], - this.patch.bind(this), - this.unpatch.bind(this), - ); - return module; - } - - /** - * Manually instruments the OpenAI module for Fireworks AI - */ - manuallyInstrument(module: Record) { - this.patch(module); - } - - /** - * Checks if a request is targeting Fireworks AI API - */ - private isFireworksRequest(client: unknown): boolean { - const baseURL = (client as { baseURL?: string })?.baseURL; - if (!baseURL) return false; - return baseURL.includes("fireworks") || baseURL.includes("api.fireworks.ai"); - } - - /** - * Patches the OpenAI module for Fireworks AI - */ - private patch( - module: Record & { fiFireworksPatched?: boolean }, - moduleVersion?: string, - ) { - if (module?.fiFireworksPatched || _isFIPatched) { - return module; +export class FireworksInstrumentation extends OpenAIInstrumentation { + constructor(options: SharedRouteOptions = {}) { + super(options); + if (!warned) { + warned = true; + process.emitWarning( + "FireworksInstrumentation is deprecated. Use OpenAIInstrumentation from @traceai/openai " + + "with baseURL https://api.fireworks.ai/inference/v1 instead.", + { type: "DeprecationWarning", code: "TRACEAI_FIREWORKS_DEPRECATED" }, + ); } - - const instrumentation: FireworksInstrumentation = this; - - // Ensure fiTracer uses the most up-to-date tracer - if (!(instrumentation.fiTracer as unknown as Record)?.tracer || - (instrumentation.fiTracer as unknown as Record)?.tracer !== instrumentation.tracer) { - instrumentation.fiTracer = new FITracer({ - tracer: instrumentation.tracer, - traceConfig: instrumentation._traceConfig - }); - } - - // Patch the OpenAI class - const OpenAI = module.OpenAI as { - prototype: { - chat?: { completions?: { create?: unknown } }; - completions?: { create?: unknown }; - embeddings?: { create?: unknown }; - }; - } | undefined; - - if (OpenAI?.prototype) { - // Patch chat.completions.create - if (OpenAI.prototype.chat?.completions && typeof (OpenAI.prototype.chat.completions as Record).create === "function") { - this._wrap( - OpenAI.prototype.chat.completions as Record, - "create", - this.createChatCompletionWrapper(instrumentation), - ); - } - - // Patch completions.create - if (OpenAI.prototype.completions && typeof (OpenAI.prototype.completions as Record).create === "function") { - this._wrap( - OpenAI.prototype.completions as Record, - "create", - this.createCompletionWrapper(instrumentation), - ); - } - - // Patch embeddings.create - if (OpenAI.prototype.embeddings && typeof (OpenAI.prototype.embeddings as Record).create === "function") { - this._wrap( - OpenAI.prototype.embeddings as Record, - "create", - this.createEmbeddingWrapper(instrumentation), - ); - } - } - - _isFIPatched = true; - try { - module.fiFireworksPatched = true; - } catch (e) { - diag.warn(`Failed to set fiFireworksPatched flag on module '${MODULE_NAME}'. Error: ${e}`); - } - - return module; - } - - /** - * Creates a wrapper for chat.completions.create - */ - private createChatCompletionWrapper(instrumentation: FireworksInstrumentation) { - // eslint-disable-next-line @typescript-eslint/no-explicit-any - return (original: any): any => { - return function patchedChatCreate( - this: unknown, - body: ChatCompletionRequest, - options?: Record, - ) { - if (!instrumentation.isFireworksRequest(this)) { - return original.apply(this, [body, options]); - } - - const { messages: _messages, ...invocationParameters } = body; - - const span = instrumentation.fiTracer.startSpan( - `Fireworks Chat Completions`, - { - kind: SpanKind.INTERNAL, - attributes: { - [SemanticConventions.FI_SPAN_KIND]: FISpanKind.LLM, - [SemanticConventions.LLM_MODEL_NAME]: body.model, - [SemanticConventions.INPUT_VALUE]: JSON.stringify(body), - [SemanticConventions.INPUT_MIME_TYPE]: MimeType.JSON, - [SemanticConventions.LLM_INVOCATION_PARAMETERS]: - JSON.stringify(invocationParameters), - [SemanticConventions.LLM_PROVIDER]: LLMProvider.FIREWORKS, - [SemanticConventions.GEN_AI_OPERATION_NAME]: "chat", - ...getChatInputMessagesAttributes(body), - ...getToolsJSONSchema(body), - [SemanticConventions.RAW_INPUT]: safelyJSONStringify(body) ?? "", - }, - }, - ); - - const execContext = getExecContext(span); - const execPromise = safeExecuteInTheMiddle( - () => { - return context.with(trace.setSpan(execContext, span), () => { - return original.apply(this, [body, options]); - }); - }, - (error) => { - if (error) { - span.recordException(error); - span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); - span.end(); - } - }, - ); - - const wrappedPromise = (execPromise as Promise>).then((result) => { - if (isChatCompletionResponse(result)) { - span.setAttributes({ - [SemanticConventions.OUTPUT_VALUE]: JSON.stringify(result), - [SemanticConventions.OUTPUT_MIME_TYPE]: MimeType.JSON, - [SemanticConventions.LLM_MODEL_NAME]: result.model, - [SemanticConventions.GEN_AI_RESPONSE_MODEL]: result.model, - [SemanticConventions.GEN_AI_RESPONSE_ID]: result.id, - [SemanticConventions.GEN_AI_RESPONSE_FINISH_REASONS]: safelyJSONStringify(result.choices.map(c => c.finish_reason)) ?? "[]", - ...getChatOutputMessagesAttributes(result), - ...getUsageAttributes(result), - [SemanticConventions.RAW_OUTPUT]: safelyJSONStringify(result) ?? "", - }); - span.setStatus({ code: SpanStatusCode.OK }); - span.end(); - } else if (isStreamResponse(result)) { - return wrapChatStream(result, span); - } - return result; - }).catch((error: Error) => { - span.recordException(error); - span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); - span.end(); - throw error; - }); - - return context.bind(execContext, wrappedPromise) as Promise>; - }; - }; } - /** - * Creates a wrapper for completions.create - */ - private createCompletionWrapper(instrumentation: FireworksInstrumentation) { - // eslint-disable-next-line @typescript-eslint/no-explicit-any - return (original: any): any => { - return function patchedCompletionCreate( - this: unknown, - body: CompletionRequest, - options?: Record, - ) { - if (!instrumentation.isFireworksRequest(this)) { - return original.apply(this, [body, options]); - } - - const { prompt: _prompt, ...invocationParameters } = body; - const prompts = Array.isArray(body.prompt) ? body.prompt : [body.prompt]; - - const span = instrumentation.fiTracer.startSpan( - `Fireworks Completions`, - { - kind: SpanKind.INTERNAL, - attributes: { - [SemanticConventions.FI_SPAN_KIND]: FISpanKind.LLM, - [SemanticConventions.LLM_MODEL_NAME]: body.model, - [SemanticConventions.INPUT_VALUE]: JSON.stringify(body), - [SemanticConventions.INPUT_MIME_TYPE]: MimeType.JSON, - [SemanticConventions.LLM_INVOCATION_PARAMETERS]: - JSON.stringify(invocationParameters), - [SemanticConventions.LLM_PROVIDER]: LLMProvider.FIREWORKS, - [SemanticConventions.GEN_AI_OPERATION_NAME]: "text_completion", - ...getPromptAttributes(prompts), - [SemanticConventions.RAW_INPUT]: safelyJSONStringify(body) ?? "", - }, - }, - ); - - const execContext = getExecContext(span); - const execPromise = safeExecuteInTheMiddle( - () => { - return context.with(trace.setSpan(execContext, span), () => { - return original.apply(this, [body, options]); - }); - }, - (error) => { - if (error) { - span.recordException(error); - span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); - span.end(); - } - }, - ); - - const wrappedPromise = (execPromise as Promise).then((result) => { - span.setAttributes({ - [SemanticConventions.OUTPUT_VALUE]: result.choices[0]?.text ?? "", - [SemanticConventions.OUTPUT_MIME_TYPE]: MimeType.TEXT, - [SemanticConventions.LLM_MODEL_NAME]: result.model, - ...getCompletionUsageAttributes(result), - [SemanticConventions.RAW_OUTPUT]: safelyJSONStringify(result) ?? "", - }); - span.setStatus({ code: SpanStatusCode.OK }); - span.end(); - return result; - }).catch((error: Error) => { - span.recordException(error); - span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); - span.end(); - throw error; - }); - - return context.bind(execContext, wrappedPromise) as Promise; - }; - }; + /** Instruments an explicitly imported OpenAI SDK module, as ESM applications require. */ + override manuallyInstrument(module: object): void { + super.manuallyInstrument(module as SharedRouteModule); } - - /** - * Creates a wrapper for embeddings.create - */ - private createEmbeddingWrapper(instrumentation: FireworksInstrumentation) { - // eslint-disable-next-line @typescript-eslint/no-explicit-any - return (original: any): any => { - return function patchedEmbeddingCreate( - this: unknown, - body: EmbeddingRequest, - options?: Record, - ) { - if (!instrumentation.isFireworksRequest(this)) { - return original.apply(this, [body, options]); - } - - const inputTexts = Array.isArray(body.input) ? body.input : [body.input]; - - const span = instrumentation.fiTracer.startSpan( - `Fireworks Embeddings`, - { - kind: SpanKind.INTERNAL, - attributes: { - [SemanticConventions.FI_SPAN_KIND]: FISpanKind.EMBEDDING, - [SemanticConventions.EMBEDDING_MODEL_NAME]: body.model, - [SemanticConventions.INPUT_VALUE]: JSON.stringify(body), - [SemanticConventions.INPUT_MIME_TYPE]: MimeType.JSON, - [SemanticConventions.LLM_PROVIDER]: LLMProvider.FIREWORKS, - [SemanticConventions.GEN_AI_OPERATION_NAME]: "embeddings", - ...getEmbeddingInputAttributes(inputTexts), - [SemanticConventions.RAW_INPUT]: safelyJSONStringify(body) ?? "", - }, - }, - ); - - const execContext = getExecContext(span); - const execPromise = safeExecuteInTheMiddle( - () => { - return context.with(trace.setSpan(execContext, span), () => { - return original.apply(this, [body, options]); - }); - }, - (error) => { - if (error) { - span.recordException(error); - span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); - span.end(); - } - }, - ); - - const wrappedPromise = (execPromise as Promise).then((result) => { - span.setAttributes({ - [SemanticConventions.OUTPUT_VALUE]: JSON.stringify(result), - [SemanticConventions.OUTPUT_MIME_TYPE]: MimeType.JSON, - [SemanticConventions.EMBEDDING_MODEL_NAME]: result.model, - ...getEmbeddingOutputAttributes(result), - [SemanticConventions.RAW_OUTPUT]: safelyJSONStringify(result) ?? "", - }); - span.setStatus({ code: SpanStatusCode.OK }); - span.end(); - return result; - }).catch((error: Error) => { - span.recordException(error); - span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); - span.end(); - throw error; - }); - - return context.bind(execContext, wrappedPromise) as Promise; - }; - }; - } - - /** - * Un-patches the OpenAI module - */ - private unpatch( - moduleExports: Record & { fiFireworksPatched?: boolean }, - moduleVersion?: string, - ) { - const OpenAI = moduleExports.OpenAI as { - prototype: { - chat?: { completions?: Record }; - completions?: Record; - embeddings?: Record; - }; - } | undefined; - - if (OpenAI?.prototype) { - if (OpenAI.prototype.chat?.completions) { - this._unwrap(OpenAI.prototype.chat.completions, "create"); - } - if (OpenAI.prototype.completions) { - this._unwrap(OpenAI.prototype.completions, "create"); - } - if (OpenAI.prototype.embeddings) { - this._unwrap(OpenAI.prototype.embeddings, "create"); - } - } - - _isFIPatched = false; - try { - moduleExports.fiFireworksPatched = false; - } catch (e) { - diag.warn(`Failed to unset fiFireworksPatched flag on module '${MODULE_NAME}'. Error: ${e}`); - } - } -} - -/** - * Type guard for chat completion response - */ -function isChatCompletionResponse( - response: ChatCompletion | StreamResponse, -): response is ChatCompletion { - return "choices" in response && Array.isArray((response as ChatCompletion).choices); -} - -/** - * Type guard for stream response - */ -function isStreamResponse( - response: T | StreamResponse, -): response is StreamResponse { - return typeof (response as StreamResponse)[Symbol.asyncIterator] === "function"; -} - -/** - * Wraps a chat stream to capture the full response - */ -async function* wrapChatStream( - stream: StreamResponse, - span: Span, -): AsyncGenerator { - let fullContent = ""; - const allChunks: ChatCompletion[] = []; - let lastChunk: ChatCompletion | null = null; - - try { - for await (const chunk of stream) { - allChunks.push(chunk); - const choice = chunk.choices?.[0]; - if (choice?.delta?.content) { - fullContent += choice.delta.content; - } - lastChunk = chunk; - yield chunk; - } - } catch (error) { - span.recordException(error as Error); - span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message }); - span.end(); - throw error; - } - - const msg: Record = { role: "assistant", content: fullContent }; - const attributes: Attributes = { - [SemanticConventions.OUTPUT_VALUE]: fullContent, - [SemanticConventions.OUTPUT_MIME_TYPE]: MimeType.TEXT, - [SemanticConventions.LLM_OUTPUT_MESSAGES]: safelyJSONStringify([msg]) ?? "[]", - [SemanticConventions.RAW_OUTPUT]: safelyJSONStringify(allChunks) ?? "", - }; - - if (lastChunk) { - attributes[SemanticConventions.LLM_MODEL_NAME] = lastChunk.model; - if (lastChunk.usage) { - attributes[SemanticConventions.LLM_TOKEN_COUNT_PROMPT] = lastChunk.usage.prompt_tokens; - attributes[SemanticConventions.LLM_TOKEN_COUNT_COMPLETION] = lastChunk.usage.completion_tokens; - attributes[SemanticConventions.LLM_TOKEN_COUNT_TOTAL] = lastChunk.usage.total_tokens; - } - } - - span.setAttributes(attributes); - span.setStatus({ code: SpanStatusCode.OK }); - span.end(); -} - -/** - * Gets input message attributes for chat requests - */ -function getChatInputMessagesAttributes(request: ChatCompletionRequest): Attributes { - const serialized = request.messages.map((message) => { - const obj: Record = { role: message.role }; - if (message.content) { - obj.content = message.content; - } - if (message.tool_call_id) { - obj.tool_call_id = message.tool_call_id; - } - return obj; - }); - return { [SemanticConventions.LLM_INPUT_MESSAGES]: safelyJSONStringify(serialized) ?? "[]" }; -} - -/** - * Gets tool schema attributes - */ -function getToolsJSONSchema(request: ChatCompletionRequest): Attributes { - if (!request.tools) { - return {}; - } - return { [SemanticConventions.LLM_TOOLS]: safelyJSONStringify(request.tools) ?? "[]" }; -} - -/** - * Gets output message attributes from chat response - */ -function getChatOutputMessagesAttributes(response: ChatCompletion): Attributes { - const choice = response.choices[0]; - if (!choice) { - return {}; - } - - const msg: Record = { role: choice.message.role }; - if (choice.message.content) { - msg.content = choice.message.content; - } - if (choice.message.tool_calls) { - msg.tool_calls = choice.message.tool_calls.map((tc) => ({ - id: tc.id, - function: { name: tc.function.name, arguments: tc.function.arguments }, - })); - } - return { [SemanticConventions.LLM_OUTPUT_MESSAGES]: safelyJSONStringify([msg]) ?? "[]" }; -} - -/** - * Gets usage attributes from chat response - */ -function getUsageAttributes(response: ChatCompletion): Attributes { - if (response.usage) { - return { - [SemanticConventions.LLM_TOKEN_COUNT_COMPLETION]: response.usage.completion_tokens, - [SemanticConventions.LLM_TOKEN_COUNT_PROMPT]: response.usage.prompt_tokens, - [SemanticConventions.LLM_TOKEN_COUNT_TOTAL]: response.usage.total_tokens, - }; - } - return {}; -} - -/** - * Gets prompt attributes for completion requests - */ -function getPromptAttributes(prompts: string[]): Attributes { - return prompts.reduce((acc: Attributes, prompt, index) => { - acc[`${SemanticConventions.LLM_PROMPTS}.${index}`] = prompt; - return acc; - }, {}); -} - -/** - * Gets usage attributes from completion response - */ -function getCompletionUsageAttributes(response: Completion): Attributes { - if (response.usage) { - return { - [SemanticConventions.LLM_TOKEN_COUNT_COMPLETION]: response.usage.completion_tokens, - [SemanticConventions.LLM_TOKEN_COUNT_PROMPT]: response.usage.prompt_tokens, - [SemanticConventions.LLM_TOKEN_COUNT_TOTAL]: response.usage.total_tokens, - }; - } - return {}; -} - -/** - * Gets embedding input attributes - */ -function getEmbeddingInputAttributes(texts: string[]): Attributes { - return texts.reduce((acc: Attributes, text, index) => { - acc[`${SemanticConventions.EMBEDDING_EMBEDDINGS}.${index}.${SemanticConventions.EMBEDDING_TEXT}`] = text; - return acc; - }, {}); -} - -/** - * Gets embedding output attributes - */ -function getEmbeddingOutputAttributes(response: EmbeddingResponse): Attributes { - const attributes: Attributes = {}; - - response.data.forEach((item, index) => { - attributes[`${SemanticConventions.EMBEDDING_EMBEDDINGS}.${index}.${SemanticConventions.EMBEDDING_VECTOR}`] = - JSON.stringify(item.embedding); - }); - - if (response.usage) { - attributes[SemanticConventions.LLM_TOKEN_COUNT_PROMPT] = response.usage.prompt_tokens; - attributes[SemanticConventions.LLM_TOKEN_COUNT_TOTAL] = response.usage.total_tokens; - } - - return attributes; } diff --git a/typescript/packages/traceai_fireworks/src/typeUtils.ts b/typescript/packages/traceai_fireworks/src/typeUtils.ts deleted file mode 100644 index f9c0e8b7d..000000000 --- a/typescript/packages/traceai_fireworks/src/typeUtils.ts +++ /dev/null @@ -1,5 +0,0 @@ -export type SafeFunction = (...args: unknown[]) => unknown; - -export function isFunction(value: unknown): value is SafeFunction { - return typeof value === "function"; -} diff --git a/typescript/packages/traceai_fireworks/test/readme.cjs b/typescript/packages/traceai_fireworks/test/readme.cjs new file mode 100644 index 000000000..9f7b5b9af --- /dev/null +++ b/typescript/packages/traceai_fireworks/test/readme.cjs @@ -0,0 +1,64 @@ +// Runs the README recipe unchanged against installed tarballs: +// FIREWORKS_CONSUMER_DIR=/path/to/consumer node --test test/readme.cjs +const assert = require('node:assert/strict'); +const { readFileSync, writeFileSync } = require('node:fs'); +const { resolve } = require('node:path'); +const { createServer } = require('node:http'); +const { spawn } = require('node:child_process'); +const { once } = require('node:events'); +const { test } = require('node:test'); + +test('Fireworks README recipe runs with the packed packages', async () => { + const consumer = process.env.FIREWORKS_CONSUMER_DIR; + const readme = readFileSync(resolve(__dirname, '../README.md'), 'utf8'); + const snippet = readme.split('## Set up Fireworks tracing\n')[1].split('```typescript\n')[1].split('```')[0]; + const script = resolve(consumer, 'fireworks.mts'); + const preload = resolve(consumer, 'synthetic-transport.mjs'); + writeFileSync(script, snippet); + // Only the model transport is replaced; register() exports real OTLP to loopback. + writeFileSync(preload, `globalThis.fetch = async (url, options) => { + if (String(url) !== 'https://api.fireworks.ai/inference/v1/chat/completions') throw new Error('Unexpected network request'); + if (JSON.parse(options.body).model !== 'accounts/fireworks/models/synthetic') throw new Error('Missing requested model'); + return new Response(JSON.stringify({ id: 'chat-recipe', object: 'chat.completion', created: 1, model: 'accounts/fireworks/models/synthetic', choices: [{ index: 0, message: { role: 'assistant', content: 'Synthetic answer' }, finish_reason: 'stop' }], usage: { prompt_tokens: 3, completion_tokens: 2, total_tokens: 5 } }), { headers: { 'content-type': 'application/json' } }); + };`); + const batches = []; + const server = createServer(async (request, response) => { + assert.equal(request.url, '/tracer/v1/traces'); + const chunks = []; + for await (const chunk of request) chunks.push(chunk); + batches.push(JSON.parse(Buffer.concat(chunks))); + response.writeHead(200, { 'content-type': 'application/json' }).end('{}'); + }); + await new Promise((done) => server.listen(0, '127.0.0.1', done)); + try { + const child = spawn(process.execPath, ['--import', preload, script], { + cwd: consumer, + env: { + PATH: process.env.PATH, + FI_BASE_URL: `http://127.0.0.1:${server.address().port}`, + FI_API_KEY: 'synthetic-fi-key', + FI_SECRET_KEY: 'synthetic-fi-secret', + FIREWORKS_API_KEY: 'synthetic-fireworks-key', + FIREWORKS_MODEL: 'accounts/fireworks/models/synthetic', + }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + let output = ''; + let errors = ''; + child.stdout.on('data', (chunk) => { output += chunk; }); + child.stderr.on('data', (chunk) => { errors += chunk; }); + const [code] = await once(child, 'close'); + assert.equal(code, 0, errors); + assert.match(output, /Synthetic answer/); + const spans = batches.flatMap((b) => b.resourceSpans.flatMap((r) => r.scopeSpans.flatMap((s) => s.spans))); + assert.equal(spans.length, 1); + assert.equal(spans[0].name, 'OpenAI Chat Completions'); + const attrs = Object.fromEntries(spans[0].attributes.map((a) => [a.key, Object.values(a.value)[0]])); + assert.equal(attrs['gen_ai.provider.name'], 'fireworks'); + assert.equal(String(attrs['gen_ai.usage.input_tokens']), '3'); + assert.equal(String(attrs['gen_ai.usage.output_tokens']), '2'); + assert.doesNotMatch(JSON.stringify(batches), /synthetic-fi-key|synthetic-fi-secret|synthetic-fireworks-key/); + } finally { + await new Promise((done) => server.close(done)); + } +}); diff --git a/typescript/packages/traceai_fireworks/test/sharedRoute.cjs b/typescript/packages/traceai_fireworks/test/sharedRoute.cjs new file mode 100644 index 000000000..ecf777aec --- /dev/null +++ b/typescript/packages/traceai_fireworks/test/sharedRoute.cjs @@ -0,0 +1,155 @@ +// Run against installed tarballs in a clean consumer, never workspace links: +// FIREWORKS_CONSUMER_DIR=/path/to/consumer node --test test/sharedRoute.cjs +// FIREWORKS_TEST_MANUAL=true instruments an explicitly loaded SDK module (as ESM +// applications do); otherwise CommonJS require hooks patch it automatically. +// FIREWORKS_TEST_BOTH=true also enables the shared OpenAIInstrumentation. +const { test, after, beforeEach } = require('node:test'); +const assert = require('node:assert/strict'); +const { createRequire } = require('node:module'); +const { resolve } = require('node:path'); +const { createServer } = require('node:http'); + +const req = createRequire(resolve(process.env.FIREWORKS_CONSUMER_DIR, 'package.json')); +const { BasicTracerProvider, SimpleSpanProcessor } = req('@opentelemetry/sdk-trace-base'); +const { OTLPTraceExporter } = req('@opentelemetry/exporter-trace-otlp-http'); +const { trace } = req('@opentelemetry/api'); +const { FireworksInstrumentation, isPatched } = req('@traceai/fireworks'); +const { OpenAIInstrumentation } = req('@traceai/openai'); + +const manual = process.env.FIREWORKS_TEST_MANUAL === 'true'; +const both = process.env.FIREWORKS_TEST_BOTH === 'true'; +const SECRET = 'SYNTHETIC-PRIVATE-CONTENT'; +const FIREWORKS = 'https://api.fireworks.ai/inference/v1'; + +const wire = []; +const server = createServer(async (request, response) => { + const chunks = []; + for await (const chunk of request) chunks.push(chunk); + const decoded = JSON.parse(Buffer.concat(chunks)); + wire.push(...decoded.resourceSpans.flatMap((r) => r.scopeSpans.flatMap((s) => s.spans))); + response.writeHead(200, { 'content-type': 'application/json' }); + response.end('{}'); +}); +const ready = new Promise((done) => server.listen(0, '127.0.0.1', done)); + +let provider; +let OpenAI; +const instrumentations = []; +const warnings = []; +process.on('warning', (warning) => warnings.push(warning)); + +function body(operation) { + if (operation === 'embeddings') { + return { object: 'list', model: 'returned-model', data: [{ index: 0, object: 'embedding', embedding: [0.1] }], usage: { prompt_tokens: 2, total_tokens: 2 } }; + } + return { + id: 'synthetic-id', created: 1, model: 'returned-model', + object: operation === 'chat' ? 'chat.completion' : 'text_completion', + choices: [{ index: 0, message: { role: 'assistant', content: SECRET }, text: SECRET, finish_reason: 'stop' }], + usage: { prompt_tokens: 2, completion_tokens: 3, total_tokens: 5 }, + }; +} + +function chunk(operation) { + return { + id: 'synthetic-id', created: 1, model: 'returned-model', + object: operation === 'chat' ? 'chat.completion.chunk' : 'text_completion', + choices: [{ index: 0, delta: { role: 'assistant', content: SECRET }, text: SECRET, finish_reason: 'stop' }], + }; +} + +// The configured host stays real so attribution is exercised; the transport is in-process. +function client(baseURL, outcome, operation) { + return new OpenAI({ + apiKey: 'synthetic-credential', + baseURL, + maxRetries: 0, + fetch: async () => { + if (outcome === 'error') { + return new Response(JSON.stringify({ error: { message: 'SYNTHETIC-PRIVATE-ERROR', type: 'invalid_request_error' } }), { status: 400, headers: { 'content-type': 'application/json' } }); + } + if (outcome === 'stream') { + return new Response(`data: ${JSON.stringify(chunk(operation))}\n\ndata: [DONE]\n\n`, { headers: { 'content-type': 'text/event-stream' } }); + } + return new Response(JSON.stringify(body(operation)), { headers: { 'content-type': 'application/json' } }); + }, + }); +} + +async function call(operation, outcome = 'success', baseURL = FIREWORKS) { + const c = client(baseURL, outcome, operation); + const stream = outcome === 'stream' ? { stream: true } : {}; + const request = operation === 'chat' + ? c.chat.completions.create({ model: 'accounts/fireworks/models/synthetic', messages: [{ role: 'user', content: SECRET }], ...stream }) + : operation === 'completions' + ? c.completions.create({ model: 'accounts/fireworks/models/synthetic', prompt: SECRET, ...stream }) + : c.embeddings.create({ model: 'nomic-ai/synthetic', input: 'synthetic embedding', encoding_format: 'float' }); + if (outcome === 'error') return assert.rejects(request); + const result = await request; + if (outcome === 'stream') for await (const _ of result) { /* consume */ } +} + +async function exported() { + await provider.forceFlush(); + const spans = wire.splice(0); + const serialized = JSON.stringify(spans); + assert.doesNotMatch(serialized, /SYNTHETIC-PRIVATE-CONTENT|SYNTHETIC-PRIVATE-ERROR|synthetic-credential/); + return spans.map((span) => span.attributes.find((a) => a.key === 'gen_ai.provider.name')?.value.stringValue); +} + +test('set up instrumentation before the real SDK is used', async () => { + await ready; + provider = new BasicTracerProvider({ + spanProcessors: [new SimpleSpanProcessor(new OTLPTraceExporter({ url: `http://127.0.0.1:${server.address().port}/v1/traces` }))], + }); + // The documented setup registers the provider before constructing instrumentation. + trace.setGlobalTracerProvider(provider); + // Manual mode loads the SDK first, so no require hook can patch it. + const preloaded = manual ? req('openai') : undefined; + const options = { traceConfig: { hideInputs: true, hideOutputs: true, hideErrorDetails: true } }; + instrumentations.push(new FireworksInstrumentation(options)); + if (both) instrumentations.push(new OpenAIInstrumentation(options)); + for (const instrumentation of instrumentations) instrumentation.setTracerProvider(provider); + const sdk = preloaded ?? req('openai'); + if (manual) for (const instrumentation of instrumentations) instrumentation.manuallyInstrument(sdk); + OpenAI = sdk.OpenAI; + assert.equal(isPatched(), true); + await new Promise(setImmediate); + assert.equal(warnings.filter((w) => w.name === 'DeprecationWarning' && w.code === 'TRACEAI_FIREWORKS_DEPRECATED').length, 1); +}); + +beforeEach(() => { wire.length = 0; }); + +for (const [operation, outcome] of [ + ['chat', 'success'], ['chat', 'stream'], ['chat', 'error'], + ['completions', 'success'], ['completions', 'stream'], ['completions', 'error'], + ['embeddings', 'success'], ['embeddings', 'error'], +]) { + test(`${operation} ${outcome} exports one Fireworks span`, async () => { + await call(operation, outcome); + assert.deepEqual(await exported(), ['fireworks']); + }); +} + +test('a direct OpenAI client in the same process keeps its own provider', async () => { + await call('chat', 'success', 'https://api.openai.com/v1'); + assert.deepEqual(await exported(), ['openai']); +}); + +test('disabling the instrumentor that did not patch keeps tracing', { skip: !both }, async () => { + instrumentations[1].disable(); + await call('chat', 'stream'); + assert.deepEqual(await exported(), ['fireworks']); +}); + +test('disabling every instrumentor stops tracing', async () => { + for (const instrumentation of instrumentations) instrumentation.disable(); + assert.equal(isPatched(), false); + await call('chat'); + assert.deepEqual(await exported(), []); +}); + +after(async () => { + await provider?.shutdown(); + await new Promise((done) => server.close(done)); +}); diff --git a/typescript/packages/traceai_openai/README.md b/typescript/packages/traceai_openai/README.md index b0c0ece66..cf35b28bc 100644 --- a/typescript/packages/traceai_openai/README.md +++ b/typescript/packages/traceai_openai/README.md @@ -222,6 +222,20 @@ const response = await client.chat.completions.create({ Choose a model available to your gateway account. `gen_ai.provider.name` comes from the configured API hostname, not the model name: `api.anannas.ai` and `anannas.ai` produce `anannas`, including failed and streamed requests. The gateway's downstream routing is not inferred. Unknown proxies and local servers retain the historical `openai` fallback; this does not establish which provider they route to. URL credentials, paths and query strings are not added as provider attributes. Streaming spans finish when you consume the stream, encounter an iteration error or leave the loop early. Consume or close streams before shutting down the tracer provider. Request and response content is captured by default; use the instrumentation's `traceConfig` input/output and error-detail hiding options for sensitive data. + +## Fireworks AI + +Point the client at Fireworks' [OpenAI-compatible endpoint](https://docs.fireworks.ai/tools-sdks/openai-compatibility). Requests to `api.fireworks.ai` produce `gen_ai.provider.name=fireworks` for chat completions, completions and embeddings, including streamed and failed requests: + +```typescript +const client = new OpenAI({ + baseURL: "https://api.fireworks.ai/inference/v1", + apiKey: process.env.FIREWORKS_API_KEY, +}); +``` + +`@traceai/fireworks` is deprecated and delegates to this instrumentor. Enabling both still produces one span per request. + ## Response helpers Instrumentation preserves the OpenAI SDK's `APIPromise` helpers. Use diff --git a/typescript/packages/traceai_openai/src/__tests__/patchOwnership.test.ts b/typescript/packages/traceai_openai/src/__tests__/patchOwnership.test.ts new file mode 100644 index 000000000..f1f504349 --- /dev/null +++ b/typescript/packages/traceai_openai/src/__tests__/patchOwnership.test.ts @@ -0,0 +1,51 @@ +import type { InstrumentationModuleDefinition } from "@opentelemetry/instrumentation"; +import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"; +import { OpenAIInstrumentation, isPatched } from "../instrumentation"; + +// Use the real SDK; matrix jobs may provide a separately installed version. +const sdk = require(process.env.OPENAI_TEST_MODULE || "openai"); + +// Jest's module registry bypasses require-in-the-middle, so record and patch the +// exports exactly as the CommonJS hook does; disable() later unpatches them. +function loadThroughRequireHook(instrumentation: OpenAIInstrumentation) { + const [definition] = (instrumentation as unknown as { _modules: InstrumentationModuleDefinition[] })._modules; + definition.moduleExports = sdk; + definition.patch!(sdk, sdk.VERSION); +} + +describe("instrumentors sharing one SDK module", () => { + const exporter = new InMemorySpanExporter(); + const provider = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] }); + const client = new sdk.OpenAI({ + apiKey: "synthetic-unused-key", + baseURL: "https://api.fireworks.ai/inference/v1", + maxRetries: 0, + fetch: async () => new Response( + JSON.stringify({ id: "synthetic-id", object: "chat.completion", created: 1, model: "m", choices: [] }), + { headers: { "content-type": "application/json" } }, + ), + }); + const chat = () => client.chat.completions.create({ model: "m", messages: [{ role: "user", content: "Hello" }] }); + + afterAll(() => provider.shutdown()); + beforeEach(() => exporter.reset()); + + it("keeps the owner's patch when an instrumentor that did not patch is disabled", async () => { + const owner = new OpenAIInstrumentation(); + const other = new OpenAIInstrumentation(); + owner.setTracerProvider(provider); + other.setTracerProvider(provider); + loadThroughRequireHook(owner); + loadThroughRequireHook(other); + + other.disable(); + expect(isPatched()).toBe(true); + await chat(); + expect(exporter.getFinishedSpans()).toHaveLength(1); + + owner.disable(); + expect(isPatched()).toBe(false); + await chat(); + expect(exporter.getFinishedSpans()).toHaveLength(1); + }); +}); diff --git a/typescript/packages/traceai_openai/src/__tests__/provider.test.ts b/typescript/packages/traceai_openai/src/__tests__/provider.test.ts index 4169594a9..217cfcede 100644 --- a/typescript/packages/traceai_openai/src/__tests__/provider.test.ts +++ b/typescript/packages/traceai_openai/src/__tests__/provider.test.ts @@ -18,6 +18,7 @@ describe("providerForResource", () => { ["api.anannas.ai", "anannas"], ["anannas.ai", "anannas"], ["api.doubleword.ai", "doubleword"], + ["api.fireworks.ai", "fireworks"], ["resource.openai.azure.com", "azure"], ["resource.services.ai.azure.com", "azure"], ["resource.cognitiveservices.azure.com", "azure"], @@ -38,6 +39,8 @@ describe("providerForResource", () => { { _client: { baseURL: "not a url" } }, { _client: { baseURL: "ftp://api.anannas.ai" } }, { _client: { baseURL: "https://constructor" } }, { _client: { baseURL: "http://127.0.0.1/v1" } }, { _client: { baseURL: "https://notopenai.azure.com" } }, + { _client: { baseURL: "https://fireworks.ai/inference/v1" } }, + { _client: { baseURL: "https://my-fireworks-proxy.example/inference/v1" } }, ])("falls back safely for %p", (resource) => { expect(providerForResource(resource)).toBe("openai"); }); diff --git a/typescript/packages/traceai_openai/src/instrumentation.ts b/typescript/packages/traceai_openai/src/instrumentation.ts index c7cbd4715..d2ccb8d71 100644 --- a/typescript/packages/traceai_openai/src/instrumentation.ts +++ b/typescript/packages/traceai_openai/src/instrumentation.ts @@ -99,6 +99,9 @@ export class OpenAIInstrumentation extends InstrumentationBase{ private fiTracer!: FITracer; private _traceConfig?: TraceConfigOptions; private manuallyPatchedModule?: typeof openai; + // Only the instance that applied a patch may remove it. Another instrumentor + // sharing the module returns early from patch() but is still asked to unpatch. + private readonly patchedModules = new WeakSet(); constructor({ instrumentationConfig, @@ -567,6 +570,7 @@ export class OpenAIInstrumentation extends InstrumentationBase{ } _isFIPatched = true; + this.patchedModules.add(module); try { // This can fail if the module is made immutable via the runtime or bundler module.fiPatched = true; @@ -585,6 +589,7 @@ export class OpenAIInstrumentation extends InstrumentationBase{ moduleVersion?: string, ) { // diag.debug(`Removing patch for ${MODULE_NAME}@${moduleVersion}`); + if (!moduleExports || !this.patchedModules.delete(moduleExports)) return; this._unwrap(moduleExports.OpenAI.Chat.Completions.prototype, "create"); this._unwrap(moduleExports.OpenAI.Completions.prototype, "create"); this._unwrap(moduleExports.OpenAI.Embeddings.prototype, "create"); diff --git a/typescript/packages/traceai_openai/src/provider.ts b/typescript/packages/traceai_openai/src/provider.ts index e5216d561..61ec1a6fe 100644 --- a/typescript/packages/traceai_openai/src/provider.ts +++ b/typescript/packages/traceai_openai/src/provider.ts @@ -21,6 +21,7 @@ const HOSTS: Readonly> = { "api.anannas.ai": "anannas", "anannas.ai": "anannas", "api.doubleword.ai": "doubleword", + "api.fireworks.ai": "fireworks", }; const SUFFIXES: ReadonlyArray = [ diff --git a/typescript/pnpm-lock.yaml b/typescript/pnpm-lock.yaml index 3eae5818d..7ba073114 100644 --- a/typescript/pnpm-lock.yaml +++ b/typescript/pnpm-lock.yaml @@ -773,28 +773,19 @@ importers: packages/traceai_fireworks: dependencies: + '@traceai/openai': + specifier: workspace:^ + version: link:../traceai_openai + devDependencies: '@opentelemetry/api': specifier: ^1.9.0 version: 1.9.0 - '@opentelemetry/core': - specifier: ^1.29.0 - version: 1.30.1(@opentelemetry/api@1.9.0) - '@opentelemetry/instrumentation': - specifier: ^0.56.0 - version: 0.56.0(@opentelemetry/api@1.9.0) + '@opentelemetry/sdk-trace-base': + specifier: ^2.0.1 + version: 2.0.1(@opentelemetry/api@1.9.0) '@traceai/fi-core': specifier: workspace:^ version: link:../fi-core - '@traceai/fi-semantic-conventions': - specifier: workspace:^ - version: link:../fi-semantic-conventions - devDependencies: - '@opentelemetry/sdk-trace-base': - specifier: ^1.29.0 - version: 1.30.1(@opentelemetry/api@1.9.0) - '@opentelemetry/sdk-trace-node': - specifier: ^1.29.0 - version: 1.30.1(@opentelemetry/api@1.9.0) '@types/jest': specifier: ^29.5.14 version: 29.5.14