Boson logoBoson
Documentation/Getting started/Installation
1 min read

Installation

This guide gets you from zero to a visible trace in the Boson web app. Instrumentation uses Boson’s open-source SDK against Boson’s official backend (see Introduction for how Cloud, SDKs, and licensing relate).

Prerequisites

  • Node.js 18+
  • A Boson API key
  • A running app or a small script where you can make one model call

Install the SDK (JavaScript/TypeScript)

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

Configure environment

The Boson SDKs are Langfuse-compatible and use Langfuse-style environment variables (Boson Cloud accepts them).

  • LANGFUSE_BASE_URL: base URL of your Boson backend (Boson Cloud or customer-deployed Boson)
  • LANGFUSE_PUBLIC_KEY: project public key
  • LANGFUSE_SECRET_KEY: project secret key

Set your API key in your environment:

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

Send a trace (minimal example)

The pattern is:

  1. Create a client
  2. Start a trace
  3. Add spans for important steps (LLM call, retrieval, tools)
  4. End the trace so it appears in the UI
import { NodeSDK } from "@opentelemetry/sdk-node"
import { LangfuseSpanProcessor, observe, propagateAttributes } from "@getboson/sdk"

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

  const run = observe(
    async () => {
      return { ok: true, at: new Date().toISOString() }
    },
    {
      name: "getting-started-handshake",
      asType: "span",
      captureInput: true,
      captureOutput: true,
    },
  )

  try {
    await propagateAttributes(
      {
        traceName: "getting-started",
        metadata: { env: process.env.NODE_ENV ?? "development" },
      },
      () => run(),
    )
    await spanProcessor.forceFlush()
  } finally {
    await spanProcessor.shutdown()
    await sdk.shutdown()
  }
}

main().catch((e) => {
  console.error(e)
  process.exitCode = 1
})

Verify in the UI

  • Open the Boson app and go to Traces
  • Filter by trace name: getting-started
  • Click into the trace and confirm you see:
    • the llm.call span
    • the input/output events (or whatever you captured)
  • Use stable identifiers: userId, sessionId, and any request id you already have
  • Redact or hash sensitive fields (PII, secrets) before sending
  • Add tags/metadata you’ll filter on (environment, release, model, feature flag)

Next steps

  • Read Product / Tracing to decide what to capture consistently
  • Set up Evaluations once you have 20–100 representative examples
// TODO: add real example