feat(cachekitio): report L1 hit latency and add a telemetry off switch (LAB-12079)

README.md

@@ -128,6 +128,8 @@ def expensive_api_call(user_id: int):
 
 *cachekit.io is in closed beta — [request access](https://cachekit.io) to get started.*
 
+During the beta the backend reports hit counts and L1 hit latency to cachekit.io by default; `CACHEKIT_TELEMETRY=false` turns that off ([Telemetry](docs/backends/cachekitio.md#telemetry)).
+
 How fresh a cachekit.io read is, and how long a deleted project's data stays readable: [Consistency and Deletion](https://docs.cachekit.io/concepts/consistency/).
 
 </details>

docs/api-reference.md

@@ -193,6 +193,7 @@ def critical_business_logic():
 | `CACHEKIT_API_KEY` | **Yes** | — | API key (`ck_live_...`) for authentication |
 | `CACHEKIT_API_URL` | No | `https://api.cachekit.io` | API endpoint override |
 | `CACHEKIT_TIMEOUT` | No | `5.0` | HTTP request timeout in seconds |
+| `CACHEKIT_TELEMETRY` | No | unset (on) | `false` turns off the usage telemetry headers ([Telemetry](backends/cachekitio.md#telemetry)) |
 
 #### Usage
 

docs/backends/cachekitio.md

@@ -37,6 +37,7 @@ backend = CachekitIOBackend(
     api_key="ck_live_...",              # default: CACHEKIT_API_KEY
     api_url="https://api.cachekit.io",  # default: CACHEKIT_API_URL, then api.cachekit.io
     timeout=5.0,                        # default: CACHEKIT_TIMEOUT, then 5.0 seconds
+    telemetry=None,                     # False turns telemetry off; see Telemetry below
 )
 ```
 
@@ -181,8 +182,48 @@ The API URL is validated on construction — HTTPS required, credentials in the
 CACHEKIT_API_KEY=ck_live_...          # API key — or pass api_key= to CachekitIOBackend / @cache.io
 CACHEKIT_API_URL=https://api.cachekit.io  # Optional — defaults to api.cachekit.io
 CACHEKIT_TIMEOUT=5.0                  # Optional — request timeout in seconds
+CACHEKIT_TELEMETRY=false              # Optional — turns telemetry off (see Telemetry)
 ```
 
+## Telemetry
+
+While cachekit.io is in closed beta, a `CachekitIOBackend` sends usage telemetry to cachekit.io by default. It
+becomes opt-in when the service launches. It goes only to the API URL the backend is configured with, as headers
+on the cache requests the backend already makes; nothing is sent on its own, and the Redis, Memcached and File
+backends and L1-only caches send none.
+
+| Headers | What they carry |
+|---------|-----------------|
+| `X-CacheKit-Session-ID`, `X-CacheKit-Session-Start` | A per-function session id, a random per-process id joined to the decorated function's `module.qualname` (so it carries the function's name), and its start time |
+| `X-CacheKit-L1-Hits`, `X-CacheKit-L2-Hits`, `X-CacheKit-Misses` | The calling function's hit and miss counts this session |
+| `X-CacheKit-L1-Hit-Rate` | L1 hits / (L1 hits + L2 hits + misses), three decimals |
+| `X-CacheKit-L1-Latency-Buckets`, `-Sum-Ns`, `-One-In` | How long the L1 hits timed since the previous request took (below) |
+
+**L1 hit latency.** Each `@cache` call through the backend is timed with probability 1/256, chosen at random before
+the call runs. A timed call that is an L1 hit adds its duration, from entering the wrapper to returning the value,
+to a report: sixteen duration buckets doubling from 128 ns, and their sum in nanoseconds. A duration over 60 s is
+dropped and counts toward neither. The next request to
+cachekit.io carries the report and empties it, so each hit is reported once. A call that waited on another call's
+miss for the same key, a miss, an L2 hit and a direct `backend.get()` are never timed, and the health check never
+carries a report. A forked child starts with an empty report and its own random draws. Under uWSGI without
+`--py-call-uwsgi-fork-hooks`, a worker draws the same sequence as its siblings until it builds a backend or makes its
+first request or timed hit on one it inherited. Each call is still timed with probability 1/256, but those workers
+time the same call positions. The flag removes the window. Hits timed after the last request are not sent.
+
+**Turning it off.** Pass `telemetry=False`, or set `CACHEKIT_TELEMETRY` (name and value in any case) to `false`, `0`, `off` or `no`.
+Off from either wins over on from the other; both unset is on. An empty or blank value counts as unset, so it leaves
+telemetry on. Any other value of the variable also turns telemetry off and logs one warning. Both are read once, when the backend is constructed: set the variable before creating it.
+`@cache.io()` builds its own backend, so use the variable there.
+
+```python notest
+from cachekit.backends.cachekitio import CachekitIOBackend
+
+backend = CachekitIOBackend(telemetry=False)
+```
+
+With telemetry off, requests carry none of the headers above. They still carry `X-CacheKit-L1-Status`, which the
+API requires, and a `User-Agent` naming cachekit-py and its version.
+
 ## When to Use
 
 **Use CachekitIOBackend when**:

docs/configuration.md

@@ -140,6 +140,10 @@ CACHEKIT_TIMEOUT=5.0
 # The same variable sizes the Redis pool, whose default is 50
 CACHEKIT_CONNECTION_POOL_SIZE=32
 
+# Optional: Turn telemetry off: false, 0, off or no (default: unset, which is on during the closed beta)
+# Off here wins over CachekitIOBackend(telemetry=True). Read once, when the backend is constructed
+CACHEKIT_TELEMETRY=false
+
 # Optional: Allow custom API hostname - disables SSRF hostname allowlist (default: false)
 # Only set to true when pointing at a private test server
 CACHEKIT_ALLOW_CUSTOM_HOST=false
@@ -154,6 +158,7 @@ CACHEKIT_ALLOW_CUSTOM_HOST=false
 | `CACHEKIT_TIMEOUT` | `float` | `5.0` | No | Per-request timeout in seconds |
 | `CACHEKIT_CONNECTION_POOL_SIZE` | `int` | `32` | No | HTTP connections the backend's one pool keeps, shared by every thread and by async calls. Each concurrent request uses one (HTTP/1.1); a request that finds all in use opens a short-lived extra connection, and urllib3 logs a pool-full warning. The same variable sizes the Redis pool, whose default is 50 |
 | `CACHEKIT_ALLOW_CUSTOM_HOST` | `bool` | `false` | No | Disable hostname allowlist (testing only) |
+| `CACHEKIT_TELEMETRY` | on/off | unset (on) | No | `false`, `0`, `off` or `no` turns off the usage telemetry headers; `true`, `1`, `on` or `yes` leaves them on; an empty or blank value counts as unset (on); any other value is off. Off from this or from `CachekitIOBackend(telemetry=False)` wins. `CACHEKIT_TELEMETRY` is not bound to the `telemetry` field; the backend combines the two when it is constructed. The name matches in any case, like the other `CACHEKIT_*` variables. See [Telemetry](backends/cachekitio.md#telemetry) |
 
 **Security notes:**
 - `CACHEKIT_API_URL` must use HTTPS. HTTP is rejected at startup.