Run Trees

run_trees

Schemas for the LangSmith API.

RunTree

Bases: RunBase

Run Schema with back-references for posting runs.

METHOD	DESCRIPTION
infer_defaults	Assign name to the run.
ensure_dotted_order	Ensure the dotted order of the run.
__setattr__	Set the _client specially.
set	Set the inputs, outputs, tags, and metadata of the run.
add_tags	Add tags to the run.
add_metadata	Add metadata to the run.
add_outputs	Upsert the given outputs into the run.
add_inputs	Upsert the given inputs into the run.
add_event	Add an event to the list of events.
end	Set the end time of the run and all child runs.
create_child	Add a child run to the run tree.
post	Post the run tree to the API asynchronously.
patch	Patch the run tree to the API in a background thread.
wait	Wait for all _futures to complete.
get_url	Return the URL of the run.
from_dotted_order	Create a new 'child' span from the provided dotted order.
from_runnable_config	Create a new 'child' span from the provided runnable config.
from_headers	Create a new 'parent' span from the provided headers.
to_headers	Return the RunTree as a dictionary of headers.
__repr__	Return a string representation of the RunTree object.

name instance-attribute

name: str

Human-readable name for the run.

id class-attribute instance-attribute

id: UUID = Field(default_factory=uuid7)

Unique identifier for the run.

run_type class-attribute instance-attribute

run_type: str = Field(default='chain')

The type of run, such as tool, chain, llm, retriever, embedding, prompt, parser.

start_time class-attribute instance-attribute

start_time: datetime = Field(default_factory=lambda: now(utc))

Start time of the run.

extra class-attribute instance-attribute

extra: dict = Field(default_factory=dict)

Additional metadata or settings related to the run.

tags class-attribute instance-attribute

tags: list[str] | None = Field(default_factory=list)

Tags for categorizing or annotating the run.

events class-attribute instance-attribute

events: list[dict] = Field(default_factory=list)

List of events associated with the run, like start and end events.

client property

client: Client

Return the client.

end_time class-attribute instance-attribute

end_time: datetime | None = None

End time of the run, if applicable.

error class-attribute instance-attribute

error: str | None = None

Error message, if the run encountered any issues.

serialized class-attribute instance-attribute

serialized: dict | None = None

Serialized object that executed the run for potential reuse.

inputs class-attribute instance-attribute

inputs: dict = Field(default_factory=dict)

Inputs used for the run.

outputs class-attribute instance-attribute

outputs: dict | None = None

Outputs generated by the run, if any.

reference_example_id class-attribute instance-attribute

reference_example_id: UUID | None = None

Reference to an example that this run may be based on.

parent_run_id class-attribute instance-attribute

parent_run_id: UUID | None = None

Identifier for a parent run, if this run is a sub-run.

attachments class-attribute instance-attribute

attachments: Attachments | dict[str, AttachmentInfo] = Field(default_factory=dict)

Attachments associated with the run.

Each entry is a tuple of (mime_type, bytes).

metadata property

metadata: dict[str, Any]

Retrieve the metadata (if any).

revision_id property

revision_id: UUID | None

Retrieve the revision ID (if any).

latency property

latency: float | None

Latency in seconds.

Config

Pydantic model configuration.

infer_defaults

infer_defaults(values: dict) -> dict

Assign name to the run.

ensure_dotted_order

ensure_dotted_order(values: dict) -> dict

Ensure the dotted order of the run.

__setattr__

__setattr__(name, value)

Set the _client specially.

set

set(
    *,
    inputs: Mapping[str, Any] | None = NOT_PROVIDED,
    outputs: Mapping[str, Any] | None = NOT_PROVIDED,
    tags: Sequence[str] | None = NOT_PROVIDED,
    metadata: Mapping[str, Any] | None = NOT_PROVIDED,
    usage_metadata: ExtractedUsageMetadata | None = NOT_PROVIDED,
) -> None

Set the inputs, outputs, tags, and metadata of the run.

If performed, this will override the default behavior of the end() method to ignore new outputs (that would otherwise be added) by the @traceable decorator.

If your LangChain or LangGraph versions are sufficiently up-to-date, this will also override the default behavior of LangChainTracer.

PARAMETER	DESCRIPTION
inputs	The inputs to set. TYPE: Mapping[str, Any] | None DEFAULT: NOT_PROVIDED
outputs	The outputs to set. TYPE: Mapping[str, Any] | None DEFAULT: NOT_PROVIDED
tags	The tags to set. TYPE: Sequence[str] | None DEFAULT: NOT_PROVIDED
metadata	The metadata to set. TYPE: Mapping[str, Any] | None DEFAULT: NOT_PROVIDED
usage_metadata	Usage information to set. TYPE: ExtractedUsageMetadata | None DEFAULT: NOT_PROVIDED

RETURNS	DESCRIPTION
None	None

add_tags

add_tags(tags: Sequence[str] | str) -> None

Add tags to the run.

add_metadata

add_metadata(metadata: dict[str, Any]) -> None

Add metadata to the run.

add_outputs

add_outputs(outputs: dict[str, Any]) -> None

Upsert the given outputs into the run.

PARAMETER	DESCRIPTION
outputs	A dictionary containing the outputs to be added. TYPE: dict[str, Any]

add_inputs

add_inputs(inputs: dict[str, Any]) -> None

Upsert the given inputs into the run.

PARAMETER	DESCRIPTION
inputs	A dictionary containing the inputs to be added. TYPE: dict[str, Any]

add_event

add_event(events: RunEvent | Sequence[RunEvent] | Sequence[dict] | dict | str) -> None

Add an event to the list of events.

PARAMETER	DESCRIPTION
events	The event(s) to be added. It can be a single event, a sequence of events, a sequence of dictionaries, a dictionary, or a string. TYPE: RunEvent | Sequence[RunEvent] | Sequence[dict] | dict | str

RETURNS	DESCRIPTION
None	None

end

end(
    *,
    outputs: dict | None = None,
    error: str | None = None,
    end_time: datetime | None = None,
    events: Sequence[RunEvent] | None = None,
    metadata: dict[str, Any] | None = None,
) -> None

Set the end time of the run and all child runs.

create_child

create_child(
    name: str,
    run_type: RUN_TYPE_T = "chain",
    *,
    run_id: ID_TYPE | None = None,
    serialized: dict | None = None,
    inputs: dict | None = None,
    outputs: dict | None = None,
    error: str | None = None,
    reference_example_id: UUID | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    tags: list[str] | None = None,
    extra: dict | None = None,
    attachments: Attachments | None = None,
) -> RunTree

Add a child run to the run tree.

post

post(exclude_child_runs: bool = True) -> None

Post the run tree to the API asynchronously.

patch

patch(*, exclude_inputs: bool = False) -> None

Patch the run tree to the API in a background thread.

PARAMETER	DESCRIPTION
exclude_inputs	Whether to exclude inputs from the patch request. TYPE: bool DEFAULT: False

wait

wait() -> None

Wait for all _futures to complete.

get_url

get_url() -> str

Return the URL of the run.

from_dotted_order classmethod

from_dotted_order(dotted_order: str, **kwargs: Any) -> RunTree

Create a new 'child' span from the provided dotted order.

RETURNS	DESCRIPTION
RunTree	The new span. TYPE: RunTree

from_runnable_config classmethod

from_runnable_config(config: dict | None, **kwargs: Any) -> RunTree | None

Create a new 'child' span from the provided runnable config.

Requires langchain to be installed.

RETURNS	DESCRIPTION
RunTree | None	The new span or None if no parent span information is found.

from_headers classmethod

from_headers(
    headers: Mapping[str | bytes, str | bytes], **kwargs: Any
) -> RunTree | None

Create a new 'parent' span from the provided headers.

Extracts parent span information from the headers and creates a new span.

Metadata and tags are extracted from the baggage header.

The dotted order and trace id are extracted from the trace header.

RETURNS	DESCRIPTION
RunTree | None	The new span or None if no parent span information is found.

to_headers

to_headers() -> dict[str, str]

Return the RunTree as a dictionary of headers.

__repr__

__repr__()

Return a string representation of the RunTree object.

configure

configure(
    client: Client | None = _SENTINEL,
    enabled: bool | None = _SENTINEL,
    project_name: str | None = _SENTINEL,
    tags: list[str] | None = _SENTINEL,
    metadata: dict[str, Any] | None = _SENTINEL,
)

Configure global LangSmith tracing context.

This function allows you to set global configuration options for LangSmith tracing that will be applied to all subsequent traced operations. It modifies context variables that control tracing behavior across your application.

Do this once at startup to configure the global settings in code.

If, instead, you wish to only configure tracing for a single invocation, use the tracing_context context manager instead.

PARAMETER	DESCRIPTION
client	A LangSmith Client instance to use for all tracing operations. If provided, this client will be used instead of creating new clients. Pass None to explicitly clear the global client. TYPE: Client | None DEFAULT: _SENTINEL
enabled	Whether tracing is enabled. Can be: True: Enable tracing and send data to LangSmith False: Disable tracing completely 'local': Enable tracing but only store data locally None: Clear the setting (falls back to environment variables) TYPE: bool | None DEFAULT: _SENTINEL
project_name	The LangSmith project name where traces will be sent. This determines which project dashboard will display your traces. Pass None to explicitly clear the project name. TYPE: str | None DEFAULT: _SENTINEL
tags	A list of tags to be applied to all traced runs. Tags are useful for filtering and organizing runs in the LangSmith UI. Pass None to explicitly clear all global tags. TYPE: list[str] | None DEFAULT: _SENTINEL
metadata	A dictionary of metadata to attach to all traced runs. Metadata can store any additional context about your runs. Pass None to explicitly clear all global metadata. TYPE: dict[str, Any] | None DEFAULT: _SENTINEL

Examples:

Basic configuration:

>>> import langsmith as ls
>>> # Enable tracing with a specific project
>>> ls.configure(enabled=True, project_name="my-project")

Set global trace masking:

>>> def hide_keys(data):
...     if not data:
...         return {}
...     return {k: v for k, v in data.items() if k not in ["key1", "key2"]}
>>> ls.configure(
...     client=ls.Client(
...         hide_inputs=hide_keys,
...         hide_outputs=hide_keys,
...     )
... )

Adding global tags and metadata:

>>> ls.configure(
...     tags=["production", "v1.0"],
...     metadata={"environment": "prod", "version": "1.0.0"},
... )

Disabling tracing:

>>> ls.configure(enabled=False)

validate_extracted_usage_metadata

validate_extracted_usage_metadata(
    data: ExtractedUsageMetadata,
) -> ExtractedUsageMetadata

Validate that the dict only contains allowed keys.