> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xdr/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/playbooks/monitor-and-troubleshoot-playbook-automations-with-xql-datasets.md).
# Monitor and troubleshoot playbook automations with XQL datasets
Monitor and troubleshoot Cortex XDR playbook automations by using XQL datasets and automation logs to identify execution issues and analyze results.
Cortex XDR provides centralized visibility into playbook executions and their automation logs. Use XQL datasets to monitor performance, investigate workflow failures, and analyze activity across playbooks, scripts, and commands.
{% hint style="info" %}
### Note
The datasets do not include playbook executions in the Playground or in debug mode.
{% endhint %}
### Monitor automation health with dashboards
You can use XQL datasets to build dashboards that expose the operational health of your SOC's automation. For example, you can monitor:
* **Execution frequency:** Track how often specific playbooks (such as malware handling workflows) are triggered to understand load and frequency.
* **Success vs. failure rates:** Create widgets to visualize the percentage of successful runs versus failures across all automation.
* **Trigger attribution:** Use the `trigger_by_type` and `executed_by` fields to identify if automation is being driven primarily by system rules, scheduled jobs, or manual analyst intervention.
### Troubleshoot playbooks and scripts
When automation workflows fail or behave unexpectedly, XQL allows you to isolate the root cause. For example, you can:
* **Identify broken scripts:** If multiple playbooks are failing, use the `playbook_tasks` or `scripts_and_commands_metrics` datasets to check if a specific script version (such as an Okta reset password script) is consistently returning errors across different parent workflows.
* **Analyze task failures:** Filter the `playbook_tasks` dataset by `task_status` to find tasks that are stuck in a pending state or failing. Review the `retry_count` and standardized error fields to determine if failures are due to transient network issues or configuration errors.
* **Sub-playbook visibility:** Use the `investigation_id` and `parent_playbook_id` fields to trace the execution flow of complex, nested playbooks.
### Implement performance best practices
Use duration metrics to optimize your automation and reduce system resource consumption.
* **Monitor execution time:** Analyze the `duration` and `net_duration` fields in the `playbook_runs` dataset to identify playbooks that are taking an unusually long time to complete.
* **Identify heavy tasks:** Use `execution_time_secs` in the `playbook_tasks` dataset to find specific tasks that are slowing down your workflows.
* **Standardized error handling:** Transition away from the deprecated `error` and `errors` fields to use standardized error reporting to ensure consistent troubleshooting across all datasets.
### Access automation datasets
To review automation logs and execution metadata, run an XQL query against the relevant dataset in the Query Center.
{% stepper %}
{% step %}
#### Navigate to XQL Search
Navigate to **Investigation & Response** > **XQL Search**.
{% endstep %}
{% step %}
#### Define the dataset
In the query editor, define the dataset you wish to analyze. For example: `dataset = playbook_tasks`
{% endstep %}
{% step %}
#### Run the query
Click **Run**.
{% endstep %}
{% step %}
#### Review the results
Use the **Query Results** tab to view the fields and execution details. You can also use the **Schema** tab in the right-hand panel to explore all available fields for the selected dataset. The table displays one row for each playbook run.
{% endstep %}
{% endstepper %}
#### Automation dataset field reference
The following tables list the key fields for the datasets supporting monitoring and troubleshooting automations.
playbook_runs dataset
These fields provide summary details of the playbook run.
| Field name | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_id` | The ID of the item the playbook ran on. |
| `entity_trigger_type` | The item type that started the playbook, for example ISSUE. |
| `playbook_name` | The name of the playbook that ran. |
| `playbook_id` | The ID of the playbook that ran. |
| `playbook_status` | How the run ended, for example Finished, Failed. **Note:** The status cannot be running because the query runs only after the playbook finishes running. |
| `finish_time` | The time the playbook run finished. |
| `start_date` | The time the playbook run started. |
| `modified` | The last time this run was changed. |
| `issue_create_time` | The time the issue was created. |
| `quiet_mode` | Whether the run was in quiet mode. |
| `run_time` | The total time the run took to run in seconds. |
| `incident_id` | The ID of the issue the playbook ran on. |
| `is_sub_playbook` | Whether this playbook is a sub playbook. |
| `parent_playbooks` | The name of the top-level playbook that started this playbook's execution. If this is the main playbook, this field is empty. |
| `net_duration` | The execution time in seconds, not counting waiting time. |
| `pack_version` | Currently not used. |
| `pack_id` | Currently not used. |
| `source_playbook_id` | Currently not used. |
| `is_copy` | Currently not used. |
| `is_ootb` | Currently not used. |
| `is_custom` | Currently not used. |
| `is_auto_enabled_rule` | Whether the trigger rule is an Autonomous Rule. |
| `run_index` | The number of times the playbook has been switched for this issue. |
| `incident_name` | Currently not used. |
| `indicators_count` | Currently not used. |
| `indicators_distribution` | Currently not used. |
| `commands` | Currently not used. |
| `scripts` | Currently not used. |
| `playbook_state` | Currently not used. |
| `playbook_priority` | The priority of the playbook execution. Higher playbook priorities are executed before lower playbook priorities. Configured on the automation rule. |
playbook_tasks dataset
These fields provide details of what happened in each playbook task.
| Field name | Description |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_id` | The ID of the item the playbook ran on. |
| `task_id` | The ID of the task inside the playbook. |
| `task_name` | The name of the task. |
| `task_status` | How the task ended, for example finished, failed, or skipped. **Note:** The status cannot be running because the query runs only after the playbook finishes running. |
| `retry_count` | How many times the task tried running again. |
| `continue_on_error` | Whether the playbook keeps running even if this task fails. |
| `finish_time` | The time the task finished. |
| `assignee` | The assigned user. |
| `task_playbook_id` | The ID of the playbook that this task belongs to. |
| `sla` | The task SLA. |
| `size` | The size of the data that the task generated. |
| `automated` | Whether the task ran automatically, not manually. |
| `reopened` | Whether the task was opened again after it was finished. |
| `comments` | Whether the task has comments. |
| `over_size` | Whether the task is large. |
| `quiet_mode` | Whether the task was in quiet mode. |
| `completed_by` | The person who finished the task, or Dbot. |
| `restricted` | Whether access to the task is restricted. |
| `due_date` | The time the task should be completed. |
| `start_date` | The time the task started. |
| `duration` | The total time to complete the run, in seconds. Includes waiting time for manual tasks. |
| `modified` | The last time this task was changed. |
| `type` | The task type, for example regular, start, conditional. |
| `script_id` | The ID of the script the task ran. |
| `script_name` | The name of the script the task ran. |
| `is_command` | Whether the task ran a command. |
| `command` | Currently not used. |
| `is_loop` | Whether the task is part of a loop. |
| `loop_iterations` | How many times the task looped. |
| `continue_on_error_type` | The way the task handles errors. |
| `skip_unavailable_flag` | Whether the task is skipped when there is an `unavailable_flag`. |
| `skipped_cause_silent` | Whether the task was skipped because it ran silent. |
| `skipped_because_missing_content` | Whether the task was skipped because some content was missing. |
| `conditional_path` | The path the task took when there was a condition. |
| `reputation_calc` | The reputation result for the task. |
| `condition_evaluations` | A list of the checks the task made. |
| `error` | Currently not used. |
| `errors` | A list of all the error messages from the task. |
| `is_sub_section` | Whether a task is a sub-section. |
scripts_and_commands_metrics dataset
These fields provide details of every command and script execution across the platform, including those triggered by playbook tasks, automation rules, jobs, and the Playground, to provide granular visibility into execution status, duration, and trigger sources.
| Field name | Description |
| ------------------- | ------------------------------------------------------------------------------- |
| `category` | The classification of the automation, such as, Analytic, Utility. |
| `name` | The display name of the command or script. |
| `instance` | The specific integration instance used for the execution. |
| `modified` | The timestamp of the last update to the execution record. |
| `type` | The type of execution, such as, command, script. |
| `duration` | The total time to complete the run in seconds. |
| `is_error` | Whether the execution resulted in an error. |
| `is_manual` | Whether the run was triggered manually by a user. |
| `is_enrichment` | Whether the automation is used for data enrichment. |
| `brand` | The product or vendor brand associated with the command. |
| `num_api_calls` | The total number of API requests made during the execution. |
| `api_response_type` | The format or status of the returned API data. |
| `ixixqwgh` | The specific architectural type of the automation. |
| `_time` | The primary timestamp of the log entry. |
| `errors` | List or collection of multiple errors, if applicable. |
| `trigger_by_type` | The type of trigger, such as playbook, automation rule, playground, job, agent. |
| `trigger_by_name` | The specific source (playbook name, job ID, automation rule ID, agent name). |
### XQL query use cases
The following query examples show how to quickly access automation metrics and troubleshoot issues.
#### Identify failed playbook runs
```
dataset = playbook_runs
| filter playbook_status = "failed"
| fields entity_id, playbook_name, playbook_id, start_date, _time , run_time
| sort desc start_date
```
#### Find the top 10 slowest playbooks (by average runtime)
```
dataset = playbook_runs
| filter run_time > 0
| comp avg(run_time) as avg_ms, count() as runs by playbook_name
| sort desc avg_ms
| limit 10
```
#### Find the slowest tasks (by average duration)
```
dataset = playbook_tasks
| filter duration > 0
| comp avg(duration) as avg_ms, count() as runs by task_name
| sort desc avg_ms
| limit 10
```
#### Identify which automation scripts are used most
```
dataset = playbook_tasks
| filter script_name != null
| comp count() as uses by script_name, script_id
| sort desc uses
| limit 20
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://cortex-docs.paloaltonetworks.com/cortex-xdr/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/playbooks/monitor-and-troubleshoot-playbook-automations-with-xql-datasets.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.