Traces#

class TracesClient(*, sdk_config: SDKConfiguration, generated_client: ApiClient)[source]#

Bases: object

Client for listing LLM traces from the Arize platform.

This class is primarily intended for internal use within the SDK. Users are highly encouraged to access resource-specific functionality via arize.ArizeClient.

The traces client is a thin wrapper around the generated REST API client, using the shared generated API client owned by arize.config.SDKConfiguration.

Parameters:

  • sdk_config (SDKConfiguration) – Resolved SDK configuration.

  • generated_client (ApiClient) – Shared generated API client instance.

list(*, project: str, space: str | None = None, start_time: datetime | None = None, end_time: datetime | None = None, filter: str | None = None, limit: int = DEFAULT_LIST_LIMIT, cursor: str | None = None) → ListTracesResponse[source]#

List traces for a project within a time range.

Each returned trace carries its full (flat) list of spans plus lightweight roll-up metadata. Traces are returned newest-first.

The filter uses the same expression syntax as arize.spans.client.SpansClient.list, but the semantics differ: a filter selects traces that contain at least one matching span (the matching span is usually a child, not the root), rather than only traces whose root span matches.

Parameters:

  • project (str) – Project name or identifier (base64) to list traces for. If the value is a name, space must also be provided.

  • space (str | None) – Optional space name or ID used to disambiguate the project lookup. Required when project is a name.

  • start_time (datetime | None) – Inclusive lower bound of the time window. Defaults to seven days before the request time.

  • end_time (datetime | None) – Exclusive upper bound of the time window. Defaults to the request time.

  • filter (str | None) –

    Optional filter expression to narrow results. Supports equality, comparison, and SQL-style AND/OR operators. A trace is returned when any of its spans matches the filter. Examples:

    "status_code = 'ERROR'"
"span_kind = 'LLM'"
"status_code = 'ERROR' AND span_kind = 'LLM'"

  • limit (int) – Maximum number of traces to return. The server enforces an upper bound. Defaults to 50.

  • cursor (str | None) – Opaque pagination cursor returned from a previous response.

Returns:

A response object with the traces and pagination information.

Raises:

ApiException – If the REST API returns an error response (e.g. 401/403/429).

Return type:

ListTracesResponse

Response Types#

Public type re-exports for the traces subdomain.

class ListTracesResponse(*, traces: List[Trace], pagination: PaginationMetadata)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
traces: List[Trace]#
pagination: PaginationMetadata#
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of ListTracesResponse from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of ListTracesResponse from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

to_df(by_alias: bool = False, exclude_none: str | bool = True, json_normalize: bool = False, convert_dtypes: bool = True, expand_field: str = 'additional_properties', expand_prefix: str = '') → pd.DataFrame#

Convert a list of objects to a pandas.DataFrame.

Behavior:

  • If an item is a Pydantic v2 model, use .model_dump(by_alias=…).

  • If an item is a mapping (dict-like), use it as-is.

  • Otherwise, raise a ValueError (unsupported row type).

Parameters:

  • self (object) – The object instance containing the field to convert.

  • by_alias (bool) – Use field aliases when dumping Pydantic models.

  • exclude_none (str | bool) – Control None/NaN column dropping. - False: keep Nones as-is - “all”: drop columns where all values are None/NaN - “any”: drop columns where any value is None/NaN - True: alias for “all”

  • json_normalize (bool) – If True, flatten nested dicts via pandas.json_normalize.

  • convert_dtypes (bool) – If True, call DataFrame.convert_dtypes() at the end.

  • expand_field (str) – If set, look for this field in each row and expand its keys into top-level columns.

  • expand_prefix (str) – If set, prefix expanded column names with this string.

Returns:

The converted DataFrame.

Return type:

pandas.DataFrame

class Trace(*, trace_id: Annotated[str, Strict(strict=True)], root_span_id: Annotated[str, Strict(strict=True)], start_time: datetime | None = None, end_time: datetime | None = None, spans_truncated: Annotated[bool, Strict(strict=True)], spans: List[Span])[source]#

Bases: BaseModel

A Trace is the collection of spans sharing a trace_id, anchored on a root span (a span with no parent). It captures a single end-to-end request through an LLM application, with lightweight roll-up metadata plus the full flat list of its spans.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
trace_id: StrictStr#
root_span_id: StrictStr#
start_time: datetime | None#
end_time: datetime | None#
spans_truncated: StrictBool#
spans: List[Span]#
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of Trace from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of Trace from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None