Groq

Tracing

To trace Groq with Braintrust’s TypeScript SDK, use auto-instrumentation, manual instrumentation, or the Braintrust gateway. Auto-instrumentation is the recommended path for most users.

Auto-instrumentation
Manual instrumentation
Gateway

Auto-instrumentation patches the groq-sdk client at runtime when you run your app with Braintrust’s import hook, so you don’t modify your application code.

Setup

Install the Braintrust and Groq SDKs, then set your API keys. Requires groq-sdk v1.0.0 or later.

pnpm add braintrust groq-sdk

npm install braintrust groq-sdk

.env

GROQ_API_KEY=<your-groq-api-key>
BRAINTRUST_API_KEY=<your-braintrust-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url-here>

Trace your application

Initialize Braintrust and call Groq normally, then run your app with the import hook to patch the client at runtime.

Initialize Braintrust and call Groq

import { initLogger } from "braintrust";
import Groq from "groq-sdk";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = new Groq({ apiKey: process.env.GROQ_API_KEY });

const response = await client.chat.completions.create({
  model: "openai/gpt-oss-120b",
  messages: [{ role: "user", content: "What is machine learning?" }],
});

console.log(response.choices[0].message.content);

Run with the import hook

node --import braintrust/hook.mjs trace-groq-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

What Braintrust traces

Braintrust patches the groq-sdk client and captures:

Chat completion spans (groq.chat.completions.create), with messages and request parameters as input, and response choices and token usage as output.
Reasoning content for Groq reasoning models, aggregated from streaming responses.
Embedding spans (groq.embeddings.create), with input and request parameters as input, and the first embedding’s vector length as output.
Token usage metrics (prompt, completion, total), including Groq cache metrics (dram_cached_tokens and sram_cached_tokens) when reported.
time_to_first_token for chat completions.
Errors captured on every call.

Tracing resources

To trace Groq manually, wrap the groq-sdk client yourself with wrapGroq().

Setup

Install the Braintrust and Groq SDKs, then set your API keys. Requires groq-sdk v1.0.0 or later.

pnpm add braintrust groq-sdk

npm install braintrust groq-sdk

.env

GROQ_API_KEY=<your-groq-api-key>
BRAINTRUST_API_KEY=<your-braintrust-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url-here>

Trace your application

Wrap the Groq client with wrapGroq() so every call is traced.

import { initLogger, wrapGroq } from "braintrust";
import Groq from "groq-sdk";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = wrapGroq(new Groq({ apiKey: process.env.GROQ_API_KEY }));

const response = await client.chat.completions.create({
  model: "openai/gpt-oss-120b",
  messages: [{ role: "user", content: "What is machine learning?" }],
});

console.log(response.choices[0].message.content);

What Braintrust traces

Braintrust patches the groq-sdk client and captures:

Chat completion spans (groq.chat.completions.create), with messages and request parameters as input, and response choices and token usage as output.
Reasoning content for Groq reasoning models, aggregated from streaming responses.
Embedding spans (groq.embeddings.create), with input and request parameters as input, and the first embedding’s vector length as output.
Token usage metrics (prompt, completion, total), including Groq cache metrics (dram_cached_tokens and sram_cached_tokens) when reported.
time_to_first_token for chat completions.
Errors captured on every call.

Tracing resources

The Braintrust gateway routes your Groq requests server-side. Point an OpenAI-compatible client at the gateway base URL, then set the x-bt-parent header to log each request to your project.

Setup

Install the Braintrust and OpenAI SDKs, then set your Braintrust API key. The gateway reads your Groq key from the provider you configure in Add Groq as an AI provider.

pnpm add braintrust openai

npm install braintrust openai

.env

BRAINTRUST_API_KEY=<your-braintrust-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url-here>

Trace your application

Point an OpenAI client at the gateway, then set the x-bt-parent header on the request so the gateway logs it to your project. Use a project_name: prefix to target a project directly, or pass span.export() to nest the call in a distributed trace.

import { OpenAI } from "openai";
import { initLogger } from "braintrust";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

// Gateway logging is opt-in: set x-bt-parent so the gateway logs to the project.
const result = await client.chat.completions.create(
  {
    model: "openai/gpt-oss-120b",
    messages: [{ role: "user", content: "What is machine learning?" }],
  },
  {
    headers: { "x-bt-parent": "project_name:My Project" },
  },
);

Tracing resources

Evals

Run experiments against Groq models to measure quality and catch regressions. An Eval is composed of a dataset of inputs, a task, and a set of scorers. To learn more, see the Experiments guide.

import { Eval } from "braintrust";
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

Eval("Groq Evaluation", {
  data: () => [
    { input: "What is 2+2?", expected: "4" },
    { input: "What is the capital of France?", expected: "Paris" },
  ],
  task: async (input) => {
    const response = await client.chat.completions.create({
      model: "openai/gpt-oss-120b",
      messages: [{ role: "user", content: input }],
    });
    return response.choices[0].message.content;
  },
  scores: [
    {
      name: "accuracy",
      scorer: (args) => (args.output === args.expected ? 1 : 0),
    },
  ],
});

AI providers

SDKs

Developer tools

Tracing

Setup

Trace your application

What Braintrust traces

Tracing resources

Setup

Trace your application

What Braintrust traces

Tracing resources

Setup

Trace your application

Tracing resources

Evals

Add Groq as an AI provider

Groq provider resources

​Tracing

​Setup

​Trace your application

​What Braintrust traces

​Tracing resources

​Setup

​Trace your application

​What Braintrust traces

​Tracing resources

​Setup

​Trace your application

​Tracing resources

​Evals

​Add Groq as an AI provider

​Groq provider resources

Tracing

Setup

Trace your application

What Braintrust traces

Tracing resources

Setup

Trace your application

What Braintrust traces

Tracing resources

Setup

Trace your application

Tracing resources

Evals

Add Groq as an AI provider

Groq provider resources