Tracer & Auto-Instrumentation

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:

Zero-config — import valiqor.auto and traces are captured automatically
Decorators — @trace_workflow and @trace_function for explicit control
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:

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:

from valiqor.trace import autolog

# Enable all supported providers
autolog()

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

`disable_autolog()`

Disable auto-instrumentation:

from valiqor.trace import disable_autolog

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

Provider-Specific Shortcuts

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:

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.

from valiqor.trace import trace_workflow

@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?")

with trace_workflow(name="qa_pipeline") as tw:
    context = retrieve_docs("What is RAG?")
    answer = generate_answer("What is RAG?", context)

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.

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:

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:

from valiqor.trace import TracerV2

Constructor

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

# 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

# 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

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.

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.

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.

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.

from valiqor.trace import ConsoleExporter

exporter = ConsoleExporter(verbose=True)

`FileExporter`

Write trace events to local JSON files.

from valiqor.trace import FileExporter

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

`APIExporter`

Upload trace events to the Valiqor backend.

from valiqor.trace import APIExporter

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

Tracing Workflow — Step-by-step tracing guide
Traces & Spans — Conceptual overview
TraceQueryClient — Query uploaded traces
Integrations — Provider-specific auto-instrumentation
Models Reference — DocumentHit, RetrievalInfo, Citation, GenerationInfo

Client

Modules

Utilities

Tracer & Auto-Instrumentation

Overview

Zero-Config Auto-Instrumentation

`autolog()` Function

`disable_autolog()`

Provider-Specific Shortcuts

`configure()` Function

Decorators

`@trace_workflow`

`@trace_function`

Conversation Tracking

`TracerV2` — Manual Tracing

Constructor

Trace Lifecycle

Span Lifecycle

Message Logging

RAG-Specific Methods

`track_retrieval()`

`track_generation()`

`track_rag_pipeline()`

Constants

`ValiqorStage`

`ValiqorSpanKind`

Exporters

`ConsoleExporter`

`FileExporter`

`APIExporter`

​Overview

​Zero-Config Auto-Instrumentation

​autolog() Function

​disable_autolog()

​Provider-Specific Shortcuts

​configure() Function

​Decorators

​@trace_workflow

​@trace_function

​Conversation Tracking

​TracerV2 — Manual Tracing

​Constructor

​Trace Lifecycle

​Span Lifecycle

​Message Logging

​RAG-Specific Methods

​track_retrieval()

​track_generation()

​track_rag_pipeline()

​Constants

​ValiqorStage

​ValiqorSpanKind

​Exporters

​ConsoleExporter

​FileExporter

​APIExporter

​Related

Overview

Zero-Config Auto-Instrumentation

`autolog()` Function

`disable_autolog()`

Provider-Specific Shortcuts

`configure()` Function

Decorators

`@trace_workflow`

`@trace_function`

Conversation Tracking

`TracerV2` — Manual Tracing

Constructor

Trace Lifecycle

Span Lifecycle

Message Logging

RAG-Specific Methods

`track_retrieval()`

`track_generation()`

`track_rag_pipeline()`

Constants

`ValiqorStage`

`ValiqorSpanKind`

Exporters

`ConsoleExporter`

`FileExporter`

`APIExporter`

Related