Spaces:
Sleeping
Sleeping
File size: 5,231 Bytes
116524e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | # 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
```bash
pip install ace-framework[tracing]
```
## Quick Start
```python
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:
```python
from ace.tracing import configure
configure()
```
Or skip the import entirely and configure from `ace`:
```python
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:
```python
from ace.tracing import trace
@trace
def classify(text: str) -> str:
return call_llm(f"Classify: {text}")
```
Add metadata with optional parameters:
```python
@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:
```python
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:
```python
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:
```python
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
```python
from ace.tracing import enable, disable
disable() # temporarily stop sending traces
# ... untraced code ...
enable() # resume
```
## Retrieving Traces
```python
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 |
|