Manual Instrumentation for Cache Module

A cache can be used to speed up data retrieval, thereby improving application performance. Because instead of getting data from a potentially slow data layer, your application will be getting data from memory (in a best case scenario). Caching can speed up read-heavy workloads for applications like Q&A portals, gaming, media sharing, and social networking.

Sentry offers a cache-monitring dashboard that can be auto-instrumented for popular Python caching setups (like Django, Redis, and memcached (coming soon).

If you're using a custom caching solution that doesn't have auto instrumentation, you can manually instrument it and use Sentry to get a look into how your caching solution is performing by following the setup instructions below.

To make it possible for Sentry to give you an overview of your cache performance, you'll need to create two spans - one indicating that something is being put into the cache, and a second one indicating that something is being fetched from the cache.

Make sure that there's a transaction running when you create the spans. If you're using a web framework those transactions will be created for you automatically. See Performance Monitoring for more information.

For detailed information about which data can be set, see the Cache Module Developer Specification.

Manual Instrumentation

If you're using anything other than Django, Redis, memcached (comming soon), you'll need to manually instrument the Cache Module by following the steps below.

Initialize Sentry

Once this is done, Sentry's Python SDK captures all unhandled exceptions and transactions.

import sentry_sdk

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",

    # Enable performance monitoring
    enable_tracing=True,
)

Add Span When Putting Data Into the Cache:

If the cache you’re using isn’t supported by auto instrumentation mentioned above, you can use the custom instrumentation instructions below to emit cache spans:

1. Set the cache value with whatever cache library you happen to be using.
2. Wrap the part of your application that uses the cached value with with sentry_sdk.start_span(...)
3. Set op to cache.set.
4. Set cache.item_size to an integer representing the size of the cached item.

(The steps described above are documented in the snippet.)

import my_caching
import sentry_sdk

key = "myCacheKey123"
value = "The value I want to cache."

with sentry_sdk.start_span(op="cache.set") as span:
    # Set a key in your caching using your custom caching solution
    my_caching.set(key, value)

    # Describe the cache server you are accessing
    span.set_data("network.peer.address", "cache.example.com/supercache")
    span.set_data("network.peer.port", 9000)

    # Add the key you want to set
    span.set_data("cache.key", key)

    # Add the size of the value you stored in the cache
    span.set_data("cache.item_size", len(value))  # Warning: if value is very big this could use lots of memory

Add Span When Retrieving Data From the Cache

If the cache you’re using isn’t supported by auto instrumentation mentioned above, you can use the custom instrumentation instructions below to emit cache spans:

1. Fetch the cached value from whatever cache library you happen to be using.
2. Wrap the part of your application that uses the cached value with with sentry_sdk.start_span(...)
3. Set op to cache.get.
4. Set cache.hit to a boolean value representing whether the value was successfully fetched from the cache or not.
5. Set cache.item_size to an integer representing the size of the cached item.

(The steps described above are documented in the snippet.)

import my_caching
import sentry_sdk

key = "myCacheKey123"
value = None

with sentry_sdk.start_span(op="cache.get") as span:
    # Get a key from your caching solution
    value = my_caching.get(key)

    # Describe the cache server you are accessing
    span.set_data("network.peer.address", "cache.example.com/supercache")
    span.set_data("network.peer.port", 9000)

    # Add the key you just retrieved from the cache
    span.set_data("cache.key", key)

    if value is not None:
        # If you retrieved a value, the cache was hit
        span.set_data("cache.hit", True)

        # Optionally also add the size of the value you retrieved
        span.set_data("cache.item_size", len(value))
    else
        # If you could not retrieve a value, it was a miss
        span.set_data("cache.hit", False)

You should now have the right spans in place. Head over to Cache dashboard to see how your cache is performing.