Package dev.braintrust.trace

Class BrainstoreTrace

java.lang.Object

dev.braintrust.trace.BrainstoreTrace

public class BrainstoreTrace
extends Object

Provides access to the distributed trace spans for a single eval task stored in Braintrust.

Spans are fetched lazily on first access and cached for subsequent calls. Score-type spans are excluded from all results (they are filtered out by the BTQL query).

Method Summary

Modifier and Type	Method	Description
static BrainstoreTrace	forExperiment(BraintrustOpenApiClient client, String experimentId, String rootTraceId, List<String> expectedSpanIds)	Creates a BrainstoreTrace that fetches spans for a trace stored in a Braintrust experiment.
static BrainstoreTrace	forTrace(BraintrustOpenApiClient client, String projectId, String rootTraceId, List<String> expectedSpanIds)	Creates a BrainstoreTrace that fetches spans for a trace stored in Braintrust project logs.
List<Map<String,Object>>	getLLMConversationThread()	Reconstructs the LLM conversation thread from all LLM spans in this trace.
List<Map<String,Object>>	getSpans()	Returns all non-score spans for this trace.
List<Map<String,Object>>	getSpans(String spanType)	Returns spans filtered by span_attributes.type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

forExperiment

public static BrainstoreTrace forExperiment(@Nonnull
 BraintrustOpenApiClient client,
 @Nonnull
 String experimentId,
 @Nonnull
 String rootTraceId,
 @Nonnull
 List<String> expectedSpanIds)

Creates a BrainstoreTrace that fetches spans for a trace stored in a Braintrust experiment.

Queries experiment('<experimentId>') and excludes score-type spans. The retry loop blocks until all expectedSpanIds are present in the results.

Parameters:

client - the API client used to execute BTQL queries

experimentId - the experiment whose spans to query

rootTraceId - the OTel trace ID (hex string, 32 chars)

expectedSpanIds - OTel span IDs (16 hex chars each) that must all appear in the results before the fetch is considered complete

forTrace

public static BrainstoreTrace forTrace(@Nonnull
 BraintrustOpenApiClient client,
 @Nonnull
 String projectId,
 @Nonnull
 String rootTraceId,
 @Nonnull
 List<String> expectedSpanIds)

Creates a BrainstoreTrace that fetches spans for a trace stored in Braintrust project logs.

Queries project_logs('<projectId>') for all spans in the trace. The retry loop blocks until all expectedSpanIds are present in the results.

Parameters:

client - the API client used to execute BTQL queries

projectId - the project whose logs to query

rootTraceId - the OTel trace ID (hex string, 32 chars)

expectedSpanIds - OTel span IDs (16 hex chars each) that must all appear in the results before the fetch is considered complete

getSpans

public List<Map<String,Object>> getSpans()

Returns all non-score spans for this trace. Results are fetched on first call and cached.

Returns:

an immutable list of span maps; each map contains the span's fields as returned by BTQL (e.g. "input", "output", "span_attributes", "start_time", "end_time")

getSpans

public List<Map<String,Object>> getSpans(@Nonnull
 String spanType)

Returns spans filtered by span_attributes.type.

Common types: "llm", "task", "eval", "tool", "function".

Parameters:

spanType - the value of span_attributes.type to filter by

Returns:

spans whose span_attributes.type matches spanType

getLLMConversationThread

public List<Map<String,Object>> getLLMConversationThread()

Reconstructs the LLM conversation thread from all LLM spans in this trace.

Flattens the span tree via pre-order DFS (parent before children, siblings in metrics.start order), then walks the resulting LLM-span sequence and de-duplicates using a seen-set: any input or output item already added to the thread is skipped.

Returns:

a flat, ordered list of message/output maps from all LLM spans in the trace