cloudflare / cloudflare/workerd

Durable Object Lifecycle Event Emission for Local Dev Tooling

Open
#5,835 0 comments 5 reactions 0 assignees View on GitHub
feature request
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.