> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracer & Auto-Instrumentation

> Trace your AI app with zero-config auto-instrumentation, decorators, manual spans, and exporters.

## Overview

Valiqor tracing captures the full execution flow of your AI application — LLM calls, tool executions, retrieval steps, and custom logic — as structured traces with spans. Three levels of instrumentation are available:

1. **Zero-config** — `import valiqor.auto` and traces are captured automatically
2. **Decorators** — `@trace_workflow` and `@trace_function` for explicit control
3. **Manual spans** — Full control via `TracerV2` for complex pipelines

***

## Zero-Config Auto-Instrumentation

The simplest way to start tracing. Add one import at the top of your application:

```python theme={"system"}
import valiqor.auto
```

This reads your configuration from environment variables or `.valiqorrc` and automatically patches supported providers (OpenAI, Anthropic, LangChain, Ollama, Agno).

***

## `autolog()` Function

Enable auto-instrumentation programmatically with more control:

```python theme={"system"}
from valiqor.trace import autolog

# Enable all supported providers
autolog()

# Enable specific providers only
autolog(providers=["openai", "langchain"])
```

### `disable_autolog()`

Disable auto-instrumentation:

```python theme={"system"}
from valiqor.trace import disable_autolog

disable_autolog()  # Disable all
disable_autolog(providers=["openai"])  # Disable specific
```

### Provider-Specific Shortcuts

```python theme={"system"}
from valiqor.trace import (
    openai_autolog,
    anthropic_autolog,
    langchain_autolog,
    ollama_autolog,
    agno_autolog,
)

openai_autolog()       # Enable OpenAI tracing only
anthropic_autolog()    # Enable Anthropic tracing only
langchain_autolog()    # Enable LangChain tracing only
ollama_autolog()       # Enable Ollama tracing only
agno_autolog()         # Enable Agno tracing only
```

***

## `configure()` Function

Configure the tracing system programmatically:

```python theme={"system"}
from valiqor.trace import configure

configure(
    api_key="your-api-key",
    project_name="my-app",
    app_name="chatbot",
    app_version="1.2.0",
    environment="production",
    trace_dir="valiqor_output/traces",
    backend_url="https://api.valiqor.com",
    auto_trace=True,
    local_export=True,
    debug=False,
)
```

| Parameter      | Type   | Default | Description                          |
| -------------- | ------ | ------- | ------------------------------------ |
| `api_key`      | `str`  | `None`  | Valiqor API key.                     |
| `project_name` | `str`  | `None`  | Project name.                        |
| `app_name`     | `str`  | `None`  | Application name for trace metadata. |
| `app_version`  | `str`  | `None`  | Application version.                 |
| `environment`  | `str`  | `None`  | Environment label.                   |
| `trace_dir`    | `str`  | `None`  | Local directory for trace export.    |
| `backend_url`  | `str`  | `None`  | Backend API URL.                     |
| `auto_trace`   | `bool` | `None`  | Enable/disable auto-tracing.         |
| `local_export` | `bool` | `None`  | Enable local file export.            |
| `debug`        | `bool` | `None`  | Enable debug logging.                |
| `export_mode`  | `str`  | `None`  | Export mode configuration.           |

***

## Decorators

### `@trace_workflow`

Create a trace for a workflow. Works as both a **context manager** and a **decorator**.

```python theme={"system"}
from valiqor.trace import trace_workflow
```

<CodeGroup>
  ```python As Decorator theme={"system"}
  @trace_workflow(name="qa_pipeline")
  def answer_question(question: str) -> str:
      context = retrieve_docs(question)
      return generate_answer(question, context)

  answer_question("What is RAG?")
  ```

  ```python As Context Manager theme={"system"}
  with trace_workflow(name="qa_pipeline") as tw:
      context = retrieve_docs("What is RAG?")
      answer = generate_answer("What is RAG?", context)
  ```
</CodeGroup>

| Parameter    | Type   | Default      | Description                                 |
| ------------ | ------ | ------------ | ------------------------------------------- |
| `name`       | `str`  | `"workflow"` | Name for this trace/workflow.               |
| `input_data` | `Dict` | `None`       | Optional input data to attach to the trace. |

***

### `@trace_function`

Create a span under the active trace for a function call.

```python theme={"system"}
from valiqor.trace import trace_function

@trace_function(name="retrieve_docs")
def retrieve_docs(query: str) -> List[str]:
    return vector_db.search(query)
```

| Parameter        | Type   | Default | Description                                  |
| ---------------- | ------ | ------- | -------------------------------------------- |
| `name`           | `str`  | `None`  | Span name. Defaults to the function name.    |
| `input_fields`   | `List` | `None`  | Which function arguments to capture.         |
| `capture_input`  | `bool` | `True`  | Whether to capture function input arguments. |
| `capture_output` | `bool` | `True`  | Whether to capture function return value.    |

***

## Conversation Tracking

For multi-turn conversational agents, group multiple interactions into a single trace:

```python theme={"system"}
from valiqor.trace import start_conversation_trace, end_conversation_trace

# Start a conversation trace
trace_id = start_conversation_trace(name="support_chat")

# ... handle multiple user turns ...

# End and finalize the conversation trace
end_conversation_trace()
```

***

## `TracerV2` — Manual Tracing

For full control over trace and span lifecycle:

```python theme={"system"}
from valiqor.trace import TracerV2
```

### Constructor

```python theme={"system"}
TracerV2(
    app: Optional[Dict[str, str]] = None,
    exporters=None,
    ring_size: int = 200,
    trace_dir: str = "valiqor_output/traces",
    backend_url: str = None,
    api_key: str = None,
    project_name: str = None,
    environment: str = None,
)
```

| Parameter      | Type             | Default                   | Description                                                |
| -------------- | ---------------- | ------------------------- | ---------------------------------------------------------- |
| `app`          | `Dict[str, str]` | —                         | App metadata, e.g. `{"name": "my-app", "version": "1.0"}`. |
| `exporters`    | `list`           | `None`                    | List of exporter instances.                                |
| `ring_size`    | `int`            | `200`                     | Max events in the ring buffer.                             |
| `trace_dir`    | `str`            | `"valiqor_output/traces"` | Local output directory.                                    |
| `backend_url`  | `str`            | `None`                    | Backend URL for cloud export.                              |
| `api_key`      | `str`            | `None`                    | API key for cloud export.                                  |
| `project_name` | `str`            | `None`                    | Project name.                                              |

### Trace Lifecycle

```python theme={"system"}
# Start a trace
trace_id = tracer.start_trace(
    name="qa_pipeline",
    input_state={"question": "What is RAG?"},
    user_id="user-123",
    session_id="session-456"
)

# ... do work with spans ...

# End the trace
result = tracer.end_trace(output_state={"answer": "RAG is..."})
```

### Span Lifecycle

```python theme={"system"}
# Start a span
span = tracer.start_span(
    name="retrieve_documents",
    stage=ValiqorStage.RETRIEVAL,
    span_kind=ValiqorSpanKind.RETRIEVER,
    attributes={"query": "What is RAG?"}
)

# Do work...

# Finish the span
tracer.finish_span(span, status="success")
```

### Message Logging

```python theme={"system"}
tracer.add_message({"role": "user", "content": "What is RAG?"})
tracer.add_message({"role": "assistant", "content": "RAG stands for..."})
```

***

## RAG-Specific Methods

`TracerV2` provides specialized methods for tracing RAG pipelines:

### `track_retrieval()`

Track a retrieval step with document hits.

```python theme={"system"}
from valiqor.trace import DocumentHit

span = tracer.start_retrieval_span("vectordb", "What is RAG?")
retrieval_info = tracer.track_retrieval(
    span=span,
    retriever="vectordb",
    query="What is RAG?",
    hits=[
        DocumentHit(doc_id="doc-1", rank=1, score=0.95, snippet_preview="RAG is..."),
        DocumentHit(doc_id="doc-2", rank=2, score=0.87, snippet_preview="Retrieval...")
    ],
    embedding_model="text-embedding-3-small",
    top_k=5,
    latency_ms=45.2
)
```

### `track_generation()`

Track a generation step.

```python theme={"system"}
from valiqor.trace import Citation

span = tracer.start_generation_span("gpt-4o")
gen_info = tracer.track_generation(
    span=span,
    answer="RAG stands for Retrieval-Augmented Generation...",
    model_used="gpt-4o",
    citations=[Citation(doc_id="doc-1", confidence=0.95)],
    latency_ms=1200.0
)
```

### `track_rag_pipeline()`

Track the entire RAG pipeline in one call.

```python theme={"system"}
span = tracer.start_rag_pipeline_span(query="What is RAG?")
retrieval_info, gen_info = tracer.track_rag_pipeline(
    span=span,
    query="What is RAG?",
    retrieval_results=[DocumentHit(doc_id="doc-1", rank=1, score=0.95)],
    answer="RAG stands for...",
    retriever_type="vectordb",
    generation_model="gpt-4o"
)
```

***

## Constants

### `ValiqorStage`

Pipeline stage labels for spans:

| Constant         | Value              |
| ---------------- | ------------------ |
| `RETRIEVAL`      | `"retrieval"`      |
| `EVALUATION`     | `"evaluation"`     |
| `SYNTHESIS`      | `"synthesis"`      |
| `ROUTING`        | `"routing"`        |
| `ORCHESTRATION`  | `"orchestration"`  |
| `LLM_CALL`       | `"llm_call"`       |
| `TOOL_CALL`      | `"tool_call"`      |
| `EMBEDDING`      | `"embedding"`      |
| `RERANKING`      | `"reranking"`      |
| `PREPROCESSING`  | `"preprocessing"`  |
| `POSTPROCESSING` | `"postprocessing"` |
| `UNKNOWN`        | `"unknown"`        |

### `ValiqorSpanKind`

Span kind classification:

| Constant        | Value             |
| --------------- | ----------------- |
| `WORKFLOW_NODE` | `"workflow_node"` |
| `LLM_CALL`      | `"llm_call"`      |
| `RETRIEVER`     | `"retriever"`     |
| `TOOL`          | `"tool"`          |
| `EVAL`          | `"eval"`          |
| `EMBEDDING`     | `"embedding"`     |
| `SYSTEM`        | `"system"`        |
| `UNKNOWN`       | `"unknown"`       |

***

## Exporters

### `ConsoleExporter`

Print trace events to the console. Useful for development.

```python theme={"system"}
from valiqor.trace import ConsoleExporter

exporter = ConsoleExporter(verbose=True)
```

### `FileExporter`

Write trace events to local JSON files.

```python theme={"system"}
from valiqor.trace import FileExporter

exporter = FileExporter(trace_dir="valiqor_output/traces")
```

### `APIExporter`

Upload trace events to the Valiqor backend.

```python theme={"system"}
from valiqor.trace import APIExporter

exporter = APIExporter(
    api_url="https://api.valiqor.com",
    api_key="your-api-key",
)
```

***

## Related

* [Tracing Workflow](/workflows/tracing) — Step-by-step tracing guide
* [Traces & Spans](/concepts/traces-and-spans) — Conceptual overview
* [TraceQueryClient](/sdk/trace-query-client) — Query uploaded traces
* [Integrations](/integrations/openai) — Provider-specific auto-instrumentation
* [Models Reference](/sdk/models) — `DocumentHit`, `RetrievalInfo`, `Citation`, `GenerationInfo`