Run Trees¶

langsmith.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 outputs 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=uuid4)

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: Optional[list[str]] = 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: Optional[datetime] = None

End time of the run, if applicable.

error `class-attribute` `instance-attribute` ¶

error: Optional[str] = None

Error message, if the run encountered any issues.

serialized `class-attribute` `instance-attribute` ¶

serialized: Optional[dict] = 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: Optional[dict] = None

Outputs generated by the run, if any.

reference_example_id `class-attribute` `instance-attribute` ¶

reference_example_id: Optional[UUID] = None

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

parent_run_id `class-attribute` `instance-attribute` ¶

parent_run_id: Optional[UUID] = None

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

attachments `class-attribute` `instance-attribute` ¶

attachments: Union[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: Optional[UUID]

Retrieve the revision ID (if any).

latency `property` ¶

latency: Optional[float]

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: Optional[Mapping[str, Any]] = NOT_PROVIDED,
    outputs: Optional[Mapping[str, Any]] = NOT_PROVIDED,
    tags: Optional[Sequence[str]] = NOT_PROVIDED,
    metadata: Optional[Mapping[str, Any]] = NOT_PROVIDED,
    usage_metadata: Optional[ExtractedUsageMetadata] = 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: `Optional[Mapping[str, Any]]` DEFAULT: `NOT_PROVIDED`
`outputs`	The outputs to set. TYPE: `Optional[Mapping[str, Any]]` DEFAULT: `NOT_PROVIDED`
`tags`	The tags to set. TYPE: `Optional[Sequence[str]]` DEFAULT: `NOT_PROVIDED`
`metadata`	The metadata to set. TYPE: `Optional[Mapping[str, Any]]` DEFAULT: `NOT_PROVIDED`
`usage_metadata`	Usage information to set. TYPE: `Optional[ExtractedUsageMetadata]` DEFAULT: `NOT_PROVIDED`

RETURNS	DESCRIPTION
`None`	None

add_tags ¶

add_tags(tags: Union[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]`

RETURNS	DESCRIPTION
`None`	None

add_inputs ¶

add_inputs(inputs: 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]`

RETURNS	DESCRIPTION
`None`	None

add_event ¶

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

Add an event to the list of events.

RETURNS	DESCRIPTION
`None`	None

end ¶

end(
    *,
    outputs: Optional[dict] = None,
    error: Optional[str] = None,
    end_time: Optional[datetime] = None,
    events: Optional[Sequence[RunEvent]] = None,
    metadata: Optional[dict[str, Any]] = 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: Optional[ID_TYPE] = None,
    serialized: Optional[dict] = None,
    inputs: Optional[dict] = None,
    outputs: Optional[dict] = None,
    error: Optional[str] = None,
    reference_example_id: Optional[UUID] = None,
    start_time: Optional[datetime] = None,
    end_time: Optional[datetime] = None,
    tags: Optional[list[str]] = None,
    extra: Optional[dict] = None,
    attachments: Optional[Attachments] = 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: Optional[dict], **kwargs: Any) -> Optional[RunTree]

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

Requires langchain to be installed.

RETURNS	DESCRIPTION
`Optional[RunTree]`	Optional[RunTree]: The new span or None if no parent span information is found.

from_headers `classmethod` ¶

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

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
`Optional[RunTree]`	Optional[RunTree]: 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: Optional[Client] = _SENTINEL,
    enabled: Optional[bool] = _SENTINEL,
    project_name: Optional[str] = _SENTINEL,
    tags: Optional[list[str]] = _SENTINEL,
    metadata: Optional[dict[str, Any]] = _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: `Optional[Client]` 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: `Optional[bool]` 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: `Optional[str]` 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: `Optional[list[str]]` 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: `Optional[dict[str, Any]]` DEFAULT: `_SENTINEL`

RETURNS	DESCRIPTION
	None

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.

Run Trees¶

langsmith.run_trees ¶

RunTree ¶

name instance-attribute ¶

id class-attribute instance-attribute ¶

run_type class-attribute instance-attribute ¶

start_time class-attribute instance-attribute ¶

extra class-attribute instance-attribute ¶

tags class-attribute instance-attribute ¶

events class-attribute instance-attribute ¶

client property ¶

end_time class-attribute instance-attribute ¶

error class-attribute instance-attribute ¶

serialized class-attribute instance-attribute ¶

inputs class-attribute instance-attribute ¶

outputs class-attribute instance-attribute ¶

reference_example_id class-attribute instance-attribute ¶

parent_run_id class-attribute instance-attribute ¶

attachments class-attribute instance-attribute ¶

metadata property ¶

revision_id property ¶

latency property ¶