Moving and combining instrumentaiton section

Author: codyde

docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx

@@ -0,0 +1,132 @@
+---
+title: Instrument Caches
+sidebar_order: 1000
+description: "Learn how to manually instrument your code to use Sentry's Cache module."
+supported:
+  - javascript.node
+  - javascript.aws-lambda
+  - javascript.azure-functions
+  - javascript.connect
+  - javascript.express
+  - javascript.fastify
+  - javascript.gcp-functions
+  - javascript.hapi
+  - javascript.koa
+  - javascript.nestjs
+  - javascript.bun
+  - javascript.deno
+  - javascript.nextjs
+  - javascript.nuxt
+  - javascript.astro
+  - javascript.solidstart
+  - javascript.sveltekit
+  - javascript.remix
+  - javascript.cloudflare
+---
+
+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](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/) that can be auto-instrumented using Sentry's Redis integration (more coming soon).
+
+## Instrumentation with Redis Clients
+
+If you're using a Redis client like `ioredis` or `redis` to cache your data, it is necessary to specify the `cachePrefixes` within the `redisIntegration` options. This configuration allows Sentry to categorize accesses to keys with the defined prefixes as "cache operations".
+
+```javascript
+Sentry.init({
+  integrations: [
+    redisIntegration({
+      cachePrefixes: ["posts:", "authors:"],
+    }),
+  ],
+});
+```
+
+## Manual Instrumentation
+
+If you're using anything other than Sentry's Redis integration, you'll need to manually instrument the [Cache Module](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/) 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.
+
+<PlatformSection supported={["javascript.node", "javascript.deno", "javascript.bun"]}>
+
+Make sure that there's an active span before you create your cache spans. If you're using a web framework like Express, a span will be created for you automatically. See <PlatformLink to="/tracing/">Tracing</PlatformLink> for more information.
+
+</PlatformSection>
+
+For detailed information about which data can be set, see the [Cache Module Developer Specification](https://develop.sentry.dev/sdk/performance/modules/caches/).
+
+### Step 1: Add Span When Putting Data Into the Cache
+
+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](https://develop.sentry.dev/sdk/performance/modules/caches/#span-data) for more information.)
+
+(The steps described above are also documented in the snippet.)
+
+```javascript {filename: my-cache.js}
+const key = "myCacheKey123";
+const value = "The value I want to cache.";
+
+Sentry.startSpan(
+  {
+    name: key,
+    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);
+  }
+);
+```
+
+### Step 2: Add Span When Retrieving Data From the Cache
+
+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](https://develop.sentry.dev/sdk/performance/modules/caches/#span-data) for more information.)
+   (The steps described above are also documented in the snippet.)
+
+```javascript {filename: my-cache.js}
+const key = "myCacheKey123";
+
+Sentry.startSpan(
+  {
+    name: key,
+    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](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/) to see how your cache is performing.