---
title: prefactor_langchain.spans module
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

# prefactor_langchain.spans module

LangChain-specific span definitions for Prefactor observability.

This module defines span dataclasses that capture LangChain-specific semantics
using the ‘langchain:

```
*
```

’ type namespace. These spans are self-contained and
can be serialized to JSON for transport to the backend.

Note: span_id, parent_span_id, and trace_id are managed by the backend
automatically, so they are not included in these span definitions.

### *class* prefactor_langchain.spans.AgentSpan(name: str = 'unnamed', start_time: float = <factory>, end_time: float | None = None, status: Literal['pending', 'running', 'completed', 'failed']='pending', inputs: dict[str, ~typing.Any]=<factory>, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=<factory>, tags: list[str] = <factory>, error: [ErrorInfo](#prefactor_langchain.spans.ErrorInfo) | None = None, type: str = 'langchain:agent', agent_name: str | None = None, agent_config: dict[str, ~typing.Any]=<factory>, initial_messages: list[dict[str, ~typing.Any]]=<factory>, final_messages: list[dict[str, ~typing.Any]]=<factory>, iteration_count: int = 0)

Bases: [`LangChainSpan`](#prefactor_langchain.spans.LangChainSpan)

Span representing an agent execution.

Captures the lifecycle of an agent run, including the agent’s
name, configuration, and the messages/state that drove the execution.

#### agent_config *: dict[str, Any]*

#### agent_name *: str | None* *= None*

#### final_messages *: list[dict[str, Any]]*

#### initial_messages *: list[dict[str, Any]]*

#### iteration_count *: int* *= 0*

#### to_dict() → dict[str, Any]

Convert to dictionary including agent-specific fields.

#### type *: str* *= 'langchain:agent'*

### *class* prefactor_langchain.spans.ErrorInfo(error_type: str, message: str, stacktrace: str | None = None)

Bases: `object`

Error information for failed spans.

#### error_type *: str*

#### message *: str*

#### stacktrace *: str | None* *= None*

#### to_dict() → dict[str, Any]

Convert to dictionary for serialization.

### *class* prefactor_langchain.spans.LLMSpan(name: str = 'unnamed', start_time: float = <factory>, end_time: float | None = None, status: Literal['pending', 'running', 'completed', 'failed']='pending', inputs: dict[str, ~typing.Any]=<factory>, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=<factory>, tags: list[str] = <factory>, error: [ErrorInfo](#prefactor_langchain.spans.ErrorInfo) | None = None, type: str = 'langchain:agent', model_name: str | None = None, provider: str | None = None, token_usage: [TokenUsage](#prefactor_langchain.spans.TokenUsage) | None = None, temperature: float | None = None, max_tokens: int | None = None, top_p: float | None = None, stop_sequences: list[str] = <factory>, messages: list[dict[str, ~typing.Any]]=<factory>, response_content: str | None = None)

Bases: [`LangChainSpan`](#prefactor_langchain.spans.LangChainSpan)

Span representing an LLM call.

Captures model-specific metadata including the model name, provider,
token usage, and generation parameters.

#### max_tokens *: int | None* *= None*

#### messages *: list[dict[str, Any]]*

#### model_name *: str | None* *= None*

#### provider *: str | None* *= None*

#### response_content *: str | None* *= None*

#### stop_sequences *: list[str]*

#### temperature *: float | None* *= None*

#### to_dict() → dict[str, Any]

Convert to dictionary including LLM-specific fields.

#### token_usage *: [TokenUsage](#prefactor_langchain.spans.TokenUsage) | None* *= None*

#### top_p *: float | None* *= None*

#### type *: str* *= 'langchain:llm'*

### *class* prefactor_langchain.spans.LangChainSpan(name: str = 'unnamed', start_time: float = <factory>, end_time: float | None = None, status: Literal['pending', 'running', 'completed', 'failed']='pending', inputs: dict[str, ~typing.Any]=<factory>, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=<factory>, tags: list[str] = <factory>, error: [ErrorInfo](#prefactor_langchain.spans.ErrorInfo) | None = None, type: str = 'langchain:agent')

Bases: `object`

Base class for all LangChain spans.

All LangChain spans share common fields for timing, status,
inputs/outputs, and error information. Trace correlation
(span_id, parent_span_id, trace_id) is handled by the backend.

Note: The ‘type’ field is defined in subclasses to avoid dataclass
field shadowing issues.

#### complete(outputs: dict[str, Any] | None = None) → None

Mark the span as completed with outputs.

#### end_time *: float | None* *= None*

#### error *: [ErrorInfo](#prefactor_langchain.spans.ErrorInfo) | None* *= None*

#### fail(error: Exception) → None

Mark the span as failed with error information.

#### inputs *: dict[str, Any]*

#### metadata *: dict[str, Any]*

#### name *: str* *= 'unnamed'*

#### outputs *: dict[str, Any] | None* *= None*

#### start_time *: float*

#### status *: Literal['pending', 'running', 'completed', 'failed']* *= 'pending'*

#### tags *: list[str]*

#### to_dict() → dict[str, Any]

Convert span to dictionary for serialization.

Returns a JSON-serializable dictionary representation of the span.

#### type *: str* *= 'langchain:agent'*

### *class* prefactor_langchain.spans.TokenUsage(prompt_tokens: int, completion_tokens: int, total_tokens: int)

Bases: `object`

Token usage information for LLM calls.

#### completion_tokens *: int*

#### prompt_tokens *: int*

#### to_dict() → dict[str, Any]

Convert to dictionary for serialization.

#### total_tokens *: int*

### *class* prefactor_langchain.spans.ToolSpan(name: str = 'unnamed', start_time: float = <factory>, end_time: float | None = None, status: Literal['pending', 'running', 'completed', 'failed']='pending', inputs: dict[str, ~typing.Any]=<factory>, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=<factory>, tags: list[str] = <factory>, error: [ErrorInfo](#prefactor_langchain.spans.ErrorInfo) | None = None, type: str = 'langchain:agent', tool_name: str | None = None, tool_schema: dict[str, ~typing.Any] | None=None, arguments: dict[str, ~typing.Any]=<factory>, execution_time_ms: int | None = None, tool_type: str | None = None, retriever_metadata: dict[str, ~typing.Any] | None=None)

Bases: [`LangChainSpan`](#prefactor_langchain.spans.LangChainSpan)

Span representing a tool execution.

Captures tool-specific metadata including the tool name, schema,
arguments, and execution time. Can represent any tool call including
retrievers (with appropriate metadata).

#### arguments *: dict[str, Any]*

#### execution_time_ms *: int | None* *= None*

#### retriever_metadata *: dict[str, Any] | None* *= None*

#### to_dict() → dict[str, Any]

Convert to dictionary including tool-specific fields.

#### tool_name *: str | None* *= None*

#### tool_schema *: dict[str, Any] | None* *= None*

#### tool_type *: str | None* *= None*

#### type *: str* *= 'langchain:tool'*