Set up tracing

​

Installation

Install the tracely package from PyPi:

pip install tracely

​

Initialize tracing

To start sending traces, use init_tracing:

from tracely import init_tracing

init_tracing(
   address="https://app.evidently.cloud/",
   api_key="YOUR_EVIDENTLY_TOKEN",
   project_id="YOUR_PROJECT_ID",
   export_name="YOUR_TRACING_DATASET_NAME",
   )

You can also set parameters using environment variables with the specified names.

​

init_tracing() Function Arguments

​

Tracing dataset ID

To get the export_id of the tracing dataset, run:

from tracely import get_info

get_info()

You can use the export_id as a dataset id for download. See datasets API.

​

Decorator

Once Tracely is initialized, you can decorate your functions with trace_event to start collecting traces for a specific function:

from tracely import init_tracing
from tracely import trace_event

@trace_event()
def process_request(question: str, session_id: str):
    # do work
    return "work done"

You can also specify which function arguments should be included in the trace.

Example 1. To log all arguments of the function:

@trace_event()

Example 2. To log only input arguments of the function:

@trace_event(track_args=[])

Example 3. To log only “arg1” and “arg2”:

@trace_event(track_args=["arg1", "arg2"])

​

trace_event Decorator Arguments

​

Nested events (Spans)

Many LLM workflows involve multiple steps — such as retrieval followed by generation, or extraction followed by summarization. In these cases, it’s useful to trace all steps as part of a single parent trace, with each step recorded as a nested child span.

You can trace multi-step workflows using the @trace_event decorator and nesting the functions. If a traced function is called inside another traced function, it will automatically appear as a nested child span, as long as it’s executed in the same call context (same thread).

For example:

@trace_event(span_name="extraction")
def extract_info(document):
    …

@trace_event(span_name="summarization")
def summarize_info(document):
    …

@trace_event(span_name="document_processing")
def process_document(document):
    extract_output = extract_info(document)
    summary_output = summarize_info(document)
    return {
        "document": document,
        "extraction_output": extract_output,
        "summary_output": summary_output
    }

This results in the following trace structure:

document_processing
├── extraction
└── summarization

​

Context manager

To create a trace event without using a decorator (e.g., for a specific piece of code), you can use the context manager:

import uuid

from tracely import init_tracing
from tracely import create_trace_event

init_tracing()

session_id = str(uuid.uuid4())

with create_trace_event("external_span", session_id=session_id) as event:
    event.set_attribute("my-attribute", "value")
    # do work
    event.set_result({"data": "data"})

You can also trace multi-step workflows using context blocks. This gives you fine-grained control — useful when tracing inline code or scripts. For example, you can nest multiple create_trace_event() calls inline inside the same function, using with blocks.

def process_document(document):
    with create_trace_event("document_processing", document=document):
        with create_trace_event("extraction"):
            ...
        with create_trace_event("summarization"):
            ...

​

create_trace_event Function Arguments

​

event Object Methods

​

Sessions

If your trace events are created in separate functions or threads you can also pass a shared session_id. In this case traces will be separate but you can view the session in the UI to join them together - e.g. to read the chat conversation.

See the example above the “Context Manager” session.

​

Add event attributes

If you want to add a new attribute to an active event span, you can use get_current_span() to get access to the current span:

import uuid

from tracely import init_tracing
from tracely import create_trace_event
from tracely import get_current_span

init_tracing()

session_id = str(uuid.uuid4())

with create_trace_event("external_span", session_id=session_id):
    span = get_current_span()
    span.set_attribute("my-attribute", "value")
    # do work
    span.set_result({"data": "data"})

​

get_current_span() Object Methods

​

Connecting event into a trace

Sometimes events happen across different systems, but it’s helpful to link them all into a single trace. You can do this using tracely.bind_to_trace:

@tracely.trace_event()
def process_request(question: str, session_id: str):
    # do work
    return "work done"

# trace id is unique 128-bit integer representing single trace
trace_id = 1234

with tracely.bind_to_trace(trace_id):
    process_request(...)

In this example, instead of creating a new trace ID for each event, all events will be attached to the existing trace with the given trace_id.