Skip to main content

​
What is a Trace?

A trace represents a single end-to-end operation in your AI pipeline. Each trace captures:
  • Inputs and outputs at each stage
  • State that existed at inference time (documents, config)
  • Timing and metadata
trace = artanis.trace("generate-report")

​
Naming Traces

The trace name should describe what the operation does, not how.
​
Good names
examples
  • "answer-question" - "classify-page" - "generate-summary"
​
Bad names
examples
  • "llm-call-1" - "step-2" - "function-x"

​
Creating a Trace

# Basic trace
trace = artanis.trace("operation-name")

# With metadata
trace = artanis.trace(
    "operation-name",
    metadata={
        "user_id": "user-123",
        "session_id": "session-456",
    }
)
Metadata is searchable in the Artanis dashboard, making it easy to filter traces by user, session, or other dimensions.

​
Recording Data

Use for user questions, prompts, and model parameters.
trace.input(question="What is X?")
trace.input(prompt=final_prompt, model="gpt-5.1")
Use for LLM responses and classification results.
trace.output(response)
trace.output({"answer": response, "confidence": 0.95})
Use for document IDs, config, and guidelines that existed at runtime.
trace.state("config", {"model": "gpt-5.1", "guidelines": text})
trace.state("documents", [doc.id for doc in corpus])

​
Basic Example

from artanis import Artanis

artanis = Artanis(api_key="sk_...")

# Create a trace
trace = artanis.trace("answer-question")

# Record inputs
trace.input(question="What is X?")

# Process
response = llm.generate(prompt)

# Record output
trace.output(response)

​
Multi-Stage Pipeline

For complex pipelines with multiple steps: 
trace = artanis.trace("rag-answer")

# Capture document corpus state
trace.state("corpus", [doc.id for doc in corpus])

# Retrieve chunks
chunks = retriever.search(question)
trace.state("chunks", [c.id for c in chunks])

# Generate response
prompt = build_prompt(question, chunks)
trace.input(prompt=prompt, model="gpt-5.1")
response = llm.generate(prompt)
trace.output(response)

​
Error Handling

Capture errors when operations fail: 
trace = artanis.trace("risky-operation")

try:
    trace.input(data=input_data)
    result = process(input_data)
    trace.output(result)
except ValidationError as e:
    trace.output({"error": "validation_failed", "details": str(e)})
    raise

​
Getting the Trace ID

The trace ID is useful for linking user feedback: 
trace_id = trace.id  # "trace_abc123..."

# Return to frontend for feedback linking
return {"answer": response, "trace_id": trace_id}
Learn how to link feedback to traces in the Feedback Integration guide.

​
Next Steps

Recording Data

Full API reference for all trace methods

Fire-and-Forget

Understand async tracing behavior