> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitor workflows
> Monitor workflow runs with detailed step logs, run states, performance metrics, and debugging tools to keep your Ravenna automations reliable.
Monitor workflow execution with detailed logs, performance metrics, and debugging tools to keep your automation running reliably.
## Understanding workflow runs
A workflow run represents a single execution triggered by an event and tracked from start to completion.
### Run states
| State | Description |
| ------------------------- | -------------------------------------------------------------------------------- |
| **Pending** | Waiting for execution resources |
| **Running** | Actively processing workflow steps |
| **Completed** | All steps finished successfully |
| **Completed with errors** | Run reached the end of the workflow, but at least one step errored along the way |
| **Failed** | The run halted because a step encountered an unrecoverable error |
| **Cancelled** | Execution stopped manually or by system |
### Run details
Each run captures start time, duration, trigger context and inputs, step-by-step execution results, success and failure counts, and error messages. Access workflow run history from the workflow detail page. Filter by status, search by trigger data or time range, and sort by execution time or duration.
***
## Step-by-step logging
Each workflow step is individually tracked with detailed execution information:
* **Input values**: Raw and resolved inputs for the step
* **Output data**: Data produced by the step
* **AI reasoning**: For AI steps (Decision Maker, Custom Prompt), the explanation the model provided for its decision or response
* **Execution duration**: How long the step took
* **Error messages**: Details if the step failed
* **Dynamic value resolution**: How references resolved at runtime
Use step logs to trace how data flows through your workflow. See how trigger data passes to actions, how action outputs feed subsequent steps, and where values transform along the way.
***
## Performance monitoring
Monitor executions per day, average duration, and peak usage periods
Track completion rates and identify reliability trends
Monitor error patterns and failure rates over time
View processing times and identify performance bottlenecks
***
## Debugging workflows
Check execution logs for specific error details and context
Identify which step failed and review its inputs and outputs
Verify data flowing between steps matches expectations
Confirm external services are available and authenticated
Make corrections in draft mode and test before republishing
***
## Common issues
* Verify the workflow is published and active (not draft or paused)
* Review trigger filters to confirm they match the expected event
* Check that required integrations are connected
* Check execution logs for the specific error message
* Verify all required fields are populated
* Test dynamic references with a manual run
* Confirm integration permissions are correct and the external service is operational
* Review dynamic value configuration for wrong references
* Check trigger data structure in logs to confirm expected fields exist
* Verify field names match exactly
* Check for external API delays in step durations
* Consider parallelizing sequential actions where possible
* Review external service performance
***
## Error types
| Error type | Cause | Fix |
| --------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
| **Validation** | Missing required fields, invalid formats, type mismatches | Review field requirements and provide valid data |
| **Integration** | Connection timeouts, authentication failures, API rate limits | Check integration status and external service health |
| **Permission** | Missing API scopes, insufficient access rights | Grant necessary permissions in integration settings |
| **Timeout** | External API delays, large data processing, network issues | Optimize the workflow or check external service performance |
***
## Retrying workflow runs
Retry a workflow run directly from the run history table when a run finishes in a state you want to redo. Use retries to recover from transient failures, rerun a workflow against the latest configuration, or re-execute a successful run on demand.
### When retry is available
The **Retry** action appears in the row actions menu for any run with one of these statuses:
* **Failed**
* **Completed with errors**
* **Completed**
Pending, running, cancelled, and skipped runs cannot be retried.
### Retry options
Selecting **Retry** opens a dialog with up to three options. Which options appear depends on the run's status and whether a newer workflow version has been published since the run started.
| Option | When it appears | What it does |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Retry with latest version** / **Rerun with latest version** | The run used an older workflow version and a newer version has been published | Starts a new run from the first step using the workflow's current active version |
| **Retry from failure** | The run failed or completed with errors and contains at least one failed step | Creates a new run that reuses successful upstream step outputs and reruns the failed step(s) on the same version |
| **Retry from beginning** / **Rerun** | Always available for retryable runs | Starts a new run from the first step using the same workflow version as the original run |
**Retry from failure** requires that the workflow shape upstream of the failed step has not changed between versions. If upstream steps were added, removed, or reconfigured, select **Retry with latest version** or **Retry from beginning** instead.
### Retry a run
Navigate to the workflow and select the **Runs** tab
Locate the run in the table. Filter by status if needed
Hover the row and select **Retry** from the actions menu
Select the option that matches your goal, then select **Retry**
A new run appears in the table linked to the original as its parent. Open it to monitor execution
### Retry via API
You can also retry a run programmatically. Send a `POST` request to `/workflows/runs/{runId}/retry` with an optional `versionId` and `retryFromFailure` flag.
```bash theme={"system"}
curl -X POST https://api.ravenna.ai/workflows/runs/{runId}/retry \
-H "Authorization: Bearer $RAVENNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"versionId": "wfv_abc123",
"retryFromFailure": true
}'
```
| Field | Type | Description |
| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `versionId` | string (optional) | Workflow version to run. Defaults to the version used by the original run. Pass the workflow's active version ID to retry against the latest published version |
| `retryFromFailure` | boolean (optional) | When `true`, reuses outputs from successful upstream steps and reruns failed step(s). When omitted or `false`, the run starts from the first step |
The response contains the new `runId`. Use it to fetch the new run or display it in your tooling.
***
## Workflow attribution in tickets
Each ticket event log shows which workflow triggered the change, including the workflow name, run ID, timestamp, and changed field values. Click the workflow badge on any ticket event to open the workflow run in a new tab and inspect the full run details. Use this to trace any automated update back to its source workflow. Workflow attribution helps you debug unexpected ticket changes, understand automation impact, and meet compliance requirements.
***
## Log management
Workflow logs are retained for analysis and compliance. Run logs use a standard retention period, while error logs have extended retention. Export logs before the retention period expires if you need long-term storage.
Log access is controlled by user permissions. View logs for workflows you own or manage. Workspace administrators can see all workflow logs.
***
## Failure notifications
Configure notifications to receive alerts when workflow runs fail. Set up notifications from the workflow **Settings** tab.
Failure notifications fire when a run finishes in either **Failed** or **Completed with errors**. The notification copy adapts to the run's final status so recipients can tell at a glance whether the workflow halted entirely or completed end-to-end with at least one step error.
Subscribe to email notifications for workflows you manage to receive personal failure alerts
Configure Slack channels to notify entire teams when critical workflows fail
### Configuring failure notifications
Navigate to your workflow and select the **Settings** tab
Toggle **Email me on failures** to receive personal email alerts when the workflow fails
Connect a Slack channel to post team notifications when workflow runs fail
Trigger a test failure to verify notifications are delivered correctly
### Email notifications
Personal email alerts notify you when workflows encounter failures. Each email includes the workflow name, run ID, and a direct link to the failure details. The subject line and body reflect whether the run **failed** or **completed with errors**. Emails include a one-click unsubscribe link that requires no authentication.
**Use email notifications when:**
* You need personal alerts for critical workflows
* You want offline notification access
* You manage workflows requiring immediate attention
### Slack notifications
Team Slack notifications post failure alerts to channels where your team collaborates. Messages include Block Kit formatting with clickable buttons and a direct link to run details. The message header reads **Workflow Run Failed** or **Workflow Run Completed With Errors** depending on the run's final status.
**Use Slack notifications when:**
* Teams need collective awareness of failures
* Failures require coordinated response
* Multiple people share responsibility for workflow reliability
Email and Slack notifications work independently. You can enable both to ensure critical workflow failures reach your team through multiple channels.
### Unsubscribing from emails
Workflow failure emails include a one-click unsubscribe link at the bottom. To resubscribe, visit the workflow **Settings** tab and toggle email notifications back on.
Unsubscribe links are unique to each user and workflow. Clicking an unsubscribe link only affects your notifications for that specific workflow.
***
## Tips
* **Set up failure notifications early.** Configure email and Slack alerts before relying on a workflow in production.
* **Review error patterns regularly.** Look for increasing failure rates or performance degradation that might indicate systemic issues.
* **Test after changes.** Monitor the first few executions closely after updating a workflow.
* **Keep integrations healthy.** Refresh credentials before they expire and verify API permissions when integrations add new features.
* **Document resolved issues.** Keep notes on what went wrong and how you fixed it. This helps troubleshoot similar problems faster next time.
Learn more about [building workflows](/documentation/automate/workflows/workflow-builder) and [publishing workflows](/documentation/automate/workflows/publish)
## Run and step statuses
**Run statuses:**
| Status | Meaning |
| --------------------- | ----------------------------------------------------------------- |
| Pending | Queued, waiting for execution resources |
| Running | Actively executing steps |
| Completed | All steps finished successfully |
| Completed with errors | Run reached the end of the workflow but at least one step errored |
| Failed | Run halted because a step encountered an unrecoverable error |
| Cancelled | Stopped manually or by system (e.g., Stop & Publish) |
**Step statuses:**
| Status | Meaning |
| --------- | ----------------------------------------------------------------- |
| Pending | Not yet started |
| Running | Currently executing |
| Completed | Finished successfully |
| Failed | Encountered an error |
| Skipped | Parent branch was skipped or condition was false |
| Waiting | Paused on a wait step (Wait for Approval, Wait for Message, etc.) |
***
## What step logs capture
Each step records:
* **Resolved inputs:** The actual values used after dynamic references are resolved.
* **Raw outputs:** The data produced by the step.
* **AI reasoning:** For AI Decision Maker and Custom Prompt steps, the model's explanation for its output or decision.
* **Duration:** Execution time for the step.
* **Error details:** Error type, message, and context if the step failed.
* **Retry attempts:** Number of retries and outcomes.
***
## Error types and retry behavior
| Error type | Cause | Retries | Notes |
| -------------- | -------------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| Validation | Missing fields, invalid formats, type mismatches | No | Fix the workflow configuration |
| Integration | Connection timeout, API error, service unavailable | Yes (3 attempts, exponential backoff) | Check integration health and external service status |
| Authentication | Expired credentials, insufficient permissions | No | Refresh credentials in integration settings |
| Timeout | Step took too long to complete | Yes | Check external service performance |
| Rate limit | Too many API requests | Yes (with backoff) | Reduce workflow frequency or stagger execution |
Retries use exponential backoff: 1 second, then 2 seconds, then 4 seconds. After 3 failed attempts, the step fails permanently and the run is marked as failed.
***
## Retrying a run
A run can be retried when its status is **Failed**, **Completed with errors**, or **Completed**. The **Retry** action appears in the row actions menu of the workflow runs table. Selecting it opens a dialog with up to three options:
* **Retry with latest version** — Start a new run from the first step using the workflow's current active version. Only offered when the original run used an older version.
* **Retry from failure** — Reuse outputs from successful upstream steps and rerun only the failed step(s). Requires that the upstream workflow shape and step configurations are unchanged between versions. Only offered when the run has at least one failed step.
* **Retry from beginning** / **Rerun** — Start a new run from the first step using the same version as the original run.
The new run is linked to the original through a parent run reference, which lets you trace retry chains.
### API
`POST /workflows/runs/{runId}/retry`
Body fields:
| Field | Type | Notes |
| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `versionId` | string, optional | Workflow version for the new run. Defaults to the original run's version. Pass the workflow's active version ID to upgrade to the latest |
| `retryFromFailure` | boolean, optional | If `true`, reuses successful upstream outputs and reruns the failed step(s). Otherwise the new run starts from the first step |
Returns `{ runId }` for the new run.
If the workflow shape upstream of the failed step changed between versions (a step was added, removed, or reconfigured), `retryFromFailure` returns an error. Fall back to starting from the beginning in that case.
***
## Debugging patterns
**Workflow not triggering:**
1. Verify the workflow is published (not draft or paused).
2. Check trigger filters. Filters use AND logic, so overly specific filters may exclude the event. Test with relaxed filters first.
3. Confirm required integrations are connected (for integration-based triggers).
4. Check if another workflow is handling the same event first.
**Action failing:**
1. Open the run log and find the failed step.
2. Check the resolved inputs. A common cause is a dynamic value reference resolving to null or an unexpected type.
3. Verify the integration is connected and credentials are valid.
4. Check external service status (Jira, Okta, etc. may be experiencing issues).
5. Test the same action with hardcoded values to isolate whether the issue is data or configuration.
**Incorrect data in actions:**
1. Check the resolved inputs on the problematic step. Compare expected vs. actual values.
2. Verify the dynamic reference points to the correct upstream step and field.
3. Check for name collisions if multiple steps have similar names.
4. Review the trigger output to confirm the expected data was present in the originating event.
**Slow execution:**
1. Check individual step durations to identify the bottleneck.
2. External API calls are the most common cause of slow steps.
3. Consider parallelizing sequential steps that are independent.
4. If a wait step is involved, verify the timeout configuration.
***
## Workflow attribution
Ticket events include workflow attribution: the workflow name, run ID, and timestamp. Click the workflow badge to open the workflow run directly in a new tab. This lets you trace any automated ticket change back to the specific workflow run that caused it. Useful for debugging unexpected ticket changes, auditing automation impact, and understanding which workflows affect which tickets.
***
## Failure notifications
Configure email and Slack notifications from the workflow Settings tab.
* **Email:** Personal alerts with workflow name, run ID, and a direct link to the failure. Includes one-click unsubscribe.
* **Slack:** Team notifications posted to a configured channel with formatted details and a link to run details.
Notifications fire for runs that end in **Failed** *or* **Completed with errors**. Subject line, email body, and the Slack header reflect which terminal status the run reached.
Set up failure notifications before relying on a workflow in production. Both channels work independently and can be enabled simultaneously.