Build a trigger
Triggers provide expanded functionality of your ExtraHop system. With triggers, you can create custom metrics, generate and store records, or send data to a third-party system. Because you write the trigger script, you control the actions taken by the trigger upon specified system events.
Before you begin
Log in to the Discover or Command appliance with a user account that has the full write privileges required to create triggers.If you are new to triggers, familiarize yourself with the trigger planning process, which will help you narrow the focus of your trigger, or determine whether you need a build a trigger at all. Then, run through the process of building a trigger by completing the Triggers Walkthrough.
Configure trigger settings
The first step to building a trigger is to provide a trigger name, determine whether debugging is enabled, and most importantly, identify which system events the trigger will run on.
Write a trigger script
The trigger script specifies the instructions the trigger will carry out when a system event configured for the trigger occurs.
Before you begin
We recommend that you open the ExtraHop Trigger API Reference, which contains the events, methods, and properties you need for your trigger. A link is also available from the trigger editor window in the ExtraHop Web UI.Assign a trigger to a device
You can assign a trigger to one or more devices or to a device group. A trigger does not run until it is assigned to a device, and the trigger gathers metric data only from the devices to which it is assigned.
Warning: | Running triggers on unnecessary devices and networks exhausts system resources. Minimize performance impact by assigning a trigger only to the specific sources that you need to collect data from. |
Important: | Triggers with the following events run whenever the event occurs.
Triggers that only run on these events cannot be assigned to devices or device
groups.
|
- Log into the Web UI on the ExtraHop Discover or Command appliance.
- Click Metrics from the top menu.
- Click Devices or Device Groups in the left pane.
- Select the checkbox for each device or device group you want to assign the trigger to.
- Click the Assign Trigger icon from the top of the page.
- Select the checkbox for each trigger you want to assign to the selected devices or device groups.
- Click Assign Triggers.
Tip: | You can also manage trigger assignments for a device from the device overview page. From the Manage Device section, click Assignments to add or remove trigger assignments from the device and to view which triggers are already assigned to the device. |
Advanced trigger options
You must configure triggers to run on at least one event. Depending on the selected event, the Trigger Configuration window displays advanced configuration options. For example, selecting the HTTP_RESPONSE event enables you to set the number of payload bytes to buffer each time that event occurs on the system.
Option | Description | Supported events |
---|---|---|
Bytes per packet to capture | Specifies the number of bytes to capture per packet. The capture starts with
the first byte in the packet. Specify this option only if the trigger script
performs packet capture. A value of 0 specifies that the capture should collect all bytes in each packet. |
All events are supported except the following list:
|
Bytes to Buffer | Specifies the minimum number of payload bytes to buffer. |
|
Clipboard Bytes to Buffer | Specifies the number of bytes to buffer on a Citrix clipboard transfer. |
|
Metric Cycle | Specifies the length of the metric cycle, expressed in seconds. The following
values are valid:
|
|
Metric Types | Specifies the metric type by the raw metric name, such as extrahop.device.http_server. Specify multiple metric types in a comma-delimited list. |
|
Per Turn | Enables packet capture on each flow turn. Per-turn analysis continuously analyzes communication between two endpoints to extract a single payload data point from the flow. If this option is enabled, any values specified for the Client matching string and Server matching string options are ignored. |
|
Client port min | Specifies the minimum port number of the client
port range. Valid values are 0 to 65535. A value of 0 specifies matching of any port. |
|
Client port max | Specifies the maximum port number of the client port range. Valid values are 0 to 65535. Any value specified for this option is ignored if the value of the Client port min option is 0. |
|
Client bytes to buffer | Specifies the number of client bytes to buffer. The value of this option cannot be set to 0 if the value of the Server bytes to buffer option is also set to 0. |
|
Client matching string | Specifies the format string that indicates when to begin buffering client
data. Any value specified for this option is ignored if the Per Turn option is enabled. |
|
Server port min | Specifies the minimum port number of the server port range. Valid values are 0 to 65535. A value of 0 specifies matching of any port. |
|
Server port max | Specifies the maximum port number of the server port range. Valid values are 0 to 65535. Any value specified for this option is ignored if the value of the Server port min option is 0. |
|
Server bytes buffer | Specifies the number of server bytes to buffer. The value of this option cannot be set to 0 if the value of the Client bytes to buffer option is also set to 0. |
|
Server matching string | Specifies the format string that indicates when to begin buffering data.
Returns the entire packet upon a string match. Any value specified for this option is ignored if the Per Turn option is enabled. |
|
All UDP Datagrams | Enables capture of all UDP datagrams. |
|
Run FLOW_CLASSIFY on expired flows | Enables running the event upon expiration to accumulate metrics for flows that were not classified before expiring. |
|
Thank you for your feedback. Can we contact you to ask follow up questions?