Exporters API

Exporters send trace data to various backends for storage and analysis.

Base Exporter

prela.exporters.base.BaseExporter

Bases: ABC

Abstract base class for span exporters.

Exporters are responsible for sending spans to external systems. Implementations must handle serialization, network requests, and error handling.

Functions

export(spans) abstractmethod

Export a batch of spans.

Parameters:

Name	Type	Description	Default
spans	list[Span]	List of spans to export	required

Raises:

Type	Description
Exception	If export fails and should not be retried

shutdown() abstractmethod

Shutdown the exporter and flush any pending data.

This method should be called before the application exits to ensure all spans are properly exported.

BatchExporter

prela.exporters.base.BatchExporter

Bases: BaseExporter

Base class for exporters that batch spans with retry logic.

This class handles common batching concerns: - Retry with exponential backoff - Timeout handling - Error logging

Subclasses only need to implement _do_export() to define how spans are actually sent to the backend.

Functions

__init__(max_retries=3, initial_backoff_ms=100.0, max_backoff_ms=10000.0, timeout_ms=30000.0)

Initialize the batch exporter.

Parameters:

Name	Type	Description	Default
max_retries	int	Maximum number of retry attempts	3
initial_backoff_ms	float	Initial backoff delay in milliseconds	100.0
max_backoff_ms	float	Maximum backoff delay in milliseconds	10000.0
timeout_ms	float	Timeout for export operation in milliseconds	30000.0

export(spans)

Export spans with retry logic.

Parameters:

Name	Type	Description	Default
spans	list[Span]	List of spans to export	required

Raises:

Type	Description
RuntimeError	If exporter is shutdown
Exception	If export fails after all retries

shutdown()

Shutdown the exporter.

Subclasses can override this to implement custom shutdown logic like flushing buffers or closing connections.

_do_export(spans) abstractmethod

Perform the actual export operation.

This method should be implemented by subclasses to define how spans are sent to the backend system.

Parameters:

Name	Type	Description	Default
spans	list[Span]	List of spans to export	required

Returns:

Type	Description
ExportResult	ExportResult indicating success, failure, or retry needed

ExportResult

prela.exporters.base.ExportResult

Bases: Enum

Result of an export operation.

Console Exporter

prela.exporters.console.ConsoleExporter

Bases: BaseExporter

Export spans to console with pretty-printed tree visualization.

Features: - Tree structure showing parent-child relationships - Color-coded output (when rich library is available) - Multiple verbosity levels (minimal, normal, verbose) - Duration and status indicators - Key attribute display

Example

from prela.core.tracer import Tracer
from prela.exporters.console import ConsoleExporter

tracer = Tracer(
    service_name="my-agent",
    exporter=ConsoleExporter(
        verbosity="normal",
        color=True,
        show_timestamps=True
    )
)

with tracer.span("research_agent", span_type="agent") as span:
    with tracer.span("gpt-4", span_type="llm") as llm_span:
        llm_span.set_attribute("llm.model", "gpt-4")
        llm_span.set_attribute("llm.input_tokens", 150)
        llm_span.set_attribute("llm.output_tokens", 89)
# Output:
# ─ agent: research_agent (1.523s) ✓
#   └─ llm: gpt-4 (823ms) ✓
#      model: gpt-4 | tokens: 150 → 89

Functions

__init__(verbosity='normal', color=True, show_timestamps=True)

Initialize console exporter.

Parameters:

Name	Type	Description	Default
verbosity	str	Output verbosity level: - "minimal": name + duration + status only - "normal": + key attributes (model, tokens, query) - "verbose": + all attributes + events	'normal'
color	bool	Enable colored output (requires rich library)	True
show_timestamps	bool	Show timestamps in output	True

export(spans)

Export spans to console with tree visualization.

Parameters:

Name	Type	Description	Default
spans	list[Span]	List of spans to export	required

Returns:

Type	Description
ExportResult	ExportResult.SUCCESS (console export never fails)

File Exporter

prela.exporters.file.FileExporter

Bases: BaseExporter

Export spans to JSONL files with rotation and trace management.

Features: - Thread-safe writes using a lock - Automatic directory creation - Date-based file naming with sequence numbers - Optional file rotation based on size - Trace retrieval by trace_id - Trace listing by date range - Old trace cleanup

File naming: traces-{date}-{sequence}.jsonl Example: traces-2025-01-26-001.jsonl

The JSONL format writes one JSON object per line, making it easy to stream and process large trace files.

Example

from prela.core.tracer import Tracer
from prela.exporters.file import FileExporter

tracer = Tracer(
    service_name="my-app",
    exporter=FileExporter(
        directory="./traces",
        max_file_size_mb=100,
        rotate=True
    )
)

with tracer.span("operation") as span:
    span.set_attribute("key", "value")
# Span is automatically written to ./traces/traces-2025-01-26-001.jsonl

Functions

__init__(directory='./traces', format='jsonl', max_file_size_mb=100, rotate=True)

Initialize file exporter.

Parameters:

Name	Type	Description	Default
directory	str | Path	Directory to store trace files (e.g., "./traces")	'./traces'
format	str	File format - "jsonl" or "ndjson" (both are equivalent)	'jsonl'
max_file_size_mb	int	Maximum file size in MB before rotation	100
rotate	bool	Whether to rotate files when size exceeded	True

export(spans)

Export spans to file.

Parameters:

Name	Type	Description	Default
spans	list[Span]	List of spans to export	required

Returns:

Type	Description
ExportResult	ExportResult.SUCCESS if successful, ExportResult.FAILURE otherwise

shutdown()

Shutdown the exporter.

No cleanup needed for file exporter - file handle is closed after each write.

list_traces(start, end)

List trace IDs within a date range.

Parameters:

Name	Type	Description	Default
start	datetime	Start datetime (inclusive)	required
end	datetime	End datetime (inclusive)	required

Returns:

Type	Description
list[str]	List of unique trace IDs found in the date range

cleanup_old_traces(days)

Delete trace files older than specified days.

Parameters:

Name	Type	Description	Default
days	int	Delete files older than this many days (0 means keep today and delete all older)	required

Returns:

Type	Description
int	Number of files deleted