• October 22, 2026
• 8 min read

LangSmith — Setup & Architecture¶

Hosting Options¶

• Hybrid is a topology of LangSmith Deployment (agent hosting), not a separate observability product: Agent Servers run in your infrastructure and send traces to LangSmith Cloud or to a self-hosted instance via LANGSMITH_ENDPOINT.
• Observability only (no agent hosting) works on Cloud or self-hosted: run the app anywhere and send traces.
• Licensing: the SDKs are MIT-licensed; the platform is a commercial product. Self-hosting and BYOC require an Enterprise contract.

Cloud Regions¶

The region is fixed by the URL where the account was created. An organization cannot span regions and cannot be migrated between them; features and prices are the same everywhere.

• Billing and payment data are stored in the US regardless of region.
• BYOC data planes are placed in a chosen AWS region (US, Canada, EU, APAC); the control plane (users, roles, billing, SSO, API keys) stays in us-east-2.

Self-Hosted Architecture¶

flowchart LR
  SDK["SDK / OTLP exporters"] -- "HTTPS /api/v1, /otel" --> FE["frontend (Nginx)<br/>UI + API entrypoint"]
  UI["Browser"] --> FE
  FE --> BE["backend<br/>CRUD API, hub API"]
  FE --> PB["platform backend<br/>auth, run ingestion"]
  PB --> Q["queue<br/>async ingestion, retries"]
  Q --> CH[("ClickHouse<br/>traces, feedback")]
  Q --> BS[("Blob storage<br/>large payloads")]
  BE --> PG[("PostgreSQL<br/>datasets, prompts, users")]
  Q --> RD[("Redis / Valkey<br/>queues, cache")]
  FE --> PL["Playground<br/>forwards to LLM APIs"]
  FE --> ACE["ACE backend<br/>sandboxed custom code"]

• Install with Helm on Kubernetes; Terraform modules exist for AWS, GCP and Azure. Use external managed ClickHouse, PostgreSQL and Redis for production.
• Ingestion is asynchronous: a run is queryable shortly after it is sent, not instantly — poll when tests read traces back.
• Features in the base install: observability, evaluation, prompt engineering, Insights, Chat. Agent-based workspaces are not available on self-hosted.

Workspaces, Projects and Agents¶

Organization (billing, SSO, members)
 └── Workspace  (API-key scope, RBAC, datasets, prompts, annotation queues)
      ├── project-based:  Tracing project  → traces, experiments
      └── agent-based:    Agent → Environment (local | development | staging | production) → traces

# project addressing
export LANGSMITH_PROJECT=checkout-ci

# agent addressing (langsmith >= 0.14.9, agent-based workspaces)
export LANGSMITH_AGENT_ID=checkout              # 1-63 chars: lowercase letters, digits, hyphens
export LANGSMITH_AGENT_ENVIRONMENT=development  # local | development | staging | production

• An agent or a project — never both. Setting both is a warning, and passing address and project_name together in code raises LangSmithUserError.
• In code: @traceable(address=ls.agent_address("checkout", "production")) or tracing_context(address=...). The address argument is marked beta in the SDK.
• In an agent-based workspace, the first trace to a new LANGSMITH_PROJECT name creates an agent of that name with the project as its Production environment.
• Self-hosted instances reject agent-addressed runs with HTTP 403.
• Separate trust boundaries (teams, customers) by workspace; separate environments (CI, staging, production) by project or environment.

API Keys¶

• Create keys in Settings → API Keys; the secret is shown once. Set an expiration.
• Evaluations, datasets and prompts need a PAT or service key — a tracing key cannot read traces, run experiments or manage keys.
• A key linked to several workspaces needs LANGSMITH_WORKSPACE_ID (direct API calls send X-Tenant-Id).
• Deactivating or deleting a key takes effect within about a minute (auth results are cached). Service keys can only be deleted.

Configuration¶

• LANGCHAIN_* names (LANGCHAIN_PROJECT, LANGCHAIN_API_KEY) are legacy aliases of the LANGSMITH_* variables.
• Other LANGSMITH_* variables, except secret-like names (containing key, secret, token, password, ...), are copied into run metadata. Do not store sensitive values in them.

Without environment variables, pass a client explicitly:

import langsmith as ls

client = ls.Client(api_key="lsv2_pt_...", api_url="https://eu.api.smith.langchain.com", workspace_id="<workspace-id>")

with ls.tracing_context(client=client, project_name="ci-run", enabled=True):
    run_app()                       # everything traced inside goes to that workspace and project

Profiles keep several setups side by side (langsmith profile create eu --api-url https://eu.api.smith.langchain.com --workspace-id <id>, then LANGSMITH_PROFILE=eu). The profile file holds secrets: chmod 600, never commit it.

RBAC¶

Typical QA setup: QA engineers are Editors on the test workspace (create datasets, annotate, run experiments) and Viewers on production; CI uses a workspace-scoped service key; the production app uses a tracing key.

Data Retention¶

• The tier is a property of the project (per environment in agent workspaces); changing it affects new traces only. Enterprise can customize the extended period per workspace up to the SaaS maximum.
• Auto-upgrade to extended (and the higher price) happens when an online evaluator or automation rule with retention extension matches a run, or when feedback is created through the SDK/API with extend_trace_retention=True (the Python default). UI feedback, notes and manually adding runs to a queue do not upgrade.
• Datasets are never deleted by retention: copy valuable runs into a dataset. Monitoring charts keep working after base traces expire.
• Self-hosted: TTL is enabled in the Helm chart (config.ttl); chart defaults are 14 days (shortlived) and 400 days (longlived), and Enterprise sets the extended period per workspace in the UI.
• Limits worth knowing: 25,000 runs per trace; HTTP 429 when rate or plan limits are hit (the SDK batches up to 100 runs per request).

Relation to OpenTelemetry¶

• OTEL_EXPORTER_OTLP_ENDPOINT is a base URL: exporters append /v1/traces; do not include it.
• Mapping: langsmith.span.kind → run type, langsmith.metadata.<key> → metadata, gen_ai.* and OpenInference attributes → LLM fields, OTEL_RESOURCE_ATTRIBUTES → metadata.
• Agent workspaces use Langsmith-Agent-Id and Langsmith-Agent-Environment headers instead of Langsmith-Project; send both or neither.

Details and code: 02 Tracing with the Python SDK.

See also¶

• LangSmith — LLM Tracing, Prompts & Evals
• LangSmith — Tracing with the Python SDK
• OpenTelemetry — Python Observability
• Jaeger — Distributed Tracing for OpenTelemetry
• Langfuse — Setup & Architecture
• LangGraph — Observability & Deployment