How LangSmith structures data
LangSmith groups multiple traces within a project. Each trace records the sequence of steps your application takes for a single operation, which are made up of individual runs. You can link together traces from multi-turn conversations as a thread.Projects
A project is a container for all the traces related to a single application or service. Log traces to a project.Traces
A trace is a collection of runs for a single operation. For example, if a user request triggers a chain that calls an LLM and then an output parser, all of those runs belong to the same trace. Runs are bound to a trace by a unique trace ID. If you are familiar with OpenTelemetry, you can think of a LangSmith trace as a collection of spans.Each trace is limited to a maximum of 25,000 runs. Once the trace reaches this limit, LangSmith will reject any additional runs that you send for that trace.
Runs
A run is a span representing a single unit of work within your LLM application: a call to an LLM, a prompt formatting step, a retrieval call, or any other discrete operation. If you are familiar with OpenTelemetry, you can think of a run as a span.Threads
A thread is a sequence of traces representing a single conversation. Each turn in a multi-turn conversation is its own trace, but traces are linked by a shared identifier. To group traces into threads, pass a special metadata key (session_id, thread_id, or conversation_id) with a unique value.
Learn how to configure threads.
Use Polly to analyze traces, runs, and threads. Polly helps you understand agent performance, debug issues, and gain insights from conversation threads without manually digging through data.
Trace enrichment
Feedback
Feedback allows you to score an individual run based on certain criteria. Each feedback entry consists of a tag and a score, and is bound to a run by a unique run ID. Feedback can be continuous or discrete (categorical), and tags can be reused across runs within an organization. For more on how feedback is stored, refer to the Feedback data format guide.Tags
Tags are strings you can attach to runs to categorize, filter, and group them in the LangSmith UI. Learn how to attach tags to your traces.Metadata
Metadata is a collection of key-value pairs you can attach to runs. For example, application version, environment, or any other contextual information. Similarly to tags, you can use metadata to filter and group runs. Learn how to add metadata to your traces.Sending traces
There are two ways to send trace data to LangSmith.Integrations
LangSmith integrations provide automatic tracing for popular LLM providers and agent frameworks (the equivalent of auto-instrumentation in general observability). When you use a supported framework such as LangChain, LangGraph, OpenAI, Anthropic, or CrewAI, the integration captures inputs, outputs, and metadata without requiring manual code changes. Browse all integrations.Manual instrumentation
Manual instrumentation lets you add tracing to any code, regardless of the framework. Use it when you’re not using a supported integration or when you need granular control over what gets traced. LangSmith provides three mechanisms:@traceable/traceable: a decorator to trace any functiontracecontext manager (Python): wrap specific code blocksRunTreeAPI: low-level, explicit trace construction
Data retention
LangSmith (SaaS) retains trace data for 400 days from ingestion. After that, traces are permanently deleted, with limited metadata retained for usage statistics. For details on retention tiers and pricing, refer to Usage and billing: Data retention.To keep data beyond the retention period, add it to a dataset. Datasets persist indefinitely, even after the source trace is deleted.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.