Tracing¶

Send agent traces to Kayba with a few lines of code. The ace.tracing module wraps all tracing functionality behind a Kayba-native API — just configure your API key and instrument your functions.

Installation¶

pip install ace-framework[tracing]

Quick Start¶

from ace.tracing import configure, trace, start_span

configure(api_key="kb-...")

@trace
def my_agent(query: str) -> str:
    with start_span("retrieval") as span:
        span.set_inputs({"query": query})
        results = search(query)
        span.set_outputs(results)
    return synthesize(results)

my_agent("What is the capital of France?")

Every call to my_agent now produces a trace visible in your Kayba dashboard.

Configuration¶

configure()¶

Parameter	Type	Default	Description
`api_key`	`str`	`None`	Kayba API key. Falls back to `KAYBA_API_KEY` env var
`base_url`	`str`	`None`	API base URL. Falls back to `KAYBA_API_URL`, then `https://use.kayba.ai`
`experiment`	`str`	`None`	Optional experiment name for grouping traces
`folder`	`str`	`None`	Optional folder name — traces are filed into this folder in the dashboard

Environment Variables¶

Variable	Description
`KAYBA_API_KEY`	API key (alternative to passing `api_key=` directly)
`KAYBA_API_URL`	Base URL override (default: `https://use.kayba.ai`)

Minimal Configuration¶

If KAYBA_API_KEY is set in your environment, configuration is a single line:

from ace.tracing import configure
configure()

Or skip the import entirely and configure from ace:

from ace import configure_tracing
configure_tracing(api_key="kb-...")

Instrumenting Your Code¶

@trace decorator¶

Wrap any function to automatically capture its inputs, outputs, and duration:

from ace.tracing import trace

@trace
def classify(text: str) -> str:
    return call_llm(f"Classify: {text}")

Add metadata with optional parameters:

@trace(name="custom-name", span_type="LLM", attributes={"model": "gpt-4o"})
def classify(text: str) -> str:
    return call_llm(f"Classify: {text}")

start_span context manager¶

For finer-grained control within a function:

from ace.tracing import trace, start_span

@trace
def my_agent(query: str) -> str:
    with start_span("retrieve") as span:
        span.set_inputs({"query": query})
        docs = vector_search(query)
        span.set_outputs({"count": len(docs)})

    with start_span("generate") as span:
        span.set_inputs({"docs": docs})
        answer = llm_generate(docs, query)
        span.set_outputs({"answer": answer})

    return answer

Spans nest automatically — child spans created inside a parent span are linked in the trace tree.

Nested function tracing¶

Decorated functions called within other decorated functions produce a nested trace:

from ace.tracing import trace

@trace
def retrieve(query: str) -> list[str]:
    return vector_search(query)

@trace
def generate(docs: list[str], query: str) -> str:
    return llm_call(docs, query)

@trace
def agent(query: str) -> str:
    docs = retrieve(query)      # child span
    return generate(docs, query) # child span

Calling agent("...") produces a single trace with three spans in a tree.

Folders¶

Traces can be organized into folders in the Kayba dashboard. Set the folder at configuration time or change it dynamically:

from ace.tracing import configure, set_folder, trace

# Set folder at configure time
configure(api_key="kb-...", folder="production")

@trace
def my_agent(query: str) -> str:
    ...

# Change folder mid-session
set_folder("staging")

# Clear folder (traces go to Unfiled)
set_folder(None)

All traces created after set_folder() are tagged with the new folder. Previously sent traces are not affected.

Enabling / Disabling¶

from ace.tracing import enable, disable

disable()  # temporarily stop sending traces
# ... untraced code ...
enable()   # resume

Retrieving Traces¶

from ace.tracing import get_trace, search_traces

# Fetch a specific trace by ID
t = get_trace("abc123")

# Search recent traces
traces = search_traces()

# Search within a specific experiment
traces = search_traces(experiment_names=["my-experiment"])

Full API Reference¶

Function	Description
`configure()`	Set API key, base URL, experiment, and folder
`trace`	Decorator — auto-instruments a function
`start_span()`	Context manager — create a child span with manual inputs/outputs
`set_folder()`	Change the target folder for subsequent traces
`get_folder()`	Return the currently configured folder
`enable()`	Re-enable tracing after disabling
`disable()`	Temporarily stop sending traces
`get_trace()`	Retrieve a trace by ID
`search_traces()`	Search for traces by experiment