Span Lifecycle

Learn how to add attributes to spans in Sentry to monitor performance and debug applications.

To add custom performance data to your application, you need to add custom instrumentation in the form of spans. Spans are a way to measure the time it takes for a specific action to occur. For example, you can create a span to measure the time it takes for a function to execute.

There are two main approaches to creating spans in Python:

In Python, spans are typically created using a context manager, which automatically manages the span's lifecycle. When you create a span using a context manager, the span automatically starts when entering the context and ends when exiting it. This is the recommended approach for most scenarios.

Copied
import sentry_sdk

# Start a span for a task
with sentry_sdk.start_span(op="task", name="Create User"):
    # Your code here
    # The span will automatically end when exiting this block
    user = create_user(email="user@example.com")
    send_welcome_email(user)
    # The span automatically ends here when the 'with' block exits

You can call the context manager's __enter__ and __exit__ methods to more explicitly control the span's lifecycle.

When you create a span, it becomes the child of the current active span. This allows you to build a hierarchy of spans that represent the execution path of your application:

Copied
import sentry_sdk

with sentry_sdk.start_span(op="process", name="Process Data"):
    # This code is tracked in the "Process Data" span
    
    with sentry_sdk.start_span(op="task", name="Validate Input"):
        # This is now a child span of "Process Data"
        validate_data()
    
    with sentry_sdk.start_span(op="task", name="Transform Data"):
        # Another child span
        transform_data()

The following options can be used when creating spans:

OptionTypeDescription
opstringThe operation of the span.
namestringThe name of the span.
start_timestampdatetime/floatThe start time of the span.

For most scenarios, we recommend using the context manager approach with sentry_sdk.start_span(). This creates a new span that automatically starts when entering the context and ends when exiting it.

Copied
import sentry_sdk

with sentry_sdk.start_span(op="db", name="Query Users") as span:
    # Perform a database query
    users = db.query("SELECT * FROM users")
    
    # You can set data on the span
    span.set_data("user_count", len(users))

The context manager also correctly handles exceptions, marking the span as failed if an exception occurs:

Copied
import sentry_sdk

try:
    with sentry_sdk.start_span(op="http", name="Call External API"):
        # If this raises an exception, the span will be marked as failed
        response = requests.get("https://api.example.com/data")
        response.raise_for_status()
except Exception:
    # The span is already marked as failed and has ended
    pass

You can access the currently active span using sentry_sdk.get_current_span():

Copied
import sentry_sdk

# Get the current active span
current_span = sentry_sdk.get_current_span()
if current_span:
    current_span.set_data("key", "value")

Transactions are a special type of span that represent a complete operation in your application, such as a web request. You can create transactions explicitly:

Copied
import sentry_sdk

with sentry_sdk.start_transaction(name="Background Task", op="task") as transaction:
    # Your code here
    
    # You can add child spans to the transaction
    with sentry_sdk.start_span(op="subtask", name="Data Processing"):
        # Process data
        pass

Span attributes customize information you can get through tracing. This information can be found in the traces views in Sentry, once you drill into a span. You can capture additional context with span attributes. These can be key-value pairs of various Python types.

Copied
import sentry_sdk

with sentry_sdk.start_span(op="db", name="Query Users") as span:
    # Execute the query
    users = db.query("SELECT * FROM users WHERE active = true")
    
    # You can add more data during execution
    span.set_data("result_count", len(users))

You can also add attributes to an existing span:

Copied
import sentry_sdk

# Get the current span
span = sentry_sdk.get_current_span()
if span:
    # Set individual data points
    span.set_data("user_id", user.id)
    span.set_data("request_size", len(request.body))

To add attributes to all spans, use the before_send_transaction callback:

Copied
import sentry_sdk

def before_send_transaction(event):
    # Add attributes to the root span (transaction)
    if "trace" in event.get("contexts", {}):
        if "data" not in event["contexts"]["trace"]:
            event["contexts"]["trace"]["data"] = {}
        
        event["contexts"]["trace"]["data"].update({
            "app_version": "1.2.3",
            "environment_region": "us-west-2"
        })
    
    # Add attributes to all child spans
    for span in event.get("spans", []):
        if "data" not in span:
            span["data"] = {}
        
        span["data"].update({
            "component_version": "2.0.0",
            "deployment_stage": "production"
        })
    
    return event

sentry_sdk.init(
    # Your other Sentry configuration options here
    before_send_transaction=before_send_transaction
)

Spans can have an operation associated with them, which helps Sentry understand the context of the span. For example, database related spans have the db operation, while HTTP requests use http.client.

Sentry maintains a list of well-known span operations that you should use when applicable:

Copied
import sentry_sdk

# HTTP client operation
with sentry_sdk.start_span(op="http.client", name="Fetch User Data"):
    response = requests.get("https://api.example.com/users")

# Database operation
with sentry_sdk.start_span(op="db", name="Save User"):
        db.execute(
        "INSERT INTO users (name, email) VALUES (%s, %s)", 
        (user.name, user.email),
    )

# File I/O operation
with sentry_sdk.start_span(op="file.read", name="Read Config"):
    with open("config.json", "r") as f:
        config = json.load(f)

You can update the status of a span to indicate whether it succeeded or failed:

Copied
import sentry_sdk

with sentry_sdk.start_span(op="task", name="Process Payment") as span:
    try:
        result = process_payment(payment_id)
        if result.success:
            # Mark the span as successful
            span.set_status("ok")
        else:
            # Mark the span as failed
            span.set_status("error")
            span.set_data("error_reason", result.error)
    except Exception:
        # Span will automatically be marked as failed when an exception occurs
        raise
Previous
Set Up Tracing
Next
Sending Span Metrics
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").