Instrument Caches

Learn how to manually instrument your code to use Sentry's 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-monitoring dashboard that can be auto-instrumented using Sentry's Redis integration (more coming soon).

If you're using anything other than Sentry's Redis integration, you'll need to manually instrument the Cache Module by following the steps below.

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.

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

Follow these custom instrumentation instructions to emit cache setting 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 Sentry.startSpan(...).
  3. Set the name to something descriptive like "Setting auth cache".
  4. Set op to cache.set.
  5. Set cache.key to a string array representing the key(s) you're setting.
  6. Optionally, you can set other attributes such as cache.item_size. (See Cache Module Span Data Conventions for more information.)

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

my-cache.js
Copied
const key = 'myCacheKey123';
const value = 'The value I want to cache.';

Sentry.startSpan(
  {
    name: 'Setting auth cache',
    attributes: {
      'cache.key': [key],
      'cache.item_size': JSON.stringify(value).length, // Warning: if value is very big this could use lots of memory
      'network.peer.address': 'cache.example.com/supercache',
      'network.peer.port': 9000,
    },
    op: 'cache.put',
  },
  span => {
    // Set a key in your caching using your custom caching solution
    my_caching.set(key, value);
  }
);

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

  1. Get the cached value from whatever cache library you happen to be using.
  2. Wrap the part of your application that fetches from the cache with Sentry.startSpan(...).
  3. Set the name to something descriptive like "Getting auth cache".
  4. Set op to cache.get.
  5. Set cache.key to a string array representing the key(s) you're setting.
  6. Set cache.hit to a boolean value representing whether the value was successfully fetched from the cache or not.
  7. Optionally, you can set other attributes such as cache.item_size. (See Cache Module Span Data Conventions for more information.) (The steps described above are also documented in the snippet.)
my-cache.js
Copied
const key = "myCacheKey123";

Sentry.startSpan(
  {
    name: "Getting auth cache",
    attributes: {
      "cache.key": [key],
      "network.peer.address": "cache.example.com/supercache",
      "network.peer.port": 9000,
    },
    op: "cache.get",
  },
  (span) => {
    // Set a key in your caching using your custom caching solution
    const value = my_caching.get(key);
    const cacheHit = Boolean(value);
    if (cacheHit) {
      span.setAttribute("cache.item_size", JSON.stringify(value).length, // Warning: if value is very big this could use lots of memory);
    }
    span.setAttribute("cache.hit", cacheHit);
  }
);

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

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