cloudflare / cloudflare/workerd
Durable Object Lifecycle Event Emission for Local Dev Tooling
- Dominant language
- C++
- Stars
- 8.7k
- Forks
- 739
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 174
Description
## Summary
Add a mechanism for workerd to emit events when Durable Objects transition between lifecycle states (active, hibernated, inactive/evicted). This would enable Miniflare and local development tools to build resource inspectors that display DO state without the observer effect of waking hibernated objects.
## Motivation
We're building local developer tooling that includes a resource inspector to help developers understand and debug their Durable Objects during development. A key piece of information developers need is the current lifecycle state of their DOs:
- **Active (in-memory)**: Currently processing requests or has scheduled work
- **Hibernated**: In-memory but idle, with hibernatable WebSockets keeping the DO alive
- **Inactive/Evicted**: Removed from memory entirely
### Heisenberg's problem of Durable Objects (the observer effect)
Inspecting a Durable Object to determine its state inherently changes that state. Any interaction with a DO will wake it up and transition it back to the active state. This creates an impossible situation for developer tooling:
```
Developer wants to see: "DO 'room-123' is currently hibernated"
What happens when we check: DO 'room-123' wakes up and becomes active
What developer sees: "DO 'room-123' is active" (incorrect/stale)
```
Currently this makes it impossible to build accurate observability tools that show the true runtime state of Durable Objects.
### Use Cases
1. **Local Resource Inspector**: A dashboard in `wrangler dev` or Vite dev server showing:
- List of instantiated DOs with their current lifecycle state
- Visual indicators (e.g., green = active, yellow = hibernated, grey = evicted)
- WebSocket connection counts per DO
- Transition history/timeline
2. **Debugging Hibernation Issues**: Developers using the WebSocket Hibernation API encounter bugs where state isn't properly persisted before hibernation. Being able to see when hibernation actually occurs (without triggering a wake) might help them diagnose these issues.
3. **Performance Profiling**: Understanding how often DOs hibernate and wake can help developers optimise their applications for cost.
4. **Educational/Learning**: New developers learning about DO lifecycles would benefit from seeing the state machine in action.
Open to any possible solutions you think would work for us.
[Feature request partially Claude'd following discussions with the team]
Contributor guide
Assessment
This issue has not been assessed yet.