[Python] Manual instrumentation for Cache Module

docs/platforms/python/performance/instrumentation/custom-instrumentation/cache-module.mdx

@@ -0,0 +1,101 @@
+---
+title: Instrument Caches
+sidebar_order: 1000
+description: "Learn how to manually instrument your code to use Sentrys 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](https://sentry.io/orgredirect/organizations/:orgslug/performance/cache/) that can be auto-instrumented for popular Python caching setups (like <PlatformLink to="/integrations/django/">Django</PlatformLink>, <PlatformLink to="/integrations/redis/">Redis</PlatformLink>, 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 <PlatformLink to="/performance/">Performance Monitoring</PlatformLink> for more information.
+
+For detailed information about which data can be set, see the [Cache Module Developer Specification](https://develop.sentry.dev/sdk/performance/modules/cache/).
+
+## Manual Instrumentation
+
+If you're using anything other than <PlatformLink to="/integrations/django/">Django</PlatformLink>, <PlatformLink to="/integrations/redis/">Redis</PlatformLink>,  memcached (comming soon), you'll need to manually instrument the [Cache Module]((https://sentry.io/orgredirect/organizations/:orgslug/performance/cache/)) by following the steps below.
+
+### Initialize Sentry
+
+<PlatformContent includePath="getting-started-config" />
+
+### 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_item`.
+4. Set `cache.item_size` to an integer representing the size of the cached item.
+
+(The steps described above are documented in the snippet.)
+
+```python
+import my_caching
+import sentry_sdk
+
+key = "myCacheKey123"
+value = "The value I want to cache."
+
+with sentry_sdk.start_span(op="cache.set_item") 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_item`.
+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.)
+
+```python
+import my_caching
+import sentry_sdk
+
+key = "myCacheKey123"
+value = None
+
+with sentry_sdk.start_span(op="cache.get_item") 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](https://sentry.io/orgredirect/organizations/:orgslug/performance/cache/) to see how your cache is performing.

docs/platforms/python/performance/instrumentation/custom-instrumentation.mdx → docs/platforms/python/performance/instrumentation/custom-instrumentation/index.mdx

@@ -1,6 +1,5 @@
 ---
 title: Custom Instrumentation
-sidebar_order: 20
 description: "Learn how to capture performance data on any action in your app."
 ---
 

docs/platforms/python/performance/instrumentation/requests-module.mdx → docs/platforms/python/performance/instrumentation/custom-instrumentation/requests-module.mdx

@@ -1,6 +1,6 @@
 ---
-title: Custom Instrumentation for Requests Module
-sidebar_order: 9999
+title: Instrument HTTP Requests
+sidebar_order: 2000
 description: "Learn how to manually instrument your code to use Sentry's Requests module."
 ---
 
@@ -14,7 +14,7 @@ For detailed information about which data can be set, see the [Requests Module d
 
 <PlatformContent includePath="getting-started-config" />
 
-### Wrap The HTTP Requests in a Span
+### Wrap HTTP Requests in a Span
 
 NOTE: Refer to [HTTP Span Data Conventions](https://develop.sentry.dev/sdk/performance/span-data-conventions/#http) for a full list of the span data attributes.