For the complete documentation index, see llms.txt. This page is also available as Markdown.
Cortex XDR

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.

Note

The datasets do not include playbook executions in the Playground or in debug mode.

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.

1

Navigate to Investigation & Response > XQL Search.

2

Define the dataset

In the query editor, define the dataset you wish to analyze. For example: dataset = playbook_tasks

3

Run the query

Click Run.

4

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.

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 milliseconds, 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

Find the top 10 slowest playbooks (by average runtime)

Find the slowest tasks (by average duration)

Identify which automation scripts are used most

Last updated

Was this helpful?