Skip to content
Merged
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
102 changes: 102 additions & 0 deletions .github/workflows/fireworks-typescript-tests.yml
Original file line number Diff line number Diff line change
@@ -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
3 changes: 2 additions & 1 deletion .github/workflows/openai-sdk-contracts.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
152 changes: 41 additions & 111 deletions typescript/packages/traceai_fireworks/README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
32 changes: 14 additions & 18 deletions typescript/packages/traceai_fireworks/examples/example.ts
Original file line number Diff line number Diff line change
@@ -1,36 +1,32 @@
/**
* 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
// hideOutputs: true, // Hide output content in traces
},
});
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({
Expand Down Expand Up @@ -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.");
}
Expand Down
9 changes: 4 additions & 5 deletions typescript/packages/traceai_fireworks/examples/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
6 changes: 6 additions & 0 deletions typescript/packages/traceai_fireworks/jest.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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$": "<rootDir>/../traceai_openai/src",
"^@traceai/fi-core$": "<rootDir>/../fi-core/src",
"^@traceai/fi-semantic-conventions$": "<rootDir>/../fi-semantic-conventions/src",
},
collectCoverageFrom: ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/__tests__/**"],
coverageDirectory: "coverage",
verbose: true,
Expand Down
Loading
Loading