Boson logoBoson
Documentation/SDK (JS/TS)/Tracing API
1 min read

Tracing API

This page mirrors the real SDK surface in sdk/boson-js (Boson-branded wrappers around upstream Langfuse packages). The SDK always talks to Boson’s official backend (Boson Cloud or customer-deployed Boson).

The fastest production-grade setup is to use OpenTelemetry’s Node SDK plus the Boson span processor.

1) Install

pnpm add @getboson/sdk @opentelemetry/sdk-node

2) Configure env vars

LANGFUSE_BASE_URL=https://app.getboson.com
LANGFUSE_PUBLIC_KEY=...
LANGFUSE_SECRET_KEY=...

3) Initialize tracing and instrument work

import { NodeSDK } from "@opentelemetry/sdk-node"
import { LangfuseSpanProcessor, observe, propagateAttributes } from "@getboson/sdk"

const spanProcessor = new LangfuseSpanProcessor()
const sdk = new NodeSDK({ spanProcessor, instrumentations: [] })
await sdk.start()

const run = observe(
  async () => {
    // Your actual work here (LLM calls, retrieval, tools…)
    return { ok: true, at: new Date().toISOString() }
  },
  {
    name: "trace-smoke-handshake",
    asType: "span",
    captureInput: true,
    captureOutput: true,
  },
)

await propagateAttributes(
  {
    traceName: "trace-smoke",
    metadata: { env: process.env.NODE_ENV ?? "development" },
  },
  () => run(),
)

await spanProcessor.forceFlush()
await spanProcessor.shutdown()
await sdk.shutdown()

This is the same pattern used in sdk/boson-js/examples/trace-smoke.

Common instrumentation helpers

Depending on your app you may also use:

  • startActiveSpan, startActiveGeneration (span/generation helpers)
  • startActiveObservation (more direct control over observation lifecycle)

Keep span naming stable (llm.completion, tool.execute, retrieval.query) and put variability in metadata.

When streaming a model response, avoid emitting an event per token. Instead:

  • emit an output.delta event occasionally (every N chars or on sentence boundaries), or
  • emit a final output event with the complete text at the end

Next steps