Configure Sampling

Learn how to configure sampling in your app using the Sentry Python SDK.

If you find that Sentry's tracing functionality is generating too much data, for example, if you notice your spans quota is quickly being exhausted, you can choose to sample your traces.

Effective sampling is key to getting the most value from Sentry's performance monitoring while minimizing overhead. The Python SDK provides two ways to control the sampling rate. You can review the options and examples below.

This page covers both transaction mode (default) and stream mode. See Streamed Spans to learn more.

traces_sample_rate is a floating-point value between 0.0 and 1.0, inclusive, which controls the probability with which each transaction (or service spans in stream mode) will be sampled. This works the same way in both transaction mode and stream mode:

Copied

sentry_sdk.init(
    # ...

    # Set traces_sample_rate to 1.0 to capture 100%
    # of transactions for tracing.
    # We recommend adjusting this value in production.
    traces_sample_rate=1.0,
)

sentry_sdk.init(
    # ...

    # Set traces_sample_rate to 1.0 to capture 100%
    # of transactions for tracing.
    # We recommend adjusting this value in production.
    traces_sample_rate=1.0,
)

With traces_sample_rate set to 0.25, each transaction/service span in your application is randomly sampled with a probability of 0.25, so you can expect that one in every four transactions/service spans will be sent to Sentry.

For more granular control, you can provide a traces_sampler function. This approach allows you to:

Apply different sampling rates to different types of transactions/service spans
Filter out specific transactions/service spans entirely
Make sampling decisions based on transaction/service span data
Control the inheritance of sampling decisions in distributed traces
Use custom attributes to modify sampling

It is strongly recommended when using a custom traces_sampler that you respect the parent sampling decision. This ensures your traces will be complete.

In distributed systems, implementing inheritance logic when trace information is propagated between services will ensure consistent sampling decisions across your entire distributed trace.

Copied

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Examine provided sampling context along with anything in the
    # global namespace to compute the sample rate for this transaction
    if "...":
        # These are important - take a big sample
        return 0.5
    elif "...":
        # These are less important - only take 1%
        return 0.01
    elif "...":
        # These aren't worth tracking - drop these transactions
        return 0

    # Default sample rate
    return 0.1

sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Examine provided sampling context along with anything in the
    # global namespace to compute the sample rate for this transaction
    if "...":
        # These are important - take a big sample
        return 0.5
    elif "...":
        # These are less important - only take 1%
        return 0.01
    elif "...":
        # These aren't worth tracking - drop these transactions
        return 0

    # Default sample rate
    return 0.1

sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Examine provided sampling context along with anything in the
    # global namespace to compute the sample rate for this span
    if "...":
        # These are important - take a big sample
        return 0.5
    elif "...":
        # These are less important - only take 1%
        return 0.01
    elif "...":
        # These aren't worth tracking - drop these spans
        return 0

    # Default sample rate
    return 0.1

sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
    trace_lifecycle="stream",
)

Traces Sampler Examples

Prioritizing Critical User Flows

Copied

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    transaction_ctx = sampling_context["transaction_context"]
    name = transaction_ctx["name"]
    op = transaction_ctx["op"]

    # Sample all checkout transactions
    if name and ('/checkout' in name or op == 'checkout'):
        return 1.0

    # Sample 50% of login transactions
    if name and ('/login' in name or op == 'login'):
        return 0.5

    # Sample 10% of everything else
    return 0.1

sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    transaction_ctx = sampling_context["transaction_context"]
    name = transaction_ctx["name"]
    op = transaction_ctx["op"]

    # Sample all checkout transactions
    if name and ('/checkout' in name or op == 'checkout'):
        return 1.0

    # Sample 50% of login transactions
    if name and ('/login' in name or op == 'login'):
        return 0.5

    # Sample 10% of everything else
    return 0.1

sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    span_ctx = sampling_context["transaction_context"]
    name = span_ctx["name"]
    op = span_ctx["op"]

    # Sample all checkout spans
    if name and ('/checkout' in name or op == 'checkout'):
        return 1.0

    # Sample 50% of login spans
    if name and ('/login' in name or op == 'login'):
        return 0.5

    # Sample 10% of everything else
    return 0.1

sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
    trace_lifecycle="stream",
)

Handling Different Environments and Error Rates

Copied

import os
import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    environment = os.environ.get("ENVIRONMENT", "development")

    # Sample all transactions in development
    if environment == "development":
        return 1.0

    # Sample more transactions if there are recent errors
    # Note: hasRecentErrors is a custom attribute that needs to be set
    if sampling_context.get("hasRecentErrors") is True:
        return 0.8

    # Sample based on environment
    if environment == "production":
        return 0.05  # 5% in production
    elif environment == "staging":
        return 0.2   # 20% in staging

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# Custom attributes need to be set on transaction start via
# the `custom_sampling_context` argument in order to be available
# in the traces_sampler
with sentry_sdk.start_transaction(
    name="GET /api/users",
    op="http.request",
    custom_sampling_context={"hasRecentErrors": True},
) as transaction:
    # your code here

import os
import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    environment = os.environ.get("ENVIRONMENT", "development")

    # Sample all transactions in development
    if environment == "development":
        return 1.0

    # Sample more transactions if there are recent errors
    # Note: hasRecentErrors is a custom attribute that needs to be set
    if sampling_context.get("hasRecentErrors") is True:
        return 0.8

    # Sample based on environment
    if environment == "production":
        return 0.05  # 5% in production
    elif environment == "staging":
        return 0.2   # 20% in staging

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# Custom attributes need to be set on transaction start via
# the `custom_sampling_context` argument in order to be available
# in the traces_sampler
with sentry_sdk.start_transaction(
    name="GET /api/users",
    op="http.request",
    custom_sampling_context={"hasRecentErrors": True},
) as transaction:
    # your code here

import os
import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    environment = os.environ.get("ENVIRONMENT", "development")

    # Sample all spans in development
    if environment == "development":
        return 1.0

    # Sample more spans if there are recent errors
    # Note: hasRecentErrors is a custom attribute that needs to be set
    if sampling_context.get("hasRecentErrors") is True:
        return 0.8

    # Sample based on environment
    if environment == "production":
        return 0.05  # 5% in production
    elif environment == "staging":
        return 0.2   # 20% in staging

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
    trace_lifecycle="stream",
)

# Custom attributes need to be set on the scope, after continue_trace
# (which resets the propagation context) and before start_span
# (which is when sampling happens), in order to be available
# in the traces_sampler
sentry_sdk.Scope.set_custom_sampling_context({"hasRecentErrors": True})
with sentry_sdk.traces.start_span(
    name="GET /api/users",
    attributes={"sentry.op": "http.request"},
) as span:
    # your code here

Controlling Sampling Based on User and Transaction Properties

Copied

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Always sample for premium users
    # Note: user.tier is a custom attribute that needs to be set
    if sampling_context.get("user", {}).get("tier") == "premium":
        return 1.0

    # Sample more transactions for users experiencing errors
    # Note: hasRecentErrors is a custom attribute
    if sampling_context.get("hasRecentErrors") is True:
        return 0.8

    # Sample less for high-volume, low-value paths
    name = sampling_context["transaction_context"]["name"]
    if name and name.startswith("/api/metrics"):
        return 0.01

    # Default sampling rate
    return 0.2

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# To set custom attributes for this example:
with sentry_sdk.start_transaction(
    name="GET /api/users",
    op="http.request",
    custom_sampling_context={"user": {"tier": "premium"}, "hasRecentErrors": True},
) as transaction:
    # Your code here

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Always sample for premium users
    # Note: user.tier is a custom attribute that needs to be set
    if sampling_context.get("user", {}).get("tier") == "premium":
        return 1.0

    # Sample more transactions for users experiencing errors
    # Note: hasRecentErrors is a custom attribute
    if sampling_context.get("hasRecentErrors") is True:
        return 0.8

    # Sample less for high-volume, low-value paths
    name = sampling_context["transaction_context"]["name"]
    if name and name.startswith("/api/metrics"):
        return 0.01

    # Default sampling rate
    return 0.2

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# To set custom attributes for this example:
with sentry_sdk.start_transaction(
    name="GET /api/users",
    op="http.request",
    custom_sampling_context={"user": {"tier": "premium"}, "hasRecentErrors": True},
) as transaction:
    # Your code here

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Always sample for premium users
    # Note: user.tier is a custom attribute that needs to be set
    if sampling_context.get("user", {}).get("tier") == "premium":
        return 1.0

    # Sample more spans for users experiencing errors
    # Note: hasRecentErrors is a custom attribute
    if sampling_context.get("hasRecentErrors") is True:
        return 0.8

    # Sample less for high-volume, low-value paths
    name = sampling_context["transaction_context"]["name"]
    if name and name.startswith("/api/metrics"):
        return 0.01

    # Default sampling rate
    return 0.2

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
    trace_lifecycle="stream",
)

# To set custom attributes for this example:
sentry_sdk.Scope.set_custom_sampling_context(
    {"user": {"tier": "premium"}, "hasRecentErrors": True}
)
with sentry_sdk.traces.start_span(
    name="GET /api/users",
    attributes={"sentry.op": "http.request"},
) as span:
    # Your code here

Complex Business Logic Sampling

Copied

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Always sample critical business operations
    # Note: op is an SDK-provided attribute
    transaction_ctx = sampling_context["transaction_context"]
    if transaction_ctx["op"] in ["payment.process", "order.create", "user.verify"]:
        return 1.0

    # Sample based on user segment
    # Note: user.segment is a custom attribute
    user_segment = sampling_context.get("user", {}).get("segment")
    if user_segment == "enterprise":
        return 0.8
    elif user_segment == "premium":
        return 0.5

    # Sample based on transaction value
    # Note: transaction.value is a custom attribute
    transaction_value = sampling_context.get("transaction", {}).get("value")
    if transaction_value is not None and transaction_value > 1000:  # High-value transactions
        return 0.7

    # Sample based on error rate in the service
    # Note: service.error_rate is a custom attribute
    error_rate = sampling_context.get("service", {}).get("error_rate")
    if error_rate is not None and error_rate > 0.05:  # Error rate above 5%
        return 0.9

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# To set custom attributes for this example:
with sentry_sdk.start_transaction(
    name="Process Payment",
    op="payment.process",
    custom_sampling_context={"user": {"segment": "enterprise"}, "transaction": {"value": 1500}, "service": {"error_rate": 0.03}},
) as transaction:
    # Your code here

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Always sample critical business operations
    # Note: op is an SDK-provided attribute
    transaction_ctx = sampling_context["transaction_context"]
    if transaction_ctx["op"] in ["payment.process", "order.create", "user.verify"]:
        return 1.0

    # Sample based on user segment
    # Note: user.segment is a custom attribute
    user_segment = sampling_context.get("user", {}).get("segment")
    if user_segment == "enterprise":
        return 0.8
    elif user_segment == "premium":
        return 0.5

    # Sample based on transaction value
    # Note: transaction.value is a custom attribute
    transaction_value = sampling_context.get("transaction", {}).get("value")
    if transaction_value is not None and transaction_value > 1000:  # High-value transactions
        return 0.7

    # Sample based on error rate in the service
    # Note: service.error_rate is a custom attribute
    error_rate = sampling_context.get("service", {}).get("error_rate")
    if error_rate is not None and error_rate > 0.05:  # Error rate above 5%
        return 0.9

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# To set custom attributes for this example:
with sentry_sdk.start_transaction(
    name="Process Payment",
    op="payment.process",
    custom_sampling_context={"user": {"segment": "enterprise"}, "transaction": {"value": 1500}, "service": {"error_rate": 0.03}},
) as transaction:
    # Your code here

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Always sample critical business operations
    # Note: sentry.op is an SDK-provided attribute
    span_ctx = sampling_context["transaction_context"]
    if span_ctx["op"] in ["payment.process", "order.create", "user.verify"]:
        return 1.0

    # Sample based on user segment
    # Note: user.segment is a custom attribute
    user_segment = sampling_context.get("user", {}).get("segment")
    if user_segment == "enterprise":
        return 0.8
    elif user_segment == "premium":
        return 0.5

    # Sample based on transaction value
    # Note: transaction.value is a custom attribute
    transaction_value = sampling_context.get("transaction", {}).get("value")
    if transaction_value is not None and transaction_value > 1000:  # High-value transactions
        return 0.7

    # Sample based on error rate in the service
    # Note: service.error_rate is a custom attribute
    error_rate = sampling_context.get("service", {}).get("error_rate")
    if error_rate is not None and error_rate > 0.05:  # Error rate above 5%
        return 0.9

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
    trace_lifecycle="stream",
)

# To set custom attributes for this example:
sentry_sdk.Scope.set_custom_sampling_context(
    {"user": {"segment": "enterprise"}, "transaction": {"value": 1500}, "service": {"error_rate": 0.03}}
)
with sentry_sdk.traces.start_span(
    name="Process Payment",
    attributes={"sentry.op": "payment.process"},
) as span:
    # Your code here

Performance-Based Sampling

Copied

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Sample more transactions with high memory usage
    # Note: memory_usage_mb is a custom attribute
    memory_usage = sampling_context.get("memory_usage_mb")
    if memory_usage is not None and memory_usage > 500:
        return 0.8

    # Sample more transactions with high CPU usage
    # Note: cpu_percent is a custom attribute
    cpu_percent = sampling_context.get("cpu_percent")
    if cpu_percent is not None and cpu_percent > 80:
        return 0.8

    # Sample more transactions with high database load
    # Note: db_connections is a custom attribute
    db_connections = sampling_context.get("db_connections")
    if db_connections is not None and db_connections > 100:
        return 0.7

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# To set custom attributes for this example:
with sentry_sdk.start_transaction(
    name="Process Data",
    op="data.process",
    custom_sampling_context={"memory_usage_mb": 600, "cpu_percent": 85, "db_connections": 120},
) as transaction:
    # Your code here

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Sample more transactions with high memory usage
    # Note: memory_usage_mb is a custom attribute
    memory_usage = sampling_context.get("memory_usage_mb")
    if memory_usage is not None and memory_usage > 500:
        return 0.8

    # Sample more transactions with high CPU usage
    # Note: cpu_percent is a custom attribute
    cpu_percent = sampling_context.get("cpu_percent")
    if cpu_percent is not None and cpu_percent > 80:
        return 0.8

    # Sample more transactions with high database load
    # Note: db_connections is a custom attribute
    db_connections = sampling_context.get("db_connections")
    if db_connections is not None and db_connections > 100:
        return 0.7

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
)

# To set custom attributes for this example:
with sentry_sdk.start_transaction(
    name="Process Data",
    op="data.process",
    custom_sampling_context={"memory_usage_mb": 600, "cpu_percent": 85, "db_connections": 120},
) as transaction:
    # Your code here

import sentry_sdk
from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    # Use the parent sampling decision if we have an incoming trace.
    # Note: we strongly recommend respecting the parent sampling decision,
    # as this ensures your traces will be complete!
    parent_sampling_decision = sampling_context["parent_sampled"]
    if parent_sampling_decision is not None:
        return float(parent_sampling_decision)

    # Sample more spans with high memory usage
    # Note: memory_usage_mb is a custom attribute
    memory_usage = sampling_context.get("memory_usage_mb")
    if memory_usage is not None and memory_usage > 500:
        return 0.8

    # Sample more spans with high CPU usage
    # Note: cpu_percent is a custom attribute
    cpu_percent = sampling_context.get("cpu_percent")
    if cpu_percent is not None and cpu_percent > 80:
        return 0.8

    # Sample more spans with high database load
    # Note: db_connections is a custom attribute
    db_connections = sampling_context.get("db_connections")
    if db_connections is not None and db_connections > 100:
        return 0.7

    # Default sampling rate
    return 0.1

# Initialize the SDK with the sampling function
sentry_sdk.init(
    # ...
    traces_sampler=traces_sampler,
    trace_lifecycle="stream",
)

# To set custom attributes for this example:
sentry_sdk.Scope.set_custom_sampling_context(
    {"memory_usage_mb": 600, "cpu_percent": 85, "db_connections": 120}
)
with sentry_sdk.traces.start_span(
    name="Process Data",
    attributes={"sentry.op": "data.process"},
) as span:
    # Your code here

When the traces_sampler function is called, the Sentry SDK passes a sampling_context object with information from the relevant span to help make sampling decisions:

Copied

{
    "transaction_context": {
        "name": str,  # transaction title at creation time (SDK-provided)
        "op": str,  # short description of transaction type (SDK-provided)
        "data": Optional[dict[str, Any]]
    },
    "parent_sampled": Optional[bool],  # whether the parent transaction was sampled (SDK-provided)
    ...  # additional custom data for sampling provided via custom_sampling_context
}

{
    "transaction_context": {
        "name": str,  # transaction title at creation time (SDK-provided)
        "op": str,  # short description of transaction type (SDK-provided)
        "data": Optional[dict[str, Any]]
    },
    "parent_sampled": Optional[bool],  # whether the parent transaction was sampled (SDK-provided)
    ...  # additional custom data for sampling provided via custom_sampling_context
}

Copied

{
    "transaction_context": {
        "name": str,  # span title at creation time (SDK-provided)
        "op": str,  # short description of span type (SDK-provided)
        "data": dict[str, Any]  # attributes set at span-creation time (SDK- and user-provided)
    },
    "parent_sampled": Optional[bool],  # whether the parent span was sampled (SDK-provided)
    ...  # additional custom key-value pairs for sampling set via custom sampling context
}

{
    "transaction_context": {
        "name": str,  # span title at creation time (SDK-provided)
        "op": str,  # short description of span type (SDK-provided)
        "data": dict[str, Any]  # attributes set at span-creation time (SDK- and user-provided)
    },
    "parent_sampled": Optional[bool],  # whether the parent span was sampled (SDK-provided)
    ...  # additional custom key-value pairs for sampling set via custom sampling context
}

The sampling context contains both SDK-provided attributes and custom attributes:

SDK-Provided Attributes:

transaction_context.name: The name of the transaction
transaction_context.op: The operation type
parent_sampled: Whether the parent transaction was sampled

Custom Attributes:

Any data you add to the custom_sampling_context parameter in start_transaction. Use this for data that you want to use for sampling decisions but don't want to include in the transaction data that gets sent to Sentry. Read more about sampling context here.

SDK-Provided Attributes:

transaction_context.name: The name of the span
transaction_context.data: Attributes set on the span at creation time, including sentry.op
parent_sampled: Whether the parent span was sampled

Custom Attributes:

Any data you add via sentry_sdk.Scope.set_custom_sampling_context(), called after continue_trace and before start_span. Use this for data that you want to use for sampling decisions but don't want to include in the span data that gets sent to Sentry. Read more about sampling context here.

When multiple sampling mechanisms could apply, Sentry follows this order of precedence:

If a sampling decision is passed to start_transaction, that decision is used.
If traces_sampler is defined, its decision is used. Although the traces_sampler can override the parent sampling decision, most users will want to ensure their traces_sampler respects the parent sampling decision.
If no traces_sampler is defined, but there is a parent sampling decision from an incoming distributed trace, we use the parent sampling decision.
If neither of the above, traces_sample_rate is used.
If none of the above are set, no transactions are sampled. This is equivalent to setting traces_sample_rate=0.0.

If traces_sampler is defined, its decision is used. Although the traces_sampler can override the parent sampling decision, most users will want to ensure their traces_sampler respects the parent sampling decision.
If no traces_sampler is defined, but there is a parent sampling decision from an incoming distributed trace, we use the parent sampling decision.
If neither of the above, traces_sample_rate is used.
If none of the above are set, no spans are sampled. This is equivalent to setting traces_sample_rate=0.0.

Sampling decisions are made when spans are created. Child spans inherit the sampling decision of their parent span unless filtered by ignore_spans.

Sentry uses a "head-based" sampling approach:

A sampling decision is made in the originating service (the "head")
This decision is propagated to all downstream services

The two key headers are:

sentry-trace: Contains trace ID, span ID, and sampling decision
baggage: Contains additional trace metadata including sample rate

The Sentry Python SDK automatically attaches these headers to outgoing HTTP requests when using auto-instrumentation with libraries like requests, urllib3, or httpx. For other communication channels, you can manually propagate trace information. Learn more about customizing tracing in custom trace propagation.

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").

How to contribute | Edit this page | Create a docs issue | Get support