Migrate from LangSmith · 2026

LangSmith is tightly bound to the LangChain ecosystem. Spanlens speaks the same graph-aware tracing shape but is provider-neutral: you can run it on plain OpenAI calls, LangChain, LangGraph, Vercel AI SDK, or raw HTTP from any language. This page shows how to swap the two without rewriting your chains.

Why teams switch

• No framework lock-in. The Spanlens proxy works whether or not you use LangChain. Most teams end up with a mix of LangChain chains and direct OpenAI calls; LangSmith only sees the LangChain half by default.
• Drop-in proxy adds zero-instrumentation paths. Background workers, third-party libraries, MCP servers all get logged automatically once they share the SDK or base URL. With LangSmith you have to thread @traceable through everything.
• Cost and token tracking on every call. Spanlens computes cost from a versioned price table and stores cost_usd directly on the request row, no downstream aggregation step needed.
• MIT self-host. One Docker compose, your Supabase + ClickHouse.

Step 1. Install

pnpm add @spanlens/sdk

Step 2. Swap LangChain / LangGraph tracing

If you use LangChain or LangGraph today, this is the smallest change. Replace the ambient LANGSMITH_TRACING=true env-var setup with an explicit Spanlens callback handler.

Before (LangSmith, env-var driven):

# .env
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=ls__xxx
LANGSMITH_PROJECT=my-app
LANGSMITH_ENDPOINT=https://api.smith.langchain.com

// chains.ts
import { ChatOpenAI } from '@langchain/openai'

const llm = new ChatOpenAI({ model: 'gpt-4o-mini' })
// LangSmith picks up every call automatically via the env vars above.

After (Spanlens callback handler):

# .env
SPANLENS_API_KEY=sl_live_xxx

// chains.ts
import { ChatOpenAI } from '@langchain/openai'
import { SpanlensClient } from '@spanlens/sdk'
import { createSpanlensCallbackHandler } from '@spanlens/sdk/langchain'

const client = new SpanlensClient()
const handler = createSpanlensCallbackHandler({ client })

const llm = new ChatOpenAI({ model: 'gpt-4o-mini' })

// Attach the handler at invocation time:
const res = await chain.invoke({ input }, { callbacks: [handler] })

// Or for LangGraph:
const graph = workflow.compile()
const res = await graph.invoke({ input }, { callbacks: [handler] })

The handler captures LLM, chain (LangGraph node), tool, and retriever spans. TherunId / parentRunId pair LangChain gives every callback becomes the Spanlens span tree, so the graph topology is preserved.

Detailed walkthrough including LangGraph specifics on /docs/integrations/langgraph.

Step 3. Replace the traceable decorator / wrapper

For non-LangChain code, LangSmith uses @traceable (Python) or traceable() (JS) to wrap arbitrary functions into runs. The Spanlens equivalent is observe().

Before (LangSmith):

import { traceable } from 'langsmith/traceable'

const answer = traceable(
  async (input: string) => {
    const docs = await retrieve(input)
    const resp = await openai.chat.completions.create({...})
    return resp.choices[0].message.content
  },
  { name: 'answer-question' },
)

After (Spanlens):

import { SpanlensClient } from '@spanlens/sdk'
import { observe } from '@spanlens/sdk'

const client = new SpanlensClient()

async function answer(input: string) {
  const trace = client.startTrace({ name: 'answer-question' })
  try {
    const docs = await observe(trace, { name: 'retrieve' }, () => retrieve(input))
    const resp = await observe(trace, { name: 'generate', spanType: 'llm' }, () =>
      openai.chat.completions.create({...})
    )
    return resp.choices[0].message.content
  } finally {
    await trace.end()
  }
}

Nested observe() calls under the same parent automatically chain into a span tree. If you want the function-decorator ergonomics, wrap once at the entry point of your route handler and call ordinary functions inside; Spanlens does not require every leaf to be decorated.

Step 4. Environment variables

Step 5. Data model mapping

Step 6. Run both side-by-side during the cutover

LangSmith and Spanlens do not conflict. Keep LangSmith env vars in place while you add the Spanlens callback handler; you will see both dashboards populated.

// Both active for one chain
const langsmithEnabled = process.env.LANGSMITH_TRACING === 'true'
const handlers = langsmithEnabled
  ? [createSpanlensCallbackHandler({ client })]  // LangSmith auto-attaches
  : [createSpanlensCallbackHandler({ client })]

await chain.invoke({ input }, { callbacks: handlers })

When the Spanlens dashboard matches LangSmith for a representative slice of traffic, drop LANGSMITH_TRACING, remove the LangSmith env vars, uninstall langsmith.

What does not migrate 1:1

• LangSmith Hub (public prompt library). Spanlens does not have a public hub. Your private prompt versions live in /prompts and are referenced by name@version through x-spanlens-prompt-version.
• RunTree low-level API. Spanlens equivalent is the SpanlensClient.startTrace() / trace.span() / span.child() chain. Same shape, different names.
• 400-day retention. Spanlens retention depends on plan: 14 days (Free), 90 days (Pro), 365 days (Team). Self-hosting removes the cap.
• LangChain auto-instrumentation across language boundaries. Within one Node process the callback handler covers LangChain JS and LangGraph JS. For Python LangChain, use the Python SDK.

Verify the cutover

1. Invoke a traced chain once.
2. Open /traces. The span tree should mirror what LangSmith showed, including LangGraph node hierarchy.
3. Open the LLM call detail. Token counts and cost should match the LangSmith run within 1%.
4. If you used datasets / eval feedback in LangSmith, re-create the dataset in /datasets and re-run the evaluator in /evals against the same dataset items.

Next: LangGraph integration for graph topology details, or data model for the full schema.