History Retention Policy
Dapr workflow state is stored in the [actor state store]{{ %ref workflow-architecture.md#state-store-usage %}}. By default, Dapr Workflows retains the complete history of workflow state changes indefinitely. This means historical workflows can be queried and inspected at any time. Running many workflows or workflows which generate large amounts of state change history can lead to increased storage usage, which can eventually fill up the state store disk space.
To help manage storage usage, Dapr Workflows supports configuring a history retention policy.
The retention policy defines how long to retain workflow state change history before it is deleted.
Workflows will only be eligible for deletion once it has reached a terminal state (Completed, Failed, or Terminated).
Each workflow terminal state can have a custom retention duration, as well as a default retention duration for any terminal states not explicitly configured.
The duration is defined as a Go duration string (for example, 72h for 72 hours, or 30m for 30 minutes).
Note
It can be useful to configure a short retention duration forCompleted workflows, while retaining Failed and Terminated workflows for longer periods to allow for investigation.Important
When adding or changing a retention policy, the policy only applies to workflows that newly reach a configured terminal state after the policy is in effect. It does not retroactively clean up workflows that are already in a terminal state.
To retroactively purge existing terminal workflows, use the Dapr CLI:
# Purge all terminal workflows older than a specific duration
dapr workflow purge --app-id <app-id> --all-older-than <duration>
# Purge only workflows with a specific status older than a duration
dapr workflow purge --app-id <app-id> --all-older-than <duration> --all-filter-status COMPLETED
dapr workflow purge --app-id <app-id> --all-older-than <duration> --all-filter-status FAILED
dapr workflow purge --app-id <app-id> --all-older-than <duration> --all-filter-status TERMINATED
When purging workflows, ensure that a workflow client is running for the same app-id so the workflow state machine can advance correctly. Avoid using the --force option while workflow instances may still be active, as this can corrupt the workflow state machine.
See How to: Manage workflows for more details on the purge command and additional cautions.
The following example configuration sets each of the terminal states.
The anyTerminal property set here would take no effect as all terminal states are explicitly configured, however it is included for reference.
See the Dapr Configuration documentation for more information on how to apply configuration to your Dapr applications.
kind: Configuration
metadata:
name: appconfig
spec:
workflow:
stateRetentionPolicy:
anyTerminal: "360h"
completed: "1m"
failed: "720h"
terminated: "360h"
Related links
- Try out Dapr Workflows using the quickstart
- Workflow overview
- Workflow API reference
- Try out the following examples: