The Playbooks Activity screen in ThreatConnect® is a control panel on which Organization Administrators and higher can monitor Playbook Server and Worker execution metrics, priorities, and processes for their instance. From this screen, current, present, and past Worker activity and allocation to Servers can be viewed and Playbook executions can be killed. For more information on Playbooks in general, see Playbooks.
Servers and Workers
A Playbook Server, also known as a Job Server, is a ThreatConnect instance that is dedicated to the execution of Playbooks. Multiple Playbook Servers can be deployed to an instance in order to scale Playbook execution capacity, enable high availability, or isolate resources. Playbook Servers can be designated as Public or Private. Private Playbook Servers enable ThreatConnect Organizations to assign a Playbook to a dedicated instance for resource allocation or quality-of-service needs. Public Playbook Servers are designated to a pool and can be used to scale horizontally for any Organization. See the ThreatConnect System Administration Guide for information about configuring and deploying Playbook Servers.
A Playbook Worker is an embedded process in a Playbook Server responsible for executing orchestration logic in a queue. A Worker can execute only one Playbook at a time, and multiple Workers can exist inside a Playbook Server. Worker count can be changed on the Playbooks Activity screen by a System Administrator. It is limited by the hardware capacity of the Playbook Server.
The Playbooks Activity Screen
On the top navigation bar (Figure 1), click PLAYBOOKS to display the Playbooks screen (Figure 2).
Click on the Activity tab at the top left of the screen, and the Activity screen will appear (Figure 3).
The Server Metrics section provides metrics about the Playbook Servers available to the user’s instance of ThreatConnect, including the following information:
- CPU Utilization: This metric specifies the current usage of the CPU of the instance by the selected Playbook Server.
- Memory Utilization: This metric specifies the current usage of the memory of the system by the selected Playbook Server.
- Type: This metric specifies whether the server is a Public Server or a Private Server.
- CPU, Memory, and Disk: These metrics specify information about the hardware configuration of the Playbook Server.
Use the dropdown menu at the top to select a Server for which to view information. Private Servers will be designated by a lock icon next to their name. In a multi-tenant instance of ThreatConnect, Private Servers are dedicated instances on which users in an Organization can run a Playbook rather than have the Playbook execute through the queue of the pool of Public Servers (i.e., the Default Server Pool). Private Servers should be used for Playbooks of priority or performance requirements that necessitate their execution outside of the Default Server Pool.
The Playbook Metrics section provides metrics about the top Playbook and App executions that have run on all Servers available to the instance. If the Counts columns are selected, as in Figure 3, the section provides information about the number of executions of those Playbooks and Apps (and, for the Playbooks, the Organization that owns them) that have executed the most. If the Duration columns are selected, as in Figure 4, the section provides information about the average amount of time it took for the Playbooks and Apps that have had the longest execution durations to execute.
The Playbooks Queue section provides the following information about the queue of Playbooks waiting for execution:
- Queue Size: This section provides the number of Playbooks in the queue. The number changes in real time as Playbooks move through the queue and are executed.
- Wait Time: This section provides an estimate of the number of seconds that a Playbook will wait for execution if it just got added to the queue.
- Queued Playbooks: This section lists the Playbooks that are in the queue, including their name, owner, and count (i.e., how many executions are queued for that particular Playbook).
- Completed Playbooks: This section provides the number of Playbooks that have been completed. Clicking on it causes the screen to scroll down to the list of completed Playbooks (See the “Completed Playbooks” section later in this article.)
Figure 5 shows what the Playbooks Queue section looks like when there are Playbooks in the queue.
The Workers section provides the number of Workers available to the instance (in parentheses after the “Workers” heading) and rectangular boxes that represent each Worker.
Each Worker is represented by a rectangular box, as shown in Figure 6 for the idle Worker named Alderaan and in Figure 7 for the active Worker named Lothal.
The graphic for a Worker provides the following information:
- Status or Playbook: If this section displays the Status heading, then it will also indicate that the Worker is idle. If the Worker is active, then the heading will change to Playbook, and it will list the name of the Playbook that the Worker is currently executing.
- Server or Elapsed Time: For idle Workers, this section lists the Server on which the Worker is operating. For active Workers, this section lists the amount of Elapsed Time for which the Worker has been executing the Playbook.
- Colored Boxes: The colored boxes at the bottom of an active Playbook provide a linear depiction of the different Triggers, Apps, and Operators in the Playbook. As in the Playbook Designer, Triggers are green rectangles; Apps are blue rectangles; and Operators are black squares (Merge), orange diamonds (If/Else), or blue rectangles (Delay). If an item (Trigger, App, or Operator) is gray, then it has not yet finished executing. Hovering over a box will cause a pop-up bubble with the name of the Trigger, App, or Operator to appear, as shown in Figure 7.
When a Worker is active, hovering the cursor over its graphic will cause the graphic to appear like the one in Figure 8.
This graphic provides the following additional information:
- Session: This section provides the unique session identification number that is assigned to each Playbook execution.
- Current Steps: This section shows lists the App(s) that are currently being executed.
Clicking on the DETAILS box at the top of the graphic causes the Worker flyout to appear (Figure 9).
The Worker flyout provides information on the Owner of the Playbook being executed, the Server on which the Worker is operating, the Playbook that the Worker is currently executing, the Session identification number for the execution, the Total Elapsed Time for the current Playbook execution, and a table containing a breakdown of the execution status for the Apps in the Playbook.
Killing a Playbook
Click on the KILL PLAYBOOK button in the Worker flyout (Figure 9) to end a Playbook’s execution. Clicking the KILL PLAYBOOK button will immediately cancel the execution; no confirmation window will appear.
The Completed Playbooks section (see Figure 3) provides a list of all Playbooks that have been executed on the instance, including the following information:
- Execution Results: The colored circle on the left-hand side of each row indicates whether a Playbook’s execution was successful (green), partially failed (orange), or completely failed (red). See the “Playbook Execution and Logging” section of Playbooks for more information.
- Session: This column provides the unique session identification number for each Playbook execution.
- Owner: This column provides the name of the owner for each executed Playbook.
- Playbook: This section provides the name of the Playbook.
- Type: This section provides the Trigger type of the Playbook.
- Server: This section provides the name of the Server on which the Playbook executed.
- Worker: This section provides the name of the Worker that executed the Playbook.
- Started: This section provides the time that the Playbook execution started.
- Ended: This section provides the time that the Playbook execution ended.
Clicking anywhere in one of the rows will cause the selected Playbook to open in Execution Mode for that particular execution in a new browser tab, showing the pathway that the Playbook took for the execution (Figure 10).
Playbooks that were killed will be marked with a red circle (“failed” result) in the Completed Playbooks section, and the status of the App that was running when the Playbook was killed will appear as Killed when that execution is viewed in Execution Mode (Figure 11).