Quickstart: For a simple end-to-end example, check the Tutorial.

​
Installation

Install the tracely package from PyPi:

pip install tracely

​
Initialize tracing

You must first connect to Evidently Cloud and create a Project.

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.

​
init_tracing() Function Arguments

ParameterDescriptionEnvironment Variable
addressTrace collector address. Defaults to https://app.evidently.cloud/.EVIDENTLY_TRACE_COLLECTOR
api_keyEvidently Cloud API key.EVIDENTLY_TRACE_COLLECTOR_API_KEY
export_nameTracing dataset name. Traces with the same name are grouped into a single dataset.EVIDENTLY_TRACE_COLLECTOR_EXPORT_NAME
project_idDestination Project ID in Evidently Cloud.EVIDENTLY_TRACE_COLLECTOR_PROJECT_ID
exporter_typeTrace export protocol: grpc or http.-
as_globalRegisters the tracing provider (opentelemetry.trace.TracerProvider) globally (True) or use locally (False). Default: True.-

​
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

ParameterDescriptionDefault
span_name: Optional[str]The name of the span to send in the event.Function name
track_args: Optional[List[str]]A list of function arguments to include in the event.None (all arguments included)
ignore_args: Optional[List[str]]A list of function arguments to exclude, e.g., arguments that contain sensitive data.None (no arguments ignored)
track_output: Optional[bool]Indicates whether to track the function’s return value.True
parse_output: Optional[bool]Indicates whether the result should be parsed, e.g., dict, list, and tuple types will be split into separate fields.True

​
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"})

​
create_trace_event Function Arguments

ParameterDescriptionDefault
nameSpan name.-
parse_outputWhether to parse the result into separate fields for dict, list, or tuple types.True
paramsKey-value parameters to set as attributes.-

​
event Object Methods

MethodDescription
set_attributeSets a custom attribute for the event.
set_resultSets a result for the event. Only one result can be set per event.

​
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

MethodDescription
set_attributeAdds a new attribute to the active span.
set_resultSets a result field for the active span. (Has no effect in decorated functions that define return values).
OverviewOverview