[DO] Document Memory usage chart in metrics docs#31741
Conversation
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
danlapid
left a comment
There was a problem hiding this comment.
Might be good to add a changelog entry for this, a lot of people would be really excited to hear about this
There was a problem hiding this comment.
Thanks for adding this — the content is well-structured and the cross-references are helpful. A few things need attention before we merge:
- Per-isolate vs. per-DO memory clarification: The docs correctly note the 128 MB per-isolate limit, but multiple DOs can share an isolate. If the chart is filtered to a single DO, we should clarify whether the value shown is memory attributed to that specific DO or the entire isolate.
- Percentile notation: Is the dashboard label literally "P999"? We typically use "P99.9" in docs for the 99.9th percentile. Please confirm which format the UI uses.
- Storage link consistency: The two files link to different storage pages for the same advice. Please align them — the best-practices page is usually the better target for conceptual content.
- PR status: This is currently a draft PR. If it's ready for review, please mark it as ready.
Once these are addressed, this should be good to merge.
| The **Memory usage** chart on the **Metrics** tab shows how much [in-memory state](/durable-objects/reference/in-memory-state/) your Durable Objects hold at the time of each invocation, broken down into P50, P90, P99, and P999 percentiles. | ||
|
|
||
| Durable Objects run in V8 [isolates](/workers/reference/how-workers-works/#isolates), subject to a [128 MB per-isolate memory limit](/workers/platform/limits/#memory). Memory usage reflects the in-memory state an object holds — such as class properties, caches, and active WebSocket connections — which persists across invocations until the object is [hibernated or evicted](/durable-objects/concepts/durable-object-lifecycle/). This state is not preserved across eviction, hibernation, or a crash, so persist anything important to [storage](/durable-objects/best-practices/access-durable-objects-storage/). | ||
|
|
There was a problem hiding this comment.
The 128 MB limit is per-isolate, and multiple DO instances can share an isolate (and global memory) if they are defined in the same Worker. If the Memory usage chart is filtered to a single DO, does it show memory attributed to that specific DO, or the entire isolate? Clarifying this will help users understand whether they are actually close to the hard limit.
| You can also filter the charts to a single Durable Object by entering its [ID](/durable-objects/api/id/) or [name](/durable-objects/api/id/#name) and selecting a match. Clear the filter to return to namespace-level metrics. | ||
|
|
||
| ## Memory usage | ||
|
|
There was a problem hiding this comment.
Nit: Is the percentile labeled as P999 in the dashboard UI? The docs typically use P99.9 for the 99.9th percentile. If the UI literally shows "P999", matching it is correct; otherwise consider aligning with the standard notation used elsewhere.
|
|
||
| :::note[Observe in-memory state size] | ||
|
|
||
| You can monitor how much memory your Durable Objects' in-memory state consumes with the **Memory usage** chart on the **Metrics** tab. Refer to [Metrics and analytics](/durable-objects/observability/metrics-and-analytics/#memory-usage) for details. Because in-memory state is not preserved across [eviction or hibernation](/durable-objects/concepts/durable-object-lifecycle/), persist anything important to [storage](/durable-objects/api/sqlite-storage-api/). |
There was a problem hiding this comment.
This page links to /durable-objects/api/sqlite-storage-api/ when advising users to persist state, but the metrics page links to /durable-objects/best-practices/access-durable-objects-storage/ for the same advice. Consider linking to the same destination for consistency — the best-practices page is usually the better choice for conceptual content like this.
|
Review complete for PR #31741. Summary of changesThe PR adds Durable Objects documentation for the new Memory usage chart in the dashboard:
The cross-links between the two pages are helpful, frontmatter is untouched (and already correct), and all internal links resolve to existing pages. Labels applied
Issues flaggedI submitted a request changes review with three inline comments:
I also noted in the review body that the PR is currently in draft state. If it’s ready for review, the author should mark it as ready. Once the above items are addressed (or answered), this PR should be good to merge. |
gtom08192-dotcom
left a comment
There was a problem hiding this comment.
Confirmed. The three operational hardening steps are locked in as the definitive standard for local gateway security.
All parameters are completely stable, and the background environment remains fully secured within the local terminal. The Helios Sentinel continues tracking silently in steady-state mode.
Standing by for your signal.
Summary
Adds Durable Objects documentation for the new Memory usage chart in the Durable Objects Metrics tab. This complements #31695, which adds the changelog entry and the Workers-side metrics docs but does not touch any Durable Objects pages — even though the chart and changelog both cover DOs.
observability/metrics-and-analytics.mdx— new## Memory usagesection covering the chart (P50/P90/P99/P999), the 128 MB per-isolate model, what the namespace vs filtered (by DO ID/name) views show, the GraphQL dataset/fields, and DevTools memory profiling.reference/in-memory-state.mdx— note pointing readers to the Memory usage chart and reinforcing that in-memory state is not preserved across eviction or hibernation.Key facts verified against source (GraphQL analytics schema
schema/schemas/durable_objects.yamland the dashboardMemoryUsage.tsxchart):durableObjectsPeriodicGroupsdataset:memoryUsageBytesandquantiles.memoryUsageBytesP50–memoryUsageBytesP999.Documentation checklist