---
title: "Caches Module"
url: https://develop.sentry.dev/sdk/telemetry/traces/modules/caches/
---

# Caches Module

The SDK's caching integration is agnostic to the underlying engine used. In most cases, the SDK will instrument existing cache abstractions in certain frameworks or libraries.

## [Span conventions](https://develop.sentry.dev/sdk/telemetry/traces/modules/caches.md#span-conventions)

### [Span Operations](https://develop.sentry.dev/sdk/telemetry/traces/modules/caches.md#span-operations)

The span operation should reflect the specific cache method being called, using the format `cache.<methodName>` (e.g. `cache.get`, `cache.putIfAbsent`, `cache.removeAll`). The following are common examples:

| Span OP        | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `cache.get`    | A single item or multiple items are retrieved from the cache |
| `cache.put`    | A single item or multiple items are written to the cache     |
| `cache.remove` | A single item or multiple items are removed from the cache   |
| `cache.flush`  | The entire content of the cache is deleted                   |

### [Span Description](https://develop.sentry.dev/sdk/telemetry/traces/modules/caches.md#span-description)

The description of cache spans should be set to the cache key(s), separated by commas, e.g. `posts`, or `article1, article2`.

### [Span Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/caches.md#span-data)

| Data Key          | Type   | Description                                                                     | Conditions                                                                                                                                                                                                     |
| ----------------- | ------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cache.hit`       | bool   | cache hit or miss                                                               | required only on read-operations (`cache.get`)                                                                                                                                                                 |
| `cache.key`       | array  | the key(s) involved in the operation                                            | required only on operations that have a key                                                                                                                                                                    |
| `cache.operation` | string | the specific cache operation performed (e.g. `get`, `putIfAbsent`, `removeAll`) | optional; useful when the SDK uses granular span operations beyond the four base ops                                                                                                                           |
| `cache.write`     | bool   | whether the operation resulted in a write to the cache                          | required only on write-operations (`cache.put`, `cache.remove`, `cache.flush`); reflects the actual outcome for conditional operations (e.g. `putIfAbsent`, `replace`); always `true` for unconditional writes |

The following data attributes are only to be set if exposed by the instrumented cache abstraction or retrievable with minimal overhead.

| Data Key               | Type   | Description                                                | Conditions                         |
| ---------------------- | ------ | ---------------------------------------------------------- | ---------------------------------- |
| `cache.item_size`      | int    | the size of the item/items read/written/deleted in `bytes` | only on operations that have a key |
| `cache.success`        | bool   | the operation has succeeded or failed                      |                                    |
| `cache.ttl`            | int    | the time to life in `seconds`                              | only on operations that have a key |
| `network.peer.address` | string | The hostname of the cache instance                         |                                    |
| `network.peer.port`    | int    | the port used by the cache instance                        |                                    |

## [Instrumentation](https://develop.sentry.dev/sdk/telemetry/traces/modules/caches.md#instrumentation)

Once an application performs a caching operation, the SDK creates a new span based on the operation, wrapping any spans of the underlying engine as direct children.

**Example**

```bash
item = Cache::get('posts')
```

This should result in the following spans, assuming a cache hit with an underlying Redis instance being used.

```bash
<span op:"cache.get" description:"posts" cache.key:"posts" cache.hit=true>
	<span op:db.redis description:"GET posts"></span>
</span>
```

### [SDK Options](https://develop.sentry.dev/sdk/telemetry/traces/modules/caches.md#sdk-options)

If convenient, the SDK can optionally offer a `cache_prefixes` option, that wraps existing instrumentations into a cache span. This will likely only be useful if Redis is being used as a cache.

```bash
Sentry.init({
  integrations: [
    Sentry.redisIntegration({
	    cachePrefixes: ['posts:', 'authors:'],
    }),
  ],
})
```

In this example, all Redis queries involving keys that match `posts:*` and `authors:*` will be wrapped into `cache.*` span.