Setup Install the Braintrust and `@huggingface/inference` packages, then set your API keys. Requires `@huggingface/inference` v2.0.0 or later (any 2.x, 3.x, or 4.x release). ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust @huggingface/inference ``` ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} npm install braintrust @huggingface/inference ``` ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} BRAINTRUST_API_KEY= HUGGINGFACE_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= ``` Auto-instrumentation To trace Hugging Face Inference SDK calls without modifying your application code, initialize Braintrust normally, then run your app with Braintrust’s import hook to patch the SDK at runtime. ```javascript title="trace-huggingface-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { initLogger } from "braintrust"; import * as huggingFace from "@huggingface/inference"; initLogger({ projectName: "huggingface-example", apiKey: process.env.BRAINTRUST_API_KEY, }); const client = new huggingFace.InferenceClient( process.env.HUGGINGFACE_API_KEY, ); const response = await client.chatCompletion({ model: "meta-llama/Llama-3.1-8B-Instruct", provider: "featherless-ai", messages: [ { role: "user", content: "Reply with exactly OK.", }, ], max_tokens: 16, temperature: 0, }); console.log(response.choices?.[0]?.message?.content); ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} node --import braintrust/hook.mjs trace-huggingface-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](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup. Manual instrumentation To trace Hugging Face clients manually, wrap them yourself with `wrapHuggingFace()`. Use this when you want to trace selected clients, or wrap the module directly before constructing clients. ```javascript title="trace-huggingface-wrap.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { initLogger, wrapHuggingFace } from "braintrust"; import * as huggingFace from "@huggingface/inference"; initLogger({ projectName: "huggingface-example", apiKey: process.env.BRAINTRUST_API_KEY, }); const hf = wrapHuggingFace(huggingFace); const client = new hf.InferenceClient(process.env.HUGGINGFACE_API_KEY); const embedding = await client.featureExtraction({ inputs: "Paris France", model: "thenlper/gte-large", provider: "hf-inference", }); console.log(embedding); ``` `wrapHuggingFace()` can wrap either: * The module import itself, including `InferenceClient`, `InferenceClientEndpoint`, `HfInference`, and `HfInferenceEndpoint`. * An already-constructed client instance. If you use routed or custom endpoints via `client.endpoint(...)`, Braintrust records the endpoint URL in span metadata. What Braintrust traces Braintrust traces these `@huggingface/inference` SDK calls, capturing: * Chat completions, including streaming chat with first-token timing. * Text generation, including streaming text generation with first-token timing. * Feature extraction, summarized as embedding count, length, and batch count. * Token usage, including prompt, completion, and total tokens. * Request metadata, including model, provider, and selected request parameters. * Response identifiers, including ID, model, object, created, and finish reason. * Routed endpoint URL when calling `client.endpoint(...)`. Resources * [Hugging Face Inference SDK](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) * [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/) * [Trace LLM calls](/instrument/trace-llm-calls)