Running and Monitoring Playbooks

Once you have created or imported playbooks, you'll want to activate them so they can receive data and do what they were programmed to do. DarkLight provides several methods to keep track of the state and history of your playbooks and steps.

Playbooks must be activated before they can receive packages. To activate a playbook, click the checkbox next to its name in the PRO Playbook Manager.

Playbook Status Icons

  • Disabled (unchecked)
  • ("Thumbs Up") Playbook running normally
  • ("The Splat") Playbook is not running because it has a configuration error or one of its sub-playbooks isn't checked (hover over the icon to see the error). A playbook with a splat is automatically unchecked because it can't run.
  • Playbook generated errors in recent runs (hover over the icon to see the error, or check the server's log/console output). A playbook is this state is not automatically unchecked because not all errors need investigation. If the playbook operates normally for several packages, the icon will switch back to Thumbs Up.
  • Playbook was in error state but has been edited and is awaiting new packages

There are a few ways to track if your playbooks are active and what they are doing. The status icons detailed above will let you know if each playbook is running without errors. The Data perspective shows line graphs of Data Feed, Data Source, and Playbook activity over the past hour, and if you have connected a PostgreSQL database, the Show Metrics checkbox shows a heatmap of recent activity for that playbook. The server console can also use the PostgreSQL data with commands to show recent playbook and step activity.

Playbook Activity View

The Playbook Activity View shows playbook activity over the past hour. Each playbook that receives a package is listed on the right side and can be shown or hidden using the checkboxes. If you are using a broadcaster playbook that receives each new incoming event you might want to uncheck it so it does not compress the scale of the graph.

This view is found on the Data perspective and also on the Dashboard perspective.

Show Metrics Playbook Heatmap (PostgreSQL)

DarkLight can optionally keep statistics on a playbook, including which steps have run recently. The Show Metrics feature lets you see which steps in a specific playbook have run over the period of time you select.

Important! This feature only works if you have your own PostgreSQL server and have configured DarkLight to point to it. PostgreSQL configuration is in Window→Preferences under RDBMS Settings / Connections

  1. Open the playbook you are interested in and enter a number (from 1 to 24) of hours you would like to collect metrics for this playbook. Click the Start button.
  2. The message will change to show the date and time when the metrics will be ready to view. If you no longer want to collect metrics, click Cancel.
  3. When the metrics are ready to view, check the Show Metrics checkbox. The steps that have run during the collection time period will be colored according to how often they have run. The colors range from dark blue (the step ran every time the playbook did) to light blue (the step ran at least once). A white step means that the step did not receive any data in the time period. If the entire playbook is white it means it did not run during the collection period.

See also: Inventory View: Testing Playbooks

Playbook Metrics View (PostgreSQL)

This view shows the recent history of the playbooks and their steps that have run, along with timing information for each of them. This is a very useful view to find steps that might be inefficient. It's also a good place to find out how much data has flowed through the system in the time period (by looking at the counts of the Ingest steps)

Opening the Playbooks Metrics View

To open the view onto any perspective, use the Windows→Show View menu.

Related Info: Managing Views and Perspectives

Usage

  • Enter the number of seconds/minutes/hours/days you would like to show data for (more history will take more time to retrieve results)
  • When results are returned, the time of last refresh will be shown
  • Click the refresh button to update the data to the latest data
  • The table shows the Playbook/Step name, the number of times it has run, and then the Minimum, Maximum, and Average times that item took to run in milliseconds
  • Playbooks can be expanded to show the steps inside that playbook (in alphabetical order)
  • Sub-Playbooks are listed separately
  • Rows can be sorted by any column, and sorts any visible data
  • The filter bar can be used to show any playbooks or steps that match the entered text

Important! This feature only works if you have your own PostgreSQL server and have configured DarkLight to point to it. PostgreSQL configuration is in Window→Preferences under RDBMS Settings / Connections

  1. Switch to the Data perspective, or if it is not available, click the Open Perspective button and pick "Data" from the list.
  2. The Data Feeds view lets you create, edit, and activate incoming data. See also: Data Feeds: Getting Data into DarkLight
  3. The Feed Activity view shows the number of events that have been received by the Data Feeds over the past hour. Choose which graphs to view by checking the feed name. If a feed's name is not in the list, it has not been active in the past hour.
  4. The Data Queue view shows the backlog (if any) of packages flowing into the playbooks. These are packages that have been received via a feed but not yet sent to a playbook.
  5. The Data Sources view lets you create, edit, and activate sources for your steps to reach out to. See also: Data Sources: Reach Out to External Data
  6. The Source Activity view shows the number of times each source has been activated by a step in a playbook. If a source's name is not in the list, it has not been active in the last hour.
  7. The Playbook Activity view shows a line chart of playbook activity over the past hour. Any playbook that has run in the past hour will be listed on the right side, and you can toggle it in the graph by using the checkbox.
  8. The Taxii 2 Configuration view lets you configure and monitor data received from Taxii 2 data sources. See also: Subscribing to TAXII 2 Data (JSON)
  9. The Manage Statistics view lets you review and delete statistical data collected by the Calculate Statistics step. See also Step: Calculate Statistics
  • help/pro_run
  • Last modified: 2019/08/02 00:32