Thank you!
We will contact you soon to
ask how we can improve our documentation.We appreciate your feedback.

Was this topic helpful?

YesNo

Thank you for your feedback. Can we contact you to ask follow up questions?

*Please enter a valid email address

How can we improve?

Trigger API Reference

Overview

Application Inspection triggers are composed of user-defined code that automatically
executes on system events through the ExtraHop trigger API. By writing triggers, you can collect
custom metric data about the activities on your network. In addition, triggers can perform
operations on protocol messages (such as an HTTP request) before the packet is
discarded.

The ExtraHop system monitors, extracts, and records a core set of Layer 7 (L7) metrics for
devices on the network, such as response counts, error counts, and processing times. After these
metrics are recorded for a given L7 protocol, the packets are discarded, freeing resources for
continued processing.

Triggers enable you to:

Generate and store custom metrics to the internal datastore of the ExtraHop system. For
example, while the ExtraHop system does not collect information about which user agent generated
an HTTP request, you can generate and collect that level of detail by writing a trigger and
committing the data to the datastore. You can also view custom data that is stored in the
datastore by creating custom metrics pages and displaying those metrics through the Metric
Explorer and dashboards.

Generate and sends records to an Explore appliance for long-term storage and
retrieval.

Create a user-defined application that collects metrics across multiple types of network
traffic to capture information with cross-tier impact. For example, to gain a unified view of
all the network traffic associated with a website—from web transactions to DNS requests and responses to database transactions—you can create an application that
contains all of these website-related metrics.

Generate custom metrics and send the information to syslog consumers such as Splunk, or to
third party databases such as MongoDB or Kafka.

Initiate a packet capture to record individual flows based on user-specified critera. You can
download captured flows and process them through third-party tools. Your ExtraHop system must be
licensed for packet capture to access this feature.

The purpose of this guide is to provide reference material when writing the blocks of
JavaScript code that run when trigger conditions are met. See Get started with triggers in the ExtraHop Web UI Guide for
a comprehensive overview of trigger concepts and procedures.

ExtraHop data types

ExtraHop data types record custom metrics using the Network, Application, and Device,
FlowNetwork, and FlowInterface classes.

There are two kinds of metrics in the ExtraHop system:

Top-level metrics

Represent an aggregate of all activity for a particular object type, such as network,
application or device.

count

Number (e.g., HTTP requests).

snapshot

A special type of count metric that, when queried over time, returns the most
recent value (e.g., TCP established connections).

Represents activity that is broken down by specific keys such as IP addresses or URIs.
For each key, there is a value that corresponds to the top-level metric types such as
count or snapshot. Detail metrics provide drill-down information for top level
metrics.

Examples:

To record information about the number of HTTP requests over time, use a top-level count
metric.

To record information about HTTP processing time over time, use a top-level sampleset (mean and average) or dataset (5-number summary) metric.

To record information about the number of times each client
IP address accessed the server, use a detail count metric with the IPAddress key and an
integer representing the number of accesses as a value.

To record information about the length of time it took the server to process each URI,
use a detail sampleset or dataset metric with the URI string key and an integer
representing processing time as a value.

To record the slowest HTTP statements over time without relying on a Session table, use
a top-level and a detail max metric.

Global functions

Global functions can be called on any event.

cache (key: String, valueFn: () => any):
any

Caches the specified parameters in a table to enable efficient lookup and return of
large data sets.

key: String

An identifier that indicates the location of the cached value. Keys must be
unique within a trigger.

valueFn: () => any

A zero-argument function that returns a non-null value.

In the following example, a list of known user agents in a JBoss trigger needs
to be normalized before comparison with the observed user agent. The trigger converts
the list to lowercase and trims excess whitespace, and then caches the
entries:

Flow refers to a conversation between two endpoints over a protocol such as TCP, UDP or
ICMP. The Flow class provides access to elements of these conversations, such as endpoint IP
addresses and age of the flow. The Flow class also contains a flow store designed to pass
objects from request to response on the same flow.

Application

The Application class enables you collect metrics across multiple types of network
traffic to capture information with cross-tier impact. For example, if you want a unified view
of all the network traffic associated with a website—from web transactions to DNS requests and
responses to database transactions—you can write a trigger to create a custom application that
contains all of these related metrics. The Application class also enables you to create custom
metrics and commit the metric data to applications. Applications can only be created and defined
through triggers.

Instance methods

The methods in this section cannot not be called directly on the Application class. You can
only call these methods on specific Application class instances. For example, the following
statement is valid:

Application("sampleApp").metricAddCount("responses", 1);

However, the following statement is invalid:

Application.metricAddCount("responses", 1);

commit(id: String): void

Creates an application, commits built-in metrics associated with the event to the
application, and adds the application to any built-in or custom records committed during
the event.

The application ID must be a string. For built-in application metrics, the
metrics are committed only once, even if the commit() method is
called multiple times on the same event.

The following statement creates an
application named "myApp" and commits built-in metrics to the
application:

Application("myApp").commit();

If you plan to
commit custom metrics to an application, you can create the application without
calling the commit() method. For example, if the application does not
already exist, the following statement creates the application and commits the custom
metric to the
application:

Application("myApp").metricAddCount("requests", 1);

You
can call the Application.commit method only on the following
events:

Creates a custom top-leveldataset metric. Commits the metric data to the
specified application.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detaildataset metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Instance properties

Trigger examples

Buffer

The Buffer class provides access to binary data.

A buffer is an object with the characteristics of an array. Each element in the array is a
number between 0 and 255, representing one byte. Each buffer object has a length property
(the number of items in an array) and a square bracket operator.

Encrypted payload is not decrypted for TCP and UDP payload analysis.

UDP_PAYLOAD requires a matching string but TCP_PAYLOAD
does not. If you do not specify a matching string for TCP_PAYLOAD, the
trigger runs one time after the first N bytes of payload.

Instance methods

decode(type: String): String

Interprets the contents of the buffer and returns a string with one of the following
options:

utf-8

ucs2

hex

equals(buffer: Buffer): Boolean

Performs an equality test between Buffer objects, where buffer is the
object to be compared against.

slice(start: Number, [end: Number]):
Buffer

Returns the specified bytes in a buffer as a new buffer. Bytes are selected starting
at the given start argument and ending at (but not including) the end argument.

start: Number

Integer that specifies where to start the selection. Use negative numbers to
select from the end of a buffer. This is zero-based.

end: Number

Optional integer that specifies where to end the selection. If omitted, all
elements from the start position and to the end of the buffer will be selected.
Use negative numbers to select from the end of a buffer. This is zero-based.

toString(): String

Converts the buffer to a string.

unpack(format: String, [offset: Number]):
Array

Processes binary or fixed-width data from any buffer object, such as one returned by
HTTP.payload, Flow.client.payload, or
Flow.sender.payload, according to the given format string and,
optionally, at the specified offset.

Returns a JavaScript array that contains one or
more unpacked fields and contains the absolute payload byte position +1 of the last
byte in the unpacked object. The bytes value can be specified as the offset in further
calls to unpack a buffer.

Note:

Buffer.unpack uses big-endian, standard alignment, by default.

The format does not have to consume the entire buffer.

Null bytes are not included in unpacked strings. For example:
buf.unpack('4s')[0] - > 'example'.

The z format character represents variable-length, null-terminated strings. If
the last field is z, the string is produced whether or not the null character is
present.

An exception is throw when all of the fields cannot be unpacked because the
buffer does not contain enough data.

Instance Properties

Trigger Examples

Device

The Device class enables you to retrieve device attributes and add custom metrics at
the device level.

Instance methods

The methods described in this section are present only on instances of the Device class.
The majority of the methods enable you to create device-level custom metrics, as shown in
the following example:

Flow.server.device.metricAddCount("slow_rsp", 1);

Note:

A device might sometimes act as a client and sometimes as a server on a flow.

Call a method as Device.metricAdd* to collect data for both device
roles.

Call a method as Flow.client.device.metricAdd* to collect data only
for the client role, regardless of whether the trigger is assigned to the client or the
server.

Call a method as Flow.server.device.metricAdd* to collect data only
for the server role, regardless of whether the trigger is assigned to the client or the
server.

Device(id: String)

Constructor for the Device object that accepts one parameter, which is a unique
16-character string ID.

If supplied with an ID from an existing Device object, the constructor creates a copy
of that object with all of the object properties, as shown in the followng
example:

Creates a custom top-leveldataset metric. Commits the metric data to the
specified application.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detaildataset metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detailsnapshot metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero,
positive signed 64-bit integer. A NaN value is silently
discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Instance properties

The following properties enable you to retrieve device attributes and are present only on
instances of the Device class.

cdpName: String

The CDP name associated with the device, if present.

dhcpName: String

The DHCP name associated with the device, if present.

discoverTime: Number

The last time the capture process discovered the device (not the original discovery
time), expressed in milliseconds since the epoch (January 1, 1970). Previously
discovered devices can be rediscovered by the capture process if they become idle and
later become active again, or if the capture process is restarted.

To direct a trigger
to run only on the initial discovery of a device, see the NEW_DEVICE
event discussed in the Discover class.

dnsNames: Array

An array of strings listing the DNS names associated with the device, if present.

hasTrigger: Boolean

The value is true if a trigger assigned to the Device object is
currently running.

If the trigger is running on an event associated with a Flow object, the hasTrigger property
value is true on at least one of the Device objects in the
flow.

The hasTrigger property is useful to distinguish device
roles. For example, if a trigger is assigned to a group of proxy servers, you can
easily determine whether a device is acting as the client or the server, rather than
checking for IP addresses or device IDs, such as in the following
example:

Flow

Flow refers to a conversation between two endpoints over a protocol such as TCP, UDP or
ICMP. The Flow class provides access to elements of these
conversations, such as endpoint IP addresses and age of the flow. The Flow class also contains a
flow store designed to pass objects from request to response on the same flow.

Note:

You can apply the Flow class on most L7 protocol events, but it is not supported on
session or datastore events.

Events

If a flow is associated with an ExtraHop-monitored L7 protocol,
events that correlate to the protocol will run in addition to flow events. For example, a
flow associated with HTTP will also run the
HTTP_REQUEST and HTTP_RESPONSE events.

FLOW_CLASSIFY

Runs whenever the ExtraHop system initially classifies a flow as being associated with
a specific protocol.

Note:

For TCP flows, the FLOW_CLASSIFY event runs
after the TCP_OPEN event.

Through a combination of L7
payload analysis, observation of TCP handshakes, and port number-based heuristics, the
FLOW_CLASSIFY event identifies the L7 protocol and the device roles
for the endpoints in a flow such as client/server or
sender/receiver.

The nature of a flow can change over its lifetime, for
example, tunneling over HTTP or switching from SMTP to SMTP-TLS. In these cases,
FLOW_CLASSIFY runs again after the protocol change.

The
FLOW_CLASSIFY event is useful for initiating an action on a flow
based on the earliest knowledge of flow information such as the L7 protocol,
client/server IP addresses, or sender/receiver ports.

Common actions initiated
upon FLOW_CLASSIFY include starting a packet capture through the
captureStart() method or associating the flow with an application
container through the addApplication() method.

Additional
options are available when you create a trigger that runs on this event. By default,
FLOW_CLASSIFY does not run upon flow expiration; however, you can
configure a trigger to do so in order to accumulate metrics for flows that were not
classified before expiring. See Advanced trigger options
for more information.

FLOW_DETACH

Runs when the parser has encountered an unexpected error or has run out of memory and
stops following the flow.

FLOW_DETACH can be used to detect malicious
content sent by clients and servers. The following is an
example of how a trigger can detect bad DNS responses upon
FLOW_DETACH
events:

Enables you to record information about a flow at timed intervals. Once
FLOW_CLASSIFY has run, the FLOW_RECORD event will
run every N seconds and whenever a flow closes. The default value for
N, known as the publish interval, is 30 minutes; the minimum value
is 60 seconds. You can set the publish interval from the ExtraHop Admin UI through the
Automatic Flow Record Settings.

FLOW_TICK

Enables you to record information about a flow per amount of data or per turn. The
FLOW_TICK event will run on every FLOW_TURN or every
128 packets, whichever occurs first. Also, L2 data is reset on
every FLOW_TICK event which enables you to add data together at each
tick. If counting throughput, collect data from FLOW_TICK events which
provide more complete metrics than
FLOW_TURN.

FLOW_TICK provides a means to
periodically check for certain conditions on the flow, such as zero windows and Nagle
delays, and then take an action, such as initiating a packet capture or sending a
syslog message.

Endpoints

Flow refers to a conversation between two endpoints over a protocol; an endpoint can be one
of the following components:

client

server

sender

receiver

The methods and properties described in this section are called or accessed for a specified
endpoint on the flow. For example, to access the device property from an
HTTP client, the syntax is Flow.client.device.

The endpoint that you specify depends on the events associated with the trigger. For
example, the ACTIVEMQ_MESSAGE event only supports sender and receiver
endpoints. The following table displays a list of events that can be associated with a flow
and the endpoints supported for each event:

Event

Client / Server

Sender / Receiver

AAA_REQUEST

yes

yes

AAA_RESPONSE

yes

yes

ACTIVEMQ_MESSAGE

no

yes

CIFS_REQUEST

yes

yes

CIFS_RESPONSE

yes

yes

DB_REQUEST

yes

yes

DB_RESPONSE

yes

yes

DHCP_REQUEST

yes

yes

DHCP_RESPONSE

yes

yes

DNS_REQUEST

yes

yes

DNS_RESPONSE

yes

yes

HTTP_REQUEST

yes

yes

HTTP_RESPONSE

yes

yes

IBMMQ_REQUEST

yes

yes

IBMMQ_RESPONSE

yes

yes

ICA_AUTH

yes

no

ICA_CLOSE

yes

no

ICA_OPEN

yes

no

ICA_TICK

yes

no

FIX_REQUEST

yes

yes

FIX_RESPONSE

yes

yes

FLOW_CLASSIFY

yes

no

FLOW_DETACH

yes

no

FLOW_TICK

yes

no

FLOW_TURN

yes

no

FTP_REQUEST

yes

yes

FTP_RESPONSE

yes

yes

HL7_REQUEST

yes

yes

HL7_RESPONSE

yes

yes

ICMP_MESSAGE

no

yes

KERBEROS_REQUEST

yes

yes

KERBEROS_RESPONSE

yes

yes

LDAP_REQUEST

yes

yes

LDAP_RESPONSE

yes

yes

MEMCACHE_REQUEST

yes

yes

MEMCACHE_RESPONSE

yes

yes

MONGODB_REQUEST

yes

yes

MONGODB_RESPONSE

yes

yes

MSMQ_MESSAGE

no

yes

NFS_REQUEST

yes

yes

NFS_RESPONSE

yes

yes

RTCP_MESSAGE

no

yes

RTP_CLOSE

no

yes

RTP_OPEN

no

yes

RTP_TICK

no

yes

SIP_REQUEST

yes

yes

SIP_RESPONSE

yes

yes

SMPP_REQUEST

yes

yes

SMPP_RESPONSE

yes

yes

SMTP_REQUEST

yes

yes

SMTP_RESPONSE

yes

yes

SSL_ALERT

yes

yes

SSL_CLOSE

yes

no

SSL_HEARTBEAT

yes

yes

SSL_OPEN

yes

no

SSL_PAYLOAD

yes

yes

SSL_RECORD

yes

yes

SSL_RENEGOTIATE

yes

no

TCP_CLOSE

yes

no

TCP_OPEN

yes

no

TCP_PAYLOAD

yes

yes

UDP_PAYLOAD

yes

yes

TELNET_MESSAGE

yes

yes

WEBSOCKET_OPEN

yes

no

WEBSOCKET_CLOSE

yes

no

WEBSOCKET_MESSAGE

yes

yes

Endpoint methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on a
FLOW_RECORD event. Record commits are not supported on
FLOW_CLASSIFY, FLOW_DETACH,
FLOW_TICK, or FLOW_TURN events.

On a flow,
traffic moves in each direction between two endpoints. The
commitRecord() method only records flow details in one
direction, such as from the client to the server. To record details about the
entire flow you must call commitRecord() twice, once for each
direction, and specify the endpoint in the syntax—for example,
Flow.client.commitRecord() and
Flow.server.commitRecord().

For built-in records, each
unique record is committed only once, even if the
commitRecord() method is called multiple times for the same
unique record.

To view the default properties committed to the record
object, see the record property below.

Endpoint properties

bytes: Number

The number of L4 payload bytes transmitted by a device. Specify the device role
in the syntax—for example, Flow.client.bytes or
Flow.receiver.bytes.

Access only on
FLOW_TICK or FLOW_TURN events or an error
will occur.

customDevices: Array

An array of custom devices in the flow. Specify the device role in the
syntax—for example, Flow.client.customDevices or
Flow.receiver.customDevices.

device: Device

The Device object associated with a device.
Specify the device role in the syntax. For example, to access the MAC address of
the client device, specify
Flow.client.device.hwaddr.

The number representing the last differentiated services code point (DSCP) value
of the flow packet.

Specify the device role in the syntax—for example,
Flow.client.dscp or
Flow.server.dscp.

dscpBytes: Array

An array that contains the number of L2 bytes for a specific Differentiated
Services Code Point (DSCP) value transmitted by a device in the flow. Specify the
device role in the syntax—for example, Flow.client.dscpBytes or
Flow.server.dscpBytes.

The value is zero for each entry that
has no bytes of the specific DSCP since the last FLOW_TICK
event.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

dscpName: String

The name associated with the DSCP value transmitted by a device in the flow. The
following table displays well-known DSCP names:

Number

Name

8

CS1

10

AF11

12

AF12

14

AF13

16

CS2

18

AF21

20

AF22

22

AF23

24

CS3

26

AF31

28

AF32

30

AF33

32

CS4

34

AF41

36

AF42

38

AF43

40

CS5

44

VA

46

EF

48

CS6

56

CS7

Specify the device role in the syntax—for example,
Flow.client.dscpName or
Flow.receiver.dscpName.

dscpPkts: Array

An array that contains the number of L2 packets for a given Differentiated
Services Code Point (DSCP) value transmitted by a device in the flow. Specify the
device role in the syntax—for example, Flow.client.dscpPkts or
Flow.server.dscpPkts.

The value is zero for each entry that
has no packets of the specific DSCP since the last FLOW_TICK
event.

Applies only to FLOW_TICK or
FLOW_TURN events.

fragPkts: Number

The number of packets resulting from IP fragmentation transmitted by a client or
server device in the flow. Specify the device role in the syntax—for example,
Flow.client.fragPkts or
Flow.server.fragPkts.

Access only on
FLOW_TICK or FLOW_TURN events or an error
will occur.

ipaddr: IPAddress

The IPAddress object associated with a device
in the flow. Specify the device role in the syntax—for example,
Flow.client.ipaddr or Flow.receiver.ipaddr.

The value is true if a TCP flow has been aborted through a TCP
reset (RST). The flow can be aborted by a device. If applicable, specify the
device role in the syntax—for example, Flow.client.isAborted or
Flow.receiver.isAborted.

This condition may be detected in
the TCP_CLOSE event and in any impacted L7 events (for example,
HTTP_REQUEST or DB_RESPONSE).

Note:

An L4 abort occurs when a TCP connection is closed with a RST instead of a
graceful shutdown.

An L7 response abort occurs when a connection closes while in the middle
of a response. This can be due to a RST, a graceful FIN shutdown, or an
expiration.

An L7 request abort occurs when a connection closes in the middle of a
request. This can also be due to a RST, a graceful FIN shutdown, or an
expiration.

isShutdown: Boolean

The value is true if the device initiated the shutdown of the
TCP connection. Specify the device role in the syntax—for example,
Flow.client.isShutdown or
Flow.receiver.isShutdown.

l2Bytes: Number

The number of L2 bytes, including the ethernet headers, transmitted by a device
in the flow. Specify the device role in the syntax—for example,
Flow.client.l2Bytes or
Flow.server.l2Bytes.

Access only on
FLOW_TICK or FLOW_TURN events or an error
will occur.

nagleDelay: Number

The number of Nagle delays associated with a device in the flow. Specify the
device role in the syntax—for example, Flow.client.nagleDelay or
Flow.server.nagleDelay.

Access only on
FLOW_TICK or FLOW_TURN events or an error
will occur.

payload: Buffer

The payload Buffer associated with a device
in the flow. Specify the device role in the syntax—for example,
Flow.client.payload or
Flow.receiver.payload.

Access only on
TCP_PAYLOAD, UDP_PAYLOAD, or
SSL_PAYLOAD events or an error will occur.

pkts: Number

The number of packets transmitted by a device in the flow. Specify the device
role in the syntax—for example, Flow.client.pkts or
Flow.server.pkts.

Access only on FLOW_TICK
or FLOW_TURN events or an error will occur.

port: Number

The port number associated with a device in the flow. Specify the device role in
the syntax—for example, Flow.client.port or
Flow.receiver.port.

rcvWndThrottle: Number

The number of receive window throttles sent from a device in the flow. Specify
the device role in the syntax—for example,
Flow.client.rcvWndThrottle or
Flow.server.rcvWndThrottle.

Access only on
FLOW_TICK or FLOW_TURN events or an error
will occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a
call to Flow.commitRecord on a FLOW_RECORD
event. The record object represents data from a single direction on the flow.

The record object contains the following default properties:

bytes (L3)

dscpName

first

last

pkts

proto

senderAddr

senderPort

receiverAddr

receiverPort

tcpFlags

Specify the device role in the syntax—for example,
Flow.client.record or
Flow.server.record.

Access the record object only on
FLOW_RECORD events or an error will occur.

rto: Number

The number of retransmission
timeouts (RTOs) associated with a device in the flow. Specify the device
role in the syntax—for example, Flow.client.rto or
Flow.server.rto.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

zeroWnd: Number

The number of zero windows sent from a device in the flow. Specify the device
role in the syntax—for example, Flow.client.zeroWnd or
Flow.server.zeroWnd.

Access only on
FLOW_TICK or FLOW_TURN events or an error
will occur.

Methods

addApplication(name: String, [turnTiming:
Boolean]): void

Creates an application with the specified name and collects L2-L4 metrics from the
flow. The application can be viewed from the Web UI and the metrics are displayed on an
L4 page in the application. A flow can be associated with one or more applications at a
given instant; the L2-L4 metrics collected by each application will be the
same.

Calling Flow.addApplication(name) on a
FLOW_CLASSIFY event is common on unsupported protocols. For flows
on supported protocols with L7 trigger events, it is recommended to call the
Application(name).commit() method, which collects a larger set of
protocol metrics.

The turnTiming flag is set to false by
default. If set to true, the ExtraHop system collects additional turn timing metrics
for the flow. If this flag is omitted, no turn timing metrics are recorded for the
application on the associated flow. Turn timing analysis analyzes L4 behavior in order
to infer L7 processing times when the monitored protocol follows a client-request,
server-response pattern and in which the client sends the first message. "Banner"
protocols (where the server sends the first message) and protocols where data flows in
both directions concurrently are not recommended for turn timing analysis.

captureStart(name: String, [options: Object]):
String

Initiates a Precision Packet Capture (PPCAP) for the flow and returns a unique
identifier of the packet capture in the format of a decimal number as a string. Returns
null if the packet capture fails to start.

name: String

The name of the packet capture file.

The maximum length is 256 characters

A separate capture is created for each flow.

Capture files with the same name are differentiated by timestamps.

options: Object

The options contained in the capture object. Omit any of the options to indicate
unlimited size for that option. All options apply to the entire flow except the
"lookback" options which apply only to the part of the flow before the trigger
event that started the packet capture.

maxBytes: Number

The total maximum number of bytes.

maxBytesLookback: Number

The total maximum number of bytes from the lookback buffer. The lookback
buffer refers to packets captured before the call to
Flow.captureStart().

maxDurationMSec: Number

The maximum duration of the packet capture, expressed in milliseconds.

maxPackets: Number

The total maximum number of packets. The maximum value might be exceeded
if the Trigger load is heavy.

maxPacketsLookback: Number

The maximum number of packets from the lookback buffer. The lookback
buffer refers to packets captured before the call to
Flow.captureStart().

The Flow.captureStart() function call requires that you have a
license for precision packet capture.

You can specify the number of bytes per packet (snaplen) you want to capture
when configuring the trigger in the ExtraHop Web UI. This option is available only
on some events. See Advanced trigger options for more
information.

Captured files are available in the ExtraHop Admin UI.

Once the packet capture drive is full, no new captures will be recorded until
the user deletes the files manually.

The maximum file name string length is 256 characters. If the name exceeds 256
characters, it will be truncated and a warning message will be visible in the
debug log, but the trigger will continue to execute.

The capture file size is the whichever maximum is reached first between the
maxPackets and maxBytes options.

The size of the capture lookback buffer is whichever maximum is reached first
between the maxPacketsLookback and
maxBytesLookback options.

Each passed max* parameter will capture up to the next packet
boundary.

If the packet capture was already started on the current flow,
Flow.captureStart() calls result in a warning visible in the
debug log, but the trigger will continue to run.

There is a maximum of 128 concurrent packet captures in the system. If that
limit is reached, subsequent calls to Flow.captureStart() will
generate a warning visible in the debug log, but the trigger will continue to
execute.

captureStop(): Boolean

Stops a packet capture that is in progress on the current flow.

commitRecord1(): void

Commits a record object to the ExtraHop Explore appliance that represents
data sent from device1 in a single direction on the flow.

You can
call this method only on FLOW_RECORD events, and each unique record
is committed only once for built-in records.

To view the properties committed to
the record object, see the record property below.

commitRecord2(): void

Commits a record object to the ExtraHop Explore appliance that represents
data sent from device2 in a single direction on the flow.

You can
call this method only on FLOW_RECORD events, and each unique record
is committed only once for built-in records.

To view the properties committed to
the record object, see the record property below.

findCustomDevice(deviceID: String): Device

Returns a single Device object that corresponds to
the specified deviceID parameter if the device is located on either side of the flow.
Returns null if no corresponding device is found.

getApplications(): String

Retrieves all applications associated with the flow.

Properties

The Flow object properties and methods discussed in this section are available to every L7
trigger event associated with the flow.

By default, the ExtraHop system uses loosely-initiated protocol classification, so it will
try to classify flows even after the connection was initiated. Loose initiation can be
turned off for ports that do not always carry the protocol traffic (e.g., the wildcard port
0). For such flows, device1, port1, and
ipaddr1 represent the device with the numerically lower IP address and
device2, port2, and ipaddr2 represent
the device with the numerically higher IP address.

age: Number

The time elapsed since the flow was initiated, expressed in seconds.

bytes1: Number

The number of L4 payload bytes transmitted by one of two devices in the flow; the
other device is represented by bytes2. The device represented by
bytes1 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

bytes2: Number

The number of L4 payload bytes transmitted by one of two devices in the flow; the
other device is represented by bytes1. The device represented by
bytes2 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

customDevices1: Array

An array of custom Device objects on a flow. Custom
devices on the other side of the flow are available by accessing
customDevices2. The device represented by
customDevices1 remains consistent for the flow.

customDevices2: Array

An array of custom Device objects on a flow. Custom
devices on the other side of the flow are available by accessing
customDevices1. The device represented by
customDevices2 remains consistent for the flow.

device1: Device

The Device object associated with one of two
devices in the flow; the other device is represented by device2. The
device represented by device1 remains consistent for the flow. For
example, Flow.device1.hwaddr accesses the MAC addresses of this device
in the flow.

The Device object associated with one of two
devices in the flow; the other device is represented by device1. The
device represented by device2 remains consistent for the flow. For
example, Flow.device2.hwaddr accesses the MAC addresses of this device
in the flow.

The number representing the last Differentiated Services Code Point (DSCP) value
transmitted by one of two devices in the flow; the other device is represented by
dscp2. The device represented by dscp1 remains
consistent for the flow.

dscp2: Number

The lnumber representing the last Differentiated Services Code Point (DSCP) value
transmitted by one of two devices in the flow; the other device is represented by
dscp1. The device represented by dscp2 remains
consistent for the flow.

dscpBytes1: Array

An array that contains the number of L2 bytes for a specific Differentiated Services
Code Point (DSCP) value transmitted by one of two devices in the flow; the other device
is represented by dscpBytes2. The device represented by
dscpBytes1 remains consistent for the flow.

The value is zero for
each entry that has no bytes of the specific DSCP since the last
FLOW_TICK event.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

dscpBytes2: Array

An array that contains the number of L2 bytes for a specific Differentiated Services
Code Point (DSCP) value transmitted by one of two devices in the flow; the other device
is represented by dscpBytes1. The device represented by
dscpBytes2 remains consistent for the flow.

The value is zero for
each entry that has no bytes of the specific DSCP since the last
FLOW_TICK event.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

dcspName1: String

The name associated with the DSCP value transmitted by one of two devices in the flow;
the other device is represented by dscpName2. The device represented by
dscpName1 remains consistent for the flow.

See the
dscpName property in the Endpoints section for a
list of supported DSCP code names.

dcspName2: String

The name associated with the DSCP value transmitted by one of two devices in the flow;
the other device is represented by dscpName1. The device represented by
dscpName2 remains consistent for the flow.

See the
dscpName property in the Endpoints section for a
list of supported DSCP code names.

dscpPkts1: Array

An array that contains the number of L2 packets for a given Differentiated Services
Code Point (DSCP) value transmitted by one of two devices in the flow; the other device
is represented by dscpPkts2. The device represented by
dscpPkts1 remains consistent for the flow.

The value is zero for
each entry that has no packets of the specific DSCP since the last
FLOW_TICK event.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

dscpPkts2: Array

An array that contains the number of L2 packets for a given Differentiated Services
Code Point (DSCP) value transmitted by one of two devices in the flow; the other device
is represented by dscpPkts1. The device represented by
dscpPkts2 remains consistent for the flow.

The value is zero for
each entry that has no packets of the specific DSCP since the last
FLOW_TICK event.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

fragPkts1: Number

The number of packets resulting from IP fragmentation transmitted by one of two
devices in the flow; the other device is represented by fragPkts2. The
device represented by fragPkts1 remains consistent for the
flow.

Access only on FLOW_TICK or FLOW_TURN events
or an error will occur.

fragPkts2: Number

The number of packets resulting from IP fragmentation transmitted by one of two
devices in the flow; the other device is represented by fragPkts1. The
device represented by fragPkts2 remains consistent for the
flow.

Access only on FLOW_TICK or FLOW_TURN events
or an error will occur.

id: String

The unique identifier of a Flow record.

ipaddr: IPAddress

TheIPAddress object associated with a device in the
flow. Specify the device role in the syntax—for example,
Flow.client.ipaddr or Flow.receiver.ipaddr.

The value is true if a TCP flow has been aborted through a TCP reset
(RST). The flow can be aborted by a device. If applicable, specify the device role in
the syntax—for example, Flow.client.isAborted or
Flow.receiver.isAborted.

This condition may be detected in the
TCP_CLOSE event and in any impacted L7 events (for example,
HTTP_REQUEST or DB_RESPONSE).

Note:

An L4 abort occurs when a TCP connection is closed with a RST instead of a
graceful shutdown.

An L7 response abort occurs when a connection closes while in the middle of a
response. This can be due to a RST, a graceful FIN shutdown, or an
expiration.

An L7 request abort occurs when a connection closes in the middle of a request.
This can also be due to a RST, a graceful FIN shutdown, or an expiration.

isExpired: Boolean

The value is true if the flow expired at the time of the event.

isShutdown: Boolean

The value is true if the device initiated the shutdown of the TCP
connection. Specify the device role in the syntax—for example,
Flow.client.isShutdown or
Flow.receiver.isShutdown.

l2Bytes1: Number

The number of L2 bytes, including the ethernet headers, transmitted by one of two
devices in the flow; the other device is represented by l2Bytes2. The
device represented by l2Bytes1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events or
an error will occur.

l2Bytes2: Number

The number of L2 bytes, including the ethernet headers, transmitted by one of two
devices in the flow; the other device is represented by l2Bytes1. The
device represented by l2Bytes2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events or
an error will occur.

l7proto: String

The L7 protocol associated with the flow. For known protocols, the property returns a
string representing the protocol name, such as HTTP, DB,
Memcache. For lesser-known protocols, the property
returns a string formatted as ipproto:port—tcp:13724
or udp:11258 For custom protocol names, the property returns a string
representing the name set through the Protocol Classification section in the Admin UI.

This property is not valid during TCP_OPEN events.

nagleDelay1: Number

The number of Nagle delays associated with one of two devices in the flow; the other
device is represented by nagleDelay2. The device represented by
nagleDelay1 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

nagleDelay2: Number

The number of Nagle delays associated with one of two devices in the flow; the other
device is represented by nagleDelay1. The device represented by
nagleDelay2 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

payload1: Buffer

The payload Buffer associated with one of two
devices in the flow; the other device is represented by payload2. The
device represented by payload1 remains consistent for the
flow.

Access only on TCP_PAYLOAD, UDP_PAYLOAD, and
SSL_PAYLOAD events or an error will occur.

payload2: Buffer

The payload Buffer associated with one of two
devices in the flow; the other device is represented by payload1. The
device represented by payload2 remains consistent for the
flow.

Access only on TCP_PAYLOAD, UDP_PAYLOAD, or
SSL_PAYLOAD events or an error will occur.

pkts1: Number

The number of packets transmitted by one of two devices in the flow; the other device
is represented by pkts2. The device represented by
pkts1 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

pkts2: Number

The number of packets transmitted by one of two devices in the flow; the other device
is represented by pkts1. The device represented by
pkts2 remains consistent for the flow.

Access only on
FLOW_TICK and FLOW_TURN events or an error will
occur.

port1: Number

The port number associated with one of two devices in a flow; the other device is
represented by port2. The device represented by port1
remains consistent for the flow.

port2: Number

The port number associated with one of two devices in a flow; the other device is
represented by port1. The device represented by port2
remains consistent for the flow.

rcvWndThrottle1: Number

The number of receive window throttles sent from one of two devices in the flow; the
other device is represented by rcvWndThrottle2. The device represented
by rcvWndThrottle1 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

rcvWndThrottle2: Number

The number of receive window throttles sent from one of two devices in the flow; the
other device is represented by rcvWndThrottle1. The device represented
by rcvWndThrottle2 remains consistent for the flow.

Access only on
FLOW_TICK or FLOW_TURN events or an error will
occur.

record1: Object

The record object committed to the ExtraHop Explore appliance through a call to
Flow.commitRecord1 on a FLOW_RECORD event.

The
object represents traffic sent in a single direction from one of two devices in the
flow; the other device is represented by the record2 property. The
device represented by the record1 property remains consistent for the
flow.

Access the record object only on FLOW_RECORD events or an
error will occur.

The record object contains the following default
properties:

bytes (L3)

dscpName

first

last

pkts

proto

senderAddr

senderPort

receiverAddr

receiverPort

tcpFlags

record2: Object

The record object committed to the ExtraHop Explore appliance through a call to
Flow.commitRecord2 on a FLOW_RECORD event.

The
object represents traffic sent in a single direction from one of two devices in the
flow; the other device is represented by the record1 property. The
device represented by the record2 property remains consistent for the
flow.

Access the record object only on FLOW_RECORD events or an
error will occur.

The record object contains the following default
properties:

bytes (L3)

dscpName

first

last

pkts

proto

senderAddr

senderPort

receiverAddr

receiverPort

tcpFlags

roundTripTime: Number

The median round-trip time (RTT) for the duration of the event, expressed in
milliseconds. The value is NaN if there are no RTT samples.

Access
only on FLOW_TICK or FLOW_TURN events or an error
will occur.

rto1: Number

The number of RTOs associated with one of two devices in the flow; the other device is
represented by rto2. The device represented by rto1
remains consistent for the flow.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

rto2: Number

The number of RTOs associated with one of two devices in the flow; the other device is
represented by rto1. The device represented by rto2
remains consistent for the flow.

Access only on FLOW_TICK or
FLOW_TURN events or an error will occur.

store: Object

The flow store is designed to pass objects from request to response on the same flow.
The store object is an instance of an empty JavaScript object. Objects
can be attached to the store as properties by defining the property key and property
value. For example:

Flow.store.myobject = "myvalue";

For events
that occur on the same flow, you can apply the flow store instead of the session table
to share information. For
example:

Flow store values persist across all requests and responses carried
on that flow. When working with the flow store, it is a best practice to set the flow
store variable to null when its value should not be conveyed to the
next request or response. This practice has the added benefit of conserving flow store
memory.

Most flow store triggers should have a structure similar to the
following
example:

FlowInterface

The FlowInterface class enables you to retrieve flow interface attributes and
to add custom metrics at the interface level.

Methods

FlowInterface(id: string)

A constructor for the FlowInterface object that accepts a flow interface ID. An error
occurs if the flow interface ID does not exist on the ExtraHop appliance.

Instance methods

The methods in this section enable you to create custom metrics on a flow interface. The
methods are present only on instances of the NetFlow
class. For example, the following statement collects metrics from NetFlow traffic on the
ingress interface:

NetFlow.ingressInterface.metricAddCount("slow_rsp", 1);

However, you can call the FlowInterface method as a static method on
NETFLOW_RECORD events. For example, the following statement collects
metrics from NetFlow traffic on both the ingress and egress interfaces:

Creates a custom top-leveldataset metric. Commits the metric data to the
specified application.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detaildataset metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detailsnapshot metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero,
positive signed 64-bit integer. A NaN value is silently
discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Instance properties

id: String

A string that uniquely identifies the flow interface.

number: Number

The flow interface number reported by the NetFlow record.

FlowNetwork

The FlowNetwork class enables you to retrieve flow network attributes and to add custom
metrics at the flow network level.

Methods

FlowNetwork(id: string)

A constructor for the FlowNetwork object that accepts a flow network ID. An error
occurs if the flow network ID does not exist on the ExtraHop appliance.

Instance methods

The methods in this section enable you to create custom metrics on a flow network. The
methods are present only on instances of the NetFlow
class. For example, the following statement collects metrics from NetFlow traffic on an
individual network:

NetFlow.network.metricAddCount("slow_rsp", 1);

However, you can call the FlowNetwork method as a static method on
NETFLOW_RECORD events. For example, the following statement collects
metrics from NetFlow traffic on both devices on the flow network:

Creates a custom top-leveldataset metric. Commits the metric data to the
specified application.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detaildataset metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Returns null in any field for which no data
is available, or returns a null object if all field data is
unavailable.

Note:

Calling this method in any trigger reserves 20 MB of total RAM,
not per trigger, on the ExtraHop Discover appliance and might impact
system performance. However, the memory is not reserved if the
getPreciseLocation method is called in any trigger.

In the
following code example, the getCountry method is called on each
specified event and retrieves rough location data for each client IP
address:

Creates a custom top-leveldataset metric. Commits the metric data to the
specified application.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Creates a custom detaildataset metric by which you can drill down.
Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is
silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive
signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences
of particular values in the dataset when set to the number of occurrences
specified by the val parameter. If no value is specified,
the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set
to true.

Trigger Examples

Session

The Session class provides access to the session table. It is designed to support
coordination across multiple independently executing triggers. The session table's global state
means any changes by a trigger or external process become visible to all other users of the
session table. Because the session table is in-memory, changes are not saved when you restart
the ExtraHop appliance or the capture process.

Session table entries can be evicted when the table grows too large or when the configured
expiration is reached.

Note:

The ExtraHop Command appliance cluster
nodes do not share their global states. The ECA does not run triggers; it only manages
them.

The ExtraHop Open Data Context API exposes the session table via the management
network, enabling coordination with external processes through the memcache protocol.

Events

The Session class is not limited only to the SESSION_EXPIRE event. You
can apply the Session class to any ExtraHop event.

SESSION_EXPIRE

Runs periodically (in approximately 30 second increments) as long as the session table
is in use. When the SESSION_EXPIRE event fires, keys that have expired in the previous
30 second interval are available through the Session.expiredKeys
property.

The SESSION_EXPIRE event is not associated with any
particular flow, so triggers on SESSION_EXPIRE events cannot commit
device metrics through Device.metricAdd* methods or
Flow.client.device.metricAdd* methods. To commit device metrics on
this event, you must add Device objects to the
session table through the Device() instance method.

Methods

add(key: String, value*, [options: Object]):
*

Adds the specified key in the session table. If the key is present, the corresponding
value is returned without modifying the key entry in the table. If the key is not
present, a new entry is created for the key and value, and the new value is
returned.

Returns the Options
object for the specified key. You configure options during calls to
Session.add(), Session.modify(), or
Session.replace().

increment(key: String, [count: Number]):
Number | Null

Looks up the specified key and increments the key value by the specified number. The
default count value is 1. Returns the new key value if the call is successful. Returns
null if the lookup fails. Returns an error if the key value is not a
number.

lookup(key: String): *

Looks up the specified key in the session table and returns the corresponding value.
Returns null if the key is not present.

modify(key: String, value: *, [options:
Object]): *

Modifies the specified key value, if the key is present in the session table, and
returns the previous value. If the key is not present, no new entry is created.

If
changes to the Options
object are included, the key options are updated. and old options are merged with new
ones. If the expire option is modified, the expiration timer is
reset.

remove(key: String): *

Removes the entry for the given key and returns the associated value.

replace(key: String, value: *, [options:
Object]): *

Updates the entry associated with the given key. If the key is present, update the
value and return the previous value. If the key is not present, add the entry and return
the previous value (null).

If changes to the Options object is
included, the key options are updated, and old options are merged with new ones. If
the expire option is provided, the expiration timer is
reset.

Options

expire: Number

The duration after which eviction occurrs, expressed in seconds. If the value is
null or undefined, the entry is evicted only when
the session table grows too large.

notify: Boolean

Indicates whether the key is available on SESSION_EXPIRE events. The
default value is false.

priority: String

Priority level that determines which entries to evict if the session table grows too
large. Valid values are PRIORITY_LOW, PRIORITY_NORMAL,
and PRIORITY_HIGH. The default value is
PRIORITY_NORMAL.

Constants

PRIORITY_LOW: Number

Default value is 0.

PRIORITY_NORMAL: Number

Default value is 1.

PRIORITY_HIGH: Number

Default value is 2.

Properties

expiredKeys :Array

An array of objects with the following properties:

age: Number

The age of the expired object, expressed in milliseconds. Age is the amount of
time elapsed between when the object in the session table was added or modified,
and the SESSION_EXPIRE event. The age determines whether the key
was evicted or expired.

name: String

The key of the expired object.

value: Number | String |
IPAddress | Boolean |
Device

The value of the entry in the session table.

Expired keys include keys that were evicted because the table grew too
large.

The expiredKeys property can be accessed only on
SESSION_EXPIREevents or an error will occur.

Trigger Examples

System

The System class enables you to access properties that identify the ExtraHop Discover appliance on which a trigger is
running. This information in useful in environments with multiple Discover appliances.

Properties

uuid: string

The universally unique identifier (UUID) of the ExtraHop Discover appliance.

ipaddr: IPAddress

The IPAddress object of the primary management
interface (Interface 1) on the ExtraHop Discover appliance.

hostname: string

The hostname for the ExtraHop Discover appliance configured in the
ExtraHop Admin UI.

Trigger

The Trigger class enables you to access details about a running trigger.

Properties

isDebugEnabled: boolean

The value is true if debugging is enabled for the trigger. The value
is determined by the state of the Enable Debugging checkbox in
the Trigger Configuration window of the ExtraHop Web UI.

VLAN

The VLAN class represents a VLAN on the network.

Instance properties

id: Number

The numerical ID for a VLAN.

Protocol and network data classes

The Trigger API classes in this section enable you to access properties and record
metrics from protocol, message, and flow activity that occurs on the ExtraHop
appliance.

AAA

The AAA (Authentication, Authorization, and Accounting) class
enables you to access properties and record metrics from AAA_REQUEST or
AAA_RESPONSE events.

Events

AAA_REQUEST

Runs when the ExtraHop system finishes processing an AAA request .

AAA_RESPONSE

Runs on every AAA response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on either an
AAA_REQUEST or AAA_RESPONSE event.

The event
determines which properties are committed to the record object. To view the default
properties committed on each event, see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

Properties

authenticator: String

The value of the authenticator field (RADIUS only).

avps:Array

avpLength: Number

The size of the AVP, expressed in bytes. This value includes the AVP header
data, as well as the value.

id: Number

The numeric ID of the attribute represented as an integer.

isGrouped: Boolean

The value is true if this is a grouped AVP (Diameter
only).

name: String

The name for the given AVP.

vendor: String

The vendor name for vendor AVPs (Diameter only).

value: String | Array |
Number

For single AVPs, a string or numeric value. For grouped AVPs (Diameter only), an
array of objects.

isDiameter: Boolean

The value is true if the request or response is Diameter.

isError: Boolean

The value is true if the response is an error. To retrieve the error
details in Diameter, check AAA.statusCode. To retrieve the error
details in RADIUS, check the AVP with code 18 (Reply-Message).

Access only on
AAA_RESPONSE events or an error will occur.

isRadius: Boolean

The value is true if the request or response is RADIUS.

isRspAborted: Boolean

The value is true if the AAA_RESPONSE event is
aborted.

Access only on AAA_RESPONSE events or an error will
occur.

method: Number

The method that corresponds to the command code in either RADIUS or Diameter.

The
following table contains valid Diameter command codes:

Command name

Abbr.

Code

AA-Request

AAR

265

AA-Answer

AAA

265

Diameter-EAP-Request

DER

268

Diameter-EAP-Answer

DEA

268

Abort-Session-Request

ASR

274

Abort-Session-Answer

ASA

274

Accounting-Request

ACR

271

Credit-Control-Request

CCR

272

Credit-Control-Answer

CCA

272

Capabilities-Exchange-Request

CER

257

Capabilities-Exchange-Answer

CEA

257

Device-Watchdog-Request

DWR

280

Device-Watchdog-Answer

DWA

280

Disconnect-Peer-Request

DPR

282

Disconnect-Peer-Answer

DPA

282

Re-Auth-Request

RAR

258

Re-Auth-Answer

RAA

258

Session-Termination-Request

STR

275

Session-Termination-Answer

STA

275

User-Authorization-Request

UAR

300

User-Authorization-Answer

UAA

300

Server-Assignment-Request

SAR

301

Server-Assignment-Answer

SAA

301

Location-Info-Request

LIR

302

Location-Info-Answer

LIA

302

Multimedia-Auth-Request

MAR

303

Multimedia-Auth-Answer

MAA

303

Registration-Termination-Request

RTR

304

Registration-Termination-Answer

RTA

304

Push-Profile-Request

PPR

305

Push-Profile-Answer

PPA

305

User-Data-Request

UDR

306

User-Data-Answer

UDA

306

Profile-Update-Request

PUR

307

Profile-Update-Answer

PUA

307

Subscribe-Notifications-Request

SNR

308

Subscribe-Notifications-Answer

SNA

308

Push-Notification-Request

PNR

309

Push-Notification-Answer

PNA

309

Bootstrapping-Info-Request

BIR

310

Bootstrapping-Info-Answer

BIA

310

Message-Process-Request

MPR

311

Message-Process-Answer

MPA

311

Update-Location-Request

ULR

316

Update-Location-Answer

ULA

316

Authentication-Information-Request

AIR

318

Authentication-Information-Answer

AIA

318

Notify-Request

NR

323

Notify-Answer

NA

323

The following table contains valid RADIUS command codes:

Command name

Code

Access-Request

1

Access-Accept

2

Access-Reject

3

Accounting-Request

4

Accounting-Response

5

Access-Challenge

11

Status-Server (experimental)

12

Status-Client (experimental)

13

Reserved

255

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN if the timing is invalid.

Access only on
AAA_RESPONSE events or an error will occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
AAA.commitRecord on either an AAA_REQUEST or
AAA_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

AAA_Request

AAA_Response

authenticator

authenticator

clientZeroWnd

clientZeroWnd

method

isError

reqBytes

isRspAborted

reqL2Bytes

method

reqPkts

processingTime

reqRTO

roundTripTime

serverZeroWnd

rspBytes

txId

rspL2Bytes

rspPkts

rspRTO

statusCode

serverZeroWnd

txId

reqBytes: Number

The number of application-level request bytes.

reqL2Bytes: Number

The number of request L2 bytes.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

Access only on AAA_REQUEST events or an
error will occur.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

rspBytes: Number

The number of application-level response bytes.

rspL2Bytes: Number

The number of response L2 bytes.

rspPkts: Number

The number of response packets.

rspRTO: Number

The number of response retransmission
timeouts (RTOs).

Access only on AAA_RESPONSE events or an
error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

statusCode: String

A string representation of the AVP identifier 268 (Result-Code).

Access only on
AAA_RESPONSE events or an error will occur.

txId: Number

A value that corresponds to the hop-by-hop identifier in Diameter and msg-id in
RADIUS.

ActiveMQ

The ActiveMQ class enables you to access properties and
record metrics from ACTIVEMQ_MESSAGE events. ActiveMQ is an implementation of
the Java Messaging Service (JMS).

Events

ACTIVEMQ_MESSAGE

Runs on every JMS message processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
ACTIVEMQ_MESSAGE event.

To view the default properties committed
to the record object, see the record property below.

For
built-in records, each unique record is committed only once, even if the
commitRecord() method is called multiple times for the same unique
record.

Properties

correlationId: String

The JMSCorrelationID field of the message.

expiration: Number

The JMSExpiration field of the message.

msg: Buffer

The message body. For TEXT_MESSAGE format messages, this returns the body of the
message as a UTF-8 string. For all other message formats, this returns the raw
bytes.

msgFormat: String

The message format. Possible values are:

BYTES_MESSAGE

MAP_MESSAGE

MESSAGE

OBJECT_MESSAGE

STREAM_MESSAGE

TEXT_MESSAGE

BLOG_MESSAGE

msgId: String

The JMSMessageID field of the message.

persistent: Boolean

The value is true if the JMSDeliveryMode is PERSISTENT.

priority: Number

The JMSPriority field of the message.

0 is the lowest priority.

9 is the highest priority.

0-4 are gradations of normal priority.

5-9 are gradations of expedited priority.

properties: Object

Zero or more properties attached to the message. The keys are arbitrary strings and
the values may be booleans, numbers, or strings.

queue: String

The JMSDestination field of the message.

receiverBytes: Number

The number of application-level bytes from the receiver.

receiverIsBroker: Boolean

The value is true if the flow-level receiver of the message is a
broker.

receiverL2Bytes: Number

The number of L2 bytes from the receiver.

receiverPkts: Number

The number of packets from the receiver.

receiverRTO: Number

The number of RTOs from the receiver.

receiverZeroWnd: Number

The number of zero windows sent by the receiver.

record: Object

The record object that was committed to the ExtraHop Explore appliance through a call to
ActiveMQ.commitRecord on an ACTIVEMQ_MESSAGE
event.

The record object contains the following default properties:

correlationId

expiration

msgFormat

msgId

persistent

priority

queue

receiverBytes

receiverIsBroker

receiverL2Bytes

receiverPkts

receiverRTO

receiverZeroWnd

redeliveryCount

replyTo

roundTripTime

senderBytes

senderIsBroker

senderL2Bytes

senderPkts

senderRTO

senderZeroWnd

timeStamp

totalMsgLength

redeliveryCount: Number

The number of redeliveries.

replyTo: String

The JMSReplyTo field of the message, converted to a string.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

senderBytes: Number

The number of application-level bytes from the sender.

senderIsBroker: Boolean

The value is true if the flow-level sender of the message is a
broker.

senderL2Bytes: Number

The number of L2 bytes from the sender.

senderPkts: Number

The number of packets from the sender.

senderRTO: Number

The number of RTOs from the sender.

senderZeroWnd: Number

The number of zero windows sent by the sender.

timeStamp: Number

The time when the message was handed off to a provider to be sent, expressed in GMT.
This is the JMSTimestamp field of the message.

totalMsgLength: Number

The length of the message, expressed in bytes.

CIFS

The CIFS class enables you to access properties and record metrics from
CIFS_REQUEST and CIFS_RESPONSE events.

Events

CIFS_REQUEST

Runs on every CIFS request processed by the device.

CIFS_RESPONSE

Runs on every CIFS response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on a
CIFS_RESPONSE event. Record commits on CIFS_REQUEST
events are not supported.

To view the default properties committed to the record
object, see the record property below.

For built-in records,
each unique record is committed only once, even if the commitRecord()
method is called multiple times for the same unique record.

Properties

Important:

Access time is the time it takes for a CIFS server to receive a
requested block. There is no access time for operations that do not access actual block data
within a file. Processing time is the time it takes for a CIFS server to respond to the
operation requested by the client, such as a metadata retrieval request.

There are no
access times for SMB2_CREATE. SMB2_CREATE creates a file that is referenced in the
response by an SMB2_FILEID. The referenced file blocks are then read from or written to
the NAS-storage device. These file read and write operations are calculated as access
times.

accessTime: Number

The amount of time taken by the server to access a file on disk, expressed in
milliseconds. For CIFS, this is the time from the first READ command in a CIFS flow
until the first byte of the response payload. The value is NaN if the
measurement or timing is invalid.

Access only on CIFS_RESPONSE events
or an error will occur.

encryptedBytes: Number

The number of encrypted bytes in the request or response.

error: String

The detailed error message recorded by the ExtraHop system.

Access only on
CIFS_RESPONSE events or an error will occur.

isCommandCreate: Boolean

The value is true if the message contains an SMB file creation
command.

isCommandDelete: Boolean

The value is true if the message contains an SMB DELETE command.

isCommandFileInfo: Boolean

The value is true if the message contains an SMB file info
command.

isCommandLock: Boolean

The value is true if the message contains an SMB locking
command.

isCommandRead: Boolean

The value is true if the message contains an SMB READ command.

isCommandRename: Boolean

The value is true if the message contains an SMB RENAME command.

isCommandWrite: Boolean

The value is true if the message contains an SMB WRITE command.

method: String

The CIFS method. Correlates to the methods listed under the CIFS metric in the
ExtraHop Web UI.

payload: Buffer

The Buffer object containing the payload bytes
starting from the READ or WRITE command in the CIFS message.

The buffer contains the
N first bytes of the payload, where N is the
number of payload bytes specified by the Bytes to Buffer field
when the trigger was configured through the ExtraHop WebUI. The default number of
bytes is 2048. For more information, see Advanced trigger options.

For larger volumes of payload
bytes, the payload might be spread across a series of READ or WRITE commands so that
no single trigger event contains the entire requested payload. You can reassemble the
payload into a single, consolidated buffer through the Flow.store and
payloadOffset properties.

payloadOffset: Number

The file offset, expressed in bytes, within the resource property.
The payload property is obtained from the resource property at the
offset.

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on CIFS_RESPONSE events or an error will
occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
CIFS.commitRecord on a CIFS_RESPONSE event.

The
record object contains the following default properties:

accessTime

clientZeroWnd

error

isCommandCreate

isCommandFileInfo

isCommandLock

isCommandRead

isCommandWrite

method

processingTime

reqSize

reqXfer

resource

rspBytes

rspXfer

serverZeroWnd

share

statusCode

user

warning

Access only on CIFS_RESPONSE events or an error will
occur.

reqBytes: Number

The number of L4 request bytes.

Access only on CIFS_RESPONSE events
or an error will occur.

reqL2Bytes: Number

The number of L2 request bytes.

Access only on
CIFS_RESPONSE events or an error will occur.

reqPkts: Number

The number of request packets.

Access only on CIFS_RESPONSE events
or an error will occur.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

Access only on CIFS_RESPONSE events or an
error will occur.

reqSize: Number

The size of the request payload, expressed in bytes.

reqTransferTime: Number

The request transfer time, expressed in milliseconds. If the request is contained in a
single packet, the transfer time is zero. If the request spans multiple packets, the
value is the amount of time between detection of the first CIFS request packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
CIFS request or a network delay. The value is NaN if there is no valid
measurement, or if the timing is invalid.

Access only on CIFS_REQUEST
events or an error will occur.

reqZeroWnd: Number

The number of zero windows in the request.

resource: String

The share, path, and filename, concatenated together.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
CIFS_RESPONSE events or an error will occur.

rspBytes: Number

The number of L4 response bytes.

Access only on CIFS_RESPONSE
events or an error will occur.

rspL2Bytes: Number

The number of L2 response bytes.

Access only on CIFS_RESPONSE
events or an error will occur.

rspPkts: Number

The number of response packets.

Access only on CIFS_RESPONSE events
or an error will occur.

rspRTO: Number

The number of response retransmission
timeouts (RTOs).

Access only on CIFS_RESPONSE events or an
error will occur.

rspSize: Number

The size of the response payload, expressed in bytes.

Access only on
CIFS_RESPONSE events or an error will occur.

rspTransferTime: Number

The response transfer time, expressed in milliseconds. If the response is contained in
a single packet, the transfer time is zero. If the response spans multiple packets, the
value is the amount of time between detection of the first CIFS response packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
CIFS response or a network delay. The value is NaN if there is no valid
measurement, or if the timing is invalid.

Access only on
CIFS_RESPONSE events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

share: String

The name of the share the user is connected to.

statusCode: Number

The numeric status code of the response (SMB2 only).

Access only on
CIFS_RESPONSE events or an error will occur.

user: String

The username, if available. In some cases, such as when the login event was not
visible or the access was anonymous, the username is not available.

Trigger Examples

DHCP

The DHCP class enables you to access properties and record
metrics from DHCP_REQUEST and DHCP_ RESPONSE
events.

Events

DHCP_REQUEST

Runs on every DHCP request processed by the device.

DHCP_RESPONSE

Runs on every DHCP response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on either
aDHCP_REQUEST or DHCP_RESPONSE event.

The event
determines which properties are committed to the record object. To view the default
properties committed on each event, see the record property below.

For built-in records, each unique record is committed only once, even if the
commitRecord() method is called multiple times for the same unique
record.

getOption(optionCode: Number): Object

Accepts a DHCP option code integer as input and returns an object containing the
following fields:

code: Number

The DHCP option code.

name: String

The DHCP option name.

payload: Number | String

The type of payload returned will be whatever the type is for that specific
option such as an IP address, an array of IP addresses, or a buffer object.

Returns null if the specified option code is not present in the
message.

Properties

clientReqDelay: Number

The time elapsed before the client attempts to acquire or
renew a DHCP lease, expressed in seconds.

Access only on DHCP_REQUEST
events or an error will occur.

error: String

The error message associated with option code 56. The value is null
if there is no error.

Access only on DHCP_RESPONSE events or an error
will occur.

gwAddr: IPAddress

The IP address used by routers to relay request and response messages.

htype: Number

The hardware type code.

msgType: String

The DHCP message type. Supported message types are:

DHCPDISCOVER

DHCPOFFER

DHCPREQUEST

DHCPDECLINE

DHCPACK

DHCPNAK

DHCPRELEASE

DHCPINFORM

DHCPFORCERENEW

DHCPLEASEQUERY

DHCPLEASEUNASSIGNED

DHCPLEASEUNKNOWN

DHCPLEASEACTIVE

DHCPBULKLEASEQUERY

DHCPLEASEQUERYDONE

offeredAddr: IPAddress

The IP address the DHCP server is offering or assigning to the client.

Access only on DHCP_RESPONSE events or an error
will occur.

options: Array of Objects

An array of objects with each object containing the following fields:

code: Number

The DHCP option code.

name: String

The DHCP option name.

payload: Number | String

The type of payload returned will be whatever the type is for that specific
option such as an IP address, an array of IP addresses, or a buffer object. IP
addresses will be parsed into an array but if the number of bytes is not divisible
by 4, it will instead be returned as a buffer.

processingTime: Number

The process time, expressed in milliseconds. The value is NaN on
malformed and aborted responses, or if the timing is invalid.

Access only on
DHCP_RESPONSE events or an error will occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
DHCP.commitRecord on either a DHCP_REQUEST or
DHCP_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

DHCP_REQUEST

DHCP_RESPONSE

clientReqDelay

msgType

gwAddr

error

htype

gwAddr

msgType

htype

reqBytes

offeredAddr

reqL2Bytes

processingTime

reqPkts

rspBytes

txId

rspL2Bytes

rspPkts

txId

reqBytes: Number

The number of request bytes.

Access only on DHCP_RESPONSE events or
an error will occur.

reqL2Bytes: Number

The number of request L2 bytes.

Access only on DHCP_RESPONSE events
or an error will occur.

reqPkts: Number

The number of request packets.

Access only on DHCP_RESPONSE events
or an error will occur.

rspBytes: Number

The number of L4 response bytes.

Access only on DHCP_RESPONSE
events or an error will occur.

rspL2Bytes: Number

The number of L2 response bytes.

Access only on DHCP_RESPONSE
events or an error will occur.

rspPkts: Number

The number of response packets.

Access only on DHCP_RESPONSE events
or an error will occur.

txId: Number

The transaction ID.

DICOM

The DICOM (Digital Imaging and Communications in Medicine)
class enables you to access properties and record metrics from DICOM_REQUEST
and DICOM_ RESPONSE events.

Events

DICOM_REQUEST

Runs on every DICOM request processed by the device.

DICOM_RESPONSE

Runs on every DICOM response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on a
DICOM_REQUEST or DICOM_RESPONSE event.

The event
determines which properties are committed to the record object. To view the default
properties committed on each event, see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

findElement(groupTag: Number, elementTag:
Number): Buffer

Returns a buffer that contains the DICOM data element specified by the passed group
and element tag numbers.

The data element is represented by a unique ordered pair of
integers that represent the group tag and element tag numbers. For example, the
ordered pair "0008, 0008" represents the "image type" element. A Registry of DICOM Data Elements and defined
tags is available at dicom.nema.org.

groupTag: Number

The first number in the unique ordered pair of integers that represent a
specific data element.

elementTag: Number

The second number in the unique ordered pair or integers that represent a
specific data element.

Properties

calledAETitle: String

The application entity (AE) title of the destination device or program.

Returns The value is true if the connection is closed before the
DICOM request is complete.

Access only on DICOM_REQUEST events or an
error will occur.

isRspAborted: Boolean

The value is true if the connection is closed before the DICOM
response is complete.

Access only on DICOM_RESPONSE events or an
error will occur.

methods: Array of Strings

An array of command fields in the message. Each command field specifies a DIMSE
operation name, such as N-CREATE-RSP.

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on DICOM_RESPONSE events or an error will
occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
DICOM.commitRecord on either a DICOM_REQUEST or
DICOM_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

DICOM_REQUEST

DICOM_RESPONSE

calledAETitle

calledAETitle

callingAETitle

callingAETitle

clientZeroWnd

clientZeroWnd

error

error

isReqAborted

isRspAborted

method

method

reqPDU

processingTime

reqSize

rspPDU

reqTransferTime

rspSize

serverZeroWnd

rspTransferTime

version

serverZeroWnd

version

reqBytes: Number

The number of application-level request bytes.

Access only on
DICOM_REQUEST events or an error will occur.

reqL2Bytes: Number

The number of L2 request bytes.

reqPDU: String

The Protocol Data Unit (PDU), or message format, of the request.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

reqSize: Number

The size of the request, expressed in bytes.

Access only on
DICOM_REQUEST events or an error will occur.

reqTransferTime: Number

The request transfer time, expressed in milliseconds.

Access only on
DICOM_REQUEST events or an error will occur.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
DICOM_RESPONSE events or an error will occur.

rspBytes: Number

The number of application-level response bytes.

Access only on
DICOM_RESPONSE events or an error will occur.

rspL2Bytes: Number

The number of L2 response bytes.

rspPDU: String

The Protocol Data Unit (PDU), or message format, of the response.

Access only on
DICOM_RESPONSE events or an error will occur.

rspPkts: Number

The number of response packets.

rspRTO: Number

The number of response retransmission
timeouts (RTOs).

rspSize: Number

The size of the response, expressed in bytes.

Access only on
DICOM_RESPONSE events or an error will occur.

rspTransferTime: Number

The response transfer time, expressed in milliseconds.

Access only on
DICOM_RESPONSE events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

version: Number

The DICOM version number.

DNS

The DNS class enables you to access properties and record
metrics from DNS_REQUEST and DNS_RESPONSE events.

Events

DNS_REQUEST

Runs on every DNS request processed by the device.

DNS_RESPONSE

Runs on every DNS response processed by the device.

Methods

answersInclude(term: String | IPAddress):
Boolean

Returns true if the specified term is present in a DNS response. For
string terms, the method checks both the name and data record in the answer section of
the response. For IPAddress terms, the method checks only the data record in the answer
section.

Can be called only on DNS_RESPONSE events.

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on a
DNS_REQUEST or DNS_RESPONSE event.

The event
determines which properties are committed to the record object. To view the default
properties committed on each event, see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

Properties

answers: Array

An array of objects corresponding to answer resource records.

Access only on
DNS_RESPONSE events or an error will occur.

The objects
contain the following properties:

data: String | IPAddress

The value of data depends on the type. The value is null for
unsupported record types. Supported record types include:

A

AAAA

NS

PTR

CNAME

MX

SRV

SOA

TXT

name: String

The record name.

ttl: Number

The time-to-live value.

type: String

The DNS record type.

typeNum: Number

The numeric representation of the DNS record type.

error: String

The name of the DNS error code, in accordance with IANA DNS parameters, recorded by
the ExtraHop system.

Returns OTHER for error codes that are unrecognized by the
system; however, errorNum specifies the numeric code value.

Access only on DNS_RESPONSE events or an error will
occur.

errorNum: Number

The numeric representation of the DNS error code in accordance with IANA DNS
parameters.

Access only on DNS_RESPONSE events or an error will
occur.

isAuthoritative: Boolean

The value is true if the authoritative answer is set in the
response.

Access only on DNS_RESPONSE events or an error will
occur.

isReqTimeout: Boolean

The value is true if the request timed out.

Access only on
DNS_REQUEST events or an error will occur.

isRspTruncated: Boolean

The value is true if the response is truncated.

Access only on
DNS_RESPONSE events or an error will occur.

opcode: String

The name of the DNS operation code in accordance with IANA DNS parameters. The
following codes are recognized by the ExtraHop system:

OpCode

Name

0

Query

1

IQuery (Inverse Query - Obsolete)

2

Status

3

Unassigned

4

Notify

5

Update

6-15

Unassigned

Returns OTHER for codes that are unrecognized by the system; however, the
opcodeNum property specifies the numeric code value.

opcodeNum: Number

The numeric representation of the DNS operation code in accordance with IANA DNS
parameters.

processingTime: Number

The server processing time, expressed in bytes. The value is NaN on
malformed and aborted responses, or if the timing is invalid.

Access only on
DNS_RESPONSE events or an error will occur.

qname: String

The hostname queried.

qtype: String

The name of the DNS request record type in accordance with IANA DNS parameters.

Returns OTHER for types that are unrecognized by the system; however, the
qtypeNum property specifies the numeric type value.

qtypeNum: Number

The numeric representation of the DNS request record type in accordance with IANA DNS
parameters.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
DNS.commitRecord on either a DNS_REQUEST or
DNS_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

DNS_REQUEST

DNS_RESPONSE

clientZeroWnd

answers

IsReqTimeout

clientZeroWnd

opcode

error

qname

isAuthoritative

qtype

isRspTruncated

reqBytes

opcode

reqL2Bytes

processingTime

reqPkts

qname

serverZeroWnd

qtype

rspBytes

rspL2Bytes

rspPkts

serverZeroWnd

reqBytes: Number

The number of application-level request bytes.

Access only on
DNS_REQUEST events or an error will occur.

reqL2Bytes: Number

The number of request L2 bytes.

Access only on DNS_REQUEST events
or an error will occur.

reqPkts: Number

The number of request packets.

Access only on DNS_REQUEST events or
an error will occur.

rspBytes: Number

The number of response bytes.

Access only on DNS_RESPONSE events or
an error will occur.

rspL2Bytes: Number

The number of response L2 bytes.

Access only on DNS_RESPONSE events
or an error will occur.

rspPkts: Number

The number of application-level response bytes.

Access only on
DNS_RESPONSE events or an error will occur.

FIX

The FIX class enables you to access properties and record
metrics from FIX_REQUEST and FIX_RESPONSE events.

Events

FIX_REQUEST

Runs on every FIX request processed by the device.

FIX_RESPONSE

Runs on every FIX response processed by the device.

Note:

FIX_RESPONSE is matched with request based on order ID. There is no
one-to-one correlation between request and response. There could be requests without a
response and sometimes data is pushed to the client. That
limits request data availability on response event, however the session table could be used
to solve any complex scenarios like submission order id, etc.

Method

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on either a
FIX_REQUEST or FIX_RESPONSE event.

The event
determines which properties are committed to the record object. To view the default
properties committed for each event see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

Properties

fields: Array

A list of FIX fields. Since they are text-based, the key-value protocol fields are
exposed as an array of objects with name and value properties containing strings. For
example:

Key
string representation is translated, if possible. With extensions, a numeric
representation is used. For example, it is not possible to determine 9178=0 (as seen
in actual captures). The key is instead translated to "9178". Fields are extracted
after message length and version fields are extracted all the way to the checksum
(last field). The checksum is not extracted.

For another example, the trigger
debug(JSON.stringify(FIX.fields)); shows the following
fields:

The record object committed to the ExtraHop Explore appliance through a call to
FIX.commitRecord on either an FIX_REQUEST or
FIX_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

FIX_REQUEST

FIX_RESPONSE

clientZeroWnd

clientZeroWnd

msgType

msgType

reqBytes

rspBytes

reqL2Bytes

rspL2Bytes

reqPkts

rspPkts

reqRTO

rspRTO

sender

sender

serverZeroWnd

serverZeroWnd

target

target

version

version

reqBytes: Number

The number of application-level request bytes.

reqL2Bytes: Number

The number of request L2 bytes.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request RTOs.

reqZeroWnd: Number

The number of zero windows in the request.

rspBytes: Number

The number of application-level response bytes.

rspL2Bytes: Number

The number of response L2 bytes.

rspPkts: Number

The number of response packets.

rspRTO: Number

The number of response RTOs.

rspZeroWnd: Number

The number of zero windows in the response.

sender: String

The value of the SenderCompID key.

target: String

The value of the TargetCompID key.

version: String

The protocol version.

FTP

The FTP class enables you to access properties and record metrics from
FTP_REQUEST and FTP_RESPONSE events.

Events

FTP_REQUEST

Runs on every FTP request processed by the device.

FTP_RESPONSE

Runs on every FTP response processed by the device.

Method

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
FTP_RESPONSE event. Record commits on FTP_REQUEST
events are not supported.

To view the default properties committed to the record
object, see the record property below.

For built-in records,
each unique record is committed only once, even if the commitRecord()
method is called multiple times for the same unique record.

Properties

args: String

The arguments to the command.

Access only on FTP_RESPONSE events or
an error will occur.

cwd: String

In the case of a user at /, when the client sends
"CWD
subdir":

FTP.cwd will be / when method == "CWD".

FTP.cwd will be /subdir for subsequent commands (rather than CWD becoming the
changed to directory as part of the CWD response trigger).

Includes "..." at the beginning of the path in the event of a resync or the path
is truncated.

Includes "..." at the end of the path if the path is too long.
Path truncates at 4096 characters.

Access only on FTP_RESPONSE
events or an error will occur.

error: string

The detailed error message recorded by the ExtraHop system.

Access only on
FTP_RESPONSE events or an error will occur.

isReqAborted: Boolean

The value is true the connection is closed before the FTP request was
complete.

isRspAborted: Boolean

The value is true if the connection is closed before the FTP response
was complete.

Access only on FTP_RESPONSE events or an error will
occur.

method: String

The FTP method.

path: String

The path for FTP commands. Includes "..." at the beginning of the path in the event of
a resync or the path is truncated. Includes "..." at the end of the path if the path is
too long. Path truncates at 4096 characters.

Access only on
FTP_RESPONSE events or an error will occur.

processingTime: Number

The server processing time, expressed in milliseconds (equivalent to
rspTimeToFirstPayload - reqTimeToLastByte). The
value is NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on FTP_RESPONSE events or an error will
occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
FTP.commitRecord on an FTP_RESPONSE event.

The
record object contains the following default properties:

args

clientZeroWnd

cwd

error

isReqAborted

isRspAborted

method

path

processingTime

reqBytes

reqL2Bytes

reqPkts

reqRTO

roundTripTime

rspBytes

rspL2Bytes

rspPkts

rspRTO

serverZeroWnd

statusCode

transferBytes

user

Access the record object only on FTP_RESPONSE events or an
error will occur.

reqBytes: Number

The number of L4 request bytes.

Access only on FTP_RESPONSE events
or an error will occur.

reqL2Bytes: Number

The number of L2 request bytes.

Access only on
FTP_RESPONSE events or an error will occur.

reqPkts: Number

The number of request packets.

Access only on FTP_RESPONSE events
or an error will occur.

reqRTO: Number

The number of request RTOs.

Access only on FTP_RESPONSE events or
an error will occur.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
FTP_RESPONSE events or an error will occur.

rspBytes: Number

The number of L4 response bytes.

Access only on FTP_RESPONSE events
or an error will occur.

rspL2Bytes: Number

The number of L2 response bytes.

Access only on FTP_RESPONSE events
or an error will occur.

rspPkts: Number

The number of response packets.

Access only on FTP_RESPONSE events
or an error will occur.

rspRTO: Number

The number of response RTOs.

Access only on FTP_RESPONSE events or
an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

statusCode: Number

The FTP status code of the response.

Access only on FTP_RESPONSE
events or an error will occur.

The following codes are valid:

Code

Description

110

Restart marker replay.

120

Service ready in
nnn
minutes.

125

Data connection already open; transfer starting.

150

File status okay; about to open data connection.

202

Command not implemented, superfluous at this site.

211

System status, or system help reply.

212

Directory status.

213

File status.

214

Help message.

215

NAME system type.

220

Service ready for new user.

221

Service closing control connection.

225

Data connection open; no transfer in progress.

226

Closing data connection. Requested file action successful.

227

Entering Passive Mode.

228

Entering Long Passive Mode.

229

Entering Extended Passive Mode.

230

User logged in, proceed. Logged out if appropriate.

231

User logged out; service terminated.

232

Logout command noted, will complete when transfer done

250

Requested file action okay, completed.

257

"PATHNAME" created.

331

User name okay, need password.

332

Need account for login.

350

Requested file action pending further information.

421

Service not available, closing control connection.

425

Can't open data connection.

426

Connection closed; transfer aborted.

430

Invalid username or password.

434

Requested host unavailable.

450

Requested file action not taken.

451

Requested action aborted. Local error in processing.

452

Requested action not taken.

501

Syntax error in parameters or arguments.

502

Command not implemented.

503

Bad sequence of commands.

504

Command not implemented for that parameter.

530

Not logged in.

532

Need account for storing files.

550

Requested action not taken. File unavailable.

551

Requested action aborted. Page type unknown.

552

Requested file action aborted. Exceeded storage allocation.

553

Requested action not taken. File name not allowed.

631

Integrity protected reply.

632

Confidentiality and integrity protected reply.

633

Confidentiality protected reply.

10054

Connection reset by peer.

10060

Cannot connect to remote server.

10061

Cannot connect to remote server.
The connection is active refused.

10066

Directory not empty.

10068

Too many users, server is full.

transferBytes: Number

The number of bytes transferred over the data channel during an
FTP_RESPONSE event.

Access only on FTP_RESPONSE
events or an error will occur.

user: String

The user name, if available. In some cases, such as when login events are encrypted,
the user name is not available.

HL7

The HL7 class enables you to access properties and record
metrics from HL7_REQUEST and HL7_RESPONSE events.

Events

HL7_REQUEST

Runs on every HL7 request processed by the device.

HL7_RESPONSE

Runs on every HL7 response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
HL7_RESPONSE event. Record commits on HL7_REQUEST
events are not supported.

To view the default properties committed to the record
object, see the record property below.

For built-in records,
each unique record is committed only once, even if the commitRecord()
method is called multiple times for the same unique record.

Properties

ackCode: String

The two character acknowledgment code.

Access only on HL7_RESPONSE
events or an error will occur.

ackId: String

The identifier for the message being acknowledged.

Access only on
HL7_RESPONSE events or an error will occur.

msgId: String

The unique identifier for this message.

msgType: String

The entire message type field, including the msgId subfield.

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on HL7_RESPONSE events or an error will
occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
HL7.commitRecord on an HL7_RESPONSE event.

The
record object contains the following default properties:

ackCode

ackId

clientZeroWnd

msgId

msgType

roundTripTime

processingTime

serverZeroWnd

version

Access the record object only on HL7_RESPONSE events or an
error will occur.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
HL7_RESPONSE events or an error will occur.

segments: Array

An array of objects where each object is of type (name: XYZ, fields: array of
strings).

subfieldDelimiter: String

Supports non-standard field delimiters.

version: String

The version advertised in the MSH segment.

Note:

The amount of buffered data is limited by the following capture option:
("message_length_max": number)

HTTP

The HTTP class enables you to access properties and record metrics from
HTTP_REQUEST and HTTP_RESPONSE events.

Events

HTTP_REQUEST

Runs on every HTTP request processed by the device.

HTTP_RESPONSE

Runs on every HTTP response processed by the device.

Additional payload options are available when you create a trigger that runs on either of
these events. See Advanced trigger options for more
information.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
HTTP_RESPONSE event. Record commits on HTTP_REQUEST
events are not supported.

To view the default properties committed to the record
object, see the record property below.

For built-in records,
each unique record is committed only once, even if the commitRecord()
method is called multiple times for the same unique record.

findHeaders(name: String): Array

Allows access to HTTP header values and returns an array of header objects (with name
and value properties) where the names match the prefix of the string value. See Example: Access HTTP header attributes for more information.

parseQuery(String): Object

Accepts a query string and returns an object with names and values corresponding to
those in the query string as shown in the following
example:

Properties

age: Number

For HTTP_REQUEST events, the time from the first byte of the request
until the last seen byte of the request. For HTTP_RESPONSE events, the
time from the first byte of the request until the last seen byte of the response. The
time is expressed in milliseconds. Specifies a valid value on malformed and aborted
requests. The value is NaN on expired requests and responses, or if the
timing is invalid.

contentType: String

The value of the content-type HTTP header.

cookies: Array

An array of objects that represents cookies and contains properties such as "domain"
and "expires." The properties correspond to the attributes of each cookie as shown in
the following
example:

Corresponds to the order in which the headers appear on the wire. The returned
object has a name and a value property. Numeric properties are useful for
iterating over all the headers and disambiguating headers with duplicate names as
shown in the following
example:

Saving
HTTP.headers to the Flow store does not save all of the
individual header values. It is a best practice to save the individual header
values to the Flow store. Refer to the Flow
class section for details.

headersRaw: String

The unmodified block of HTTP headers, expressed as a string.

host: String

The value in the HTTP host header.

isDesync: Boolean

The value is true if the protocol parser became desynchronized due to
missing packets.

isEncrypted: Boolean

Specifies The value is true if the transaction is over secure
HTTP.

isPipelined: Boolean

The value is true if the transaction is pipelined.

isReqAborted: Boolean

The value is true if the connection is closed before the HTTP request
was complete.

isRspAborted: Boolean

The value is true if the connection is closed before the HTTP
response was complete.

Access only on HTTP_RESPONSE events or an
error will occur.

isRspChunked: Boolean

The value is true if the response is chunked.

Access only on
HTTP_RESPONSE events or an error will occur.

isRspCompressed: Boolean

The value is true if the response is compressed.

Access only on
HTTP_RESPONSE events or an error will occur.

isServerPush: Boolean

The value is true if the transaction is the result of a server
push.

method: String

The HTTP method of the transaction such as POST and GET.

origin: IPAddress | String

The value in the X-Forwarded-For or the true-client-ip header.

path: String

The path portion of the URI: /path/.

payload: Buffer

The Buffer object containing the raw payload bytes
of the event transaction. If the payload was compressed, the decompressed content is
returned.

The buffer contains the N first bytes of the payload,
where N is the number of payload bytes specified by the
Bytes to Buffer field when the trigger was configured through
the ExtraHop WebUI. The default number of bytes is 2048. For more information, see
Advanced trigger options.

The following script is
an example of HTTP payload
analysis:

/* Extract the user name based on a pattern "user=*&" from payload of a
login URI that has "auth/login" as a URI substring. */
if (HTTP.payload && /auth\/login/i.test(HTTP.uri)) {
var user = /user=(.*?)\&/i.exec(HTTP.payload);
if (user !== null) {
debug("user: " + user[1]);
}
}

Note:

If
two HTTP payload buffering triggers are assigned to the same device, the higher value
is used and the value of HTTP.payload will be the same for both
triggers.

processingTime: Number

The server processing time, expressed in milliseconds (equivalent to
rspTimeToFirstPayload - reqTimeToLastByte). The
value is NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on HTTP_RESPONSE events or an error will
occur.

query: String

The query string portion of the URI: query=string. This typically
follows the URL and is separated from it by a question mark. Multiple query strings are
separated by an ampersand (&) or semicolon (;) delimiter.

record: Object

The record object that was committed to the ExtraHop Explore appliance through a call to
HTTP.commitRecord on an HTTP_RESPONSE event.

The
record object contains the following default properties:

clientZeroWnd

contentType

host

isPipelined

isReqAborted

isRspAborted

isRspChunked

isRspCompressed

method

origin

query

referer

reqBytes

reqL2Bytes

reqPkts

reqRTO

reqSize

reqTimeToLastByte

roundTripTime

rspBytes

rspL2Bytes

rspPkts

rspRTO

rspSize

rspTimeToFirstHeader

rspTimeToFirstPayload

rspTimeToLastByte

rspVersion

serverZeroWnd

statusCode

thinkTime

title

processingTime

uri

userAgent

Access the record object only on HTTP_RESPONSE events or an
error will occur.

referer: String

The value in the HTTP referrer header.

reqBytes: Number

The number of L4 request bytes.

Access only on HTTP_RESPONSE events
or an error will occur.

reqL2Bytes: Number

The number of request L2 bytes.

Access only on
HTTP_RESPONSE events or an error will occur.

reqPkts: Number

The number of request packets.

Access only on HTTP_RESPONSE events
or an error will occur.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

Access only on HTTP_RESPONSE events or an
error will occur.

reqSize: Number

The size of the request payload, expressed in bytes. The size does not include
headers.

reqTimeToLastByte: Number

The time from the first byte of the request until the last byte of the request,
expressed in milliseconds. The value is NaN on expired requests and
responses, or if the timing is invalid.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median TCP round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
HTTP_RESPONSE events or an error will occur.

rspBytes: Number

The number of response L4 bytes.

Access only on HTTP_RESPONSE
events or an error will occur.

rspL2Bytes: Number

The number of response L2 bytes.

Access only on HTTP_RESPONSE
events or an error will occur.

rspPkts: Number

The number of response packets.

Access only on HTTP_RESPONSE events
or an error will occur.

rspRTO: Number

The number of response retransmission
timeouts (RTOs).

Access only on HTTP_RESPONSE events or an
error will occur.

rspSize: Number

The size of the response payload, expressed in bytes. The size does not include
headers.

Access only on HTTP_RESPONSE events or an error will
occur.

rspTimeToFirstHeader: Number

The time from the first byte of the request until the status line that precedes the
response headers, expressed in milliseconds. The value is NaN on
malformed and aborted responses, or if the timing is invalid.

Access only on
HTTP_RESPONSE events or an error will occur.

rspTimeToFirstPayload: Number

The time from the first byte of the request until the first payload byte of the
response, expressed in milliseconds. Returns zero value when the response does not
contain payload. The value is NaN on malformed and aborted responses,
or if the timing is invalid.

Access only on HTTP_RESPONSE events or
an error will occur.

rspTimeToLastByte: Number

The time from the first byte of the request until the last byte of the response,
expressed in milliseconds. The value is NaN on malformed and aborted
responses, or if the timing is invalid.

Access only on HTTP_RESPONSE
events or an error will occur.

rspVersion: String

The HTTP version of the response.

Access only on HTTP_RESPONSE
events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

statusCode: Number

The HTTP status code of the response.

Access only on HTTP_RESPONSE
events or an error will occur.

Note:

Returns a status code of 0 if no valid
HTTP_RESPONSE is received.

streamID: Number

The ID of the stream that transferred the resource. Because responses might be
returned out of order, this property is required for HTTP/2 transactions to match
requests with responses. The value is 1 for the HTTP/1.1 upgrade
request and null for previous HTTP versions.

title: String

The value in the title element of the HTML content, if present.

thinkTime: Number

The time elapsed between the server having transferred the response to the client and the client transferring a new request to the server,
expressed in milliseconds. The value is NaN if there is no valid
measurement.

Trigger Examples

ICA

The ICA class enables you to access properties and record metrics from
ICA_OPEN, ICA_AUTH, ICA_TICK, and
ICA_ CLOSE events.

Events

ICA_AUTH

Runs when the ICA authentication is complete.

ICA_CLOSE

Runs when the ICA session is closed.

ICA_OPEN

Runs immediately after the ICA application is initially loaded.

ICA_TICK

Runs periodically while the user interacts with the ICA application.

After the
ICA_OPEN event has run at least once, the ICA_TICK
event is run anytime latency is reported and returned by the
clientLatency or networkLatency properties
described below.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on either an
ICA_OPEN, ICA_TICK, or ICA_CLOSE
event. Record commits on ICA_AUTH events are not supported.

The event
determines which properties are committed to the record object. To view the default
properties committed for each event, see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

Properties

application: String

The name of the application being launched.

authDomain: String

The Windows authentication domain to which the user belongs.

channels: Array

An array of objects containing information about virtual channels observed since the
last ICA_TICK event.

Access only on ICA_TICK
events or an error will occur.

Each object contains
the following properties:

name: String

The name of the virtual channel.

description: String

The friendly description of the channel name.

clientBytes: Number

The number of bytes sent by the client for that
channel.

serverBytes: Number

The number of bytes sent by the server for the channel.

clientMachine: String

The name of the client machine. This is a name that is
advertised by the ICA client and is usually the hostname of the client machine.

clientBytes: Number

Upon an ICA_CLOSE event, the incremental number of application-level
client bytes observed since the last ICA_TICK event. Does not specify
the total number of bytes for the session.

Access only on ICA_CLOSE
or ICA_TICK
events or an error will occur.

clientCGPMsgCount: Number

The number of client CGP messages since the last ICA_TICK
event.

Access only on ICA_TICK
events or an error will occur.

clientLatency: Number

The latency of the client, expressed in milliseconds, as
reported by End User Experience Management (EUEM) beacon.

Client latency is reported
when a packet from the client on the EUEM channel reports the result of a single ICA
round-trip measurement.

Access only on ICA_TICK
events or an error will occur.

clientL2Bytes: Number

Upon an ICA_CLOSE event, the incremental number of L2 client bytes observed since the last ICA_TICK event. Does
not specify the total number of bytes for the session.

Access only on
ICA_CLOSE or ICA_TICK
events or an error will occur.

clientMsgCount: Number

The number of client messages since the last ICA_TICK event.

Access
only on ICA_TICK
events or an error will occur.

clientPkts: Number

Upon an ICA_CLOSE event, the incremental number of client packets
observed since the last ICA_TICK event. Does not specify the total
number of packets for the session.

Access only on ICA_CLOSE or
ICA_TICK
events or an error will occur.

clientRTO: Number

Upon an ICA_CLOSE event, the incremental number of client retransmission timeouts (RTOs) observed since
the last ICA_TICK event. Does not specify the total number of RTOs for
the session.

Access only on ICA_CLOSE or ICA_TICK
events or an error will occur.

clientZeroWnd: Number

The number of zero windows sent by the client.

Access only on
ICA_CLOSE or ICA_TICK
events or an error will occur.

clientType: String

The type of the ICA client which is the user-agent equivalent to ICA.

clipboardData: Buffer

The buffer object that contains raw data from the clipboard transfer.

The value is
null if the ICA_TICK event did not result from a
clipboard data transfer, or if or if the channel specified by the
tickChannel property is not a clipboard channel.

The maximum
number of bytes in the buffer is specified by the Clipboard Bytes to
Buffer field when the trigger was configured through the ExtraHop Web UI.
The default maximum object size is 1024 bytes. For more information, see the Advanced trigger options.

To determine the direction of
the clipboard data transfer, access this property through
Flow.sender, Flow.receiver,
Flow.client, or Flow.server.

Access only on
ICA_TICK events or an error will occur.

clipboardDataType: String

The type of data on the clipboard transfer. The following clipboard types are
supported:

TEXT

BITMAP

METAFILEPICT

SYMLINK

DIF

TIFF

OEMTEXT

DIB

PALLETTE

PENDATA

RIFF

WAVE

UNICODETEXT

EHNMETAFILE

OWNERDISPLAY

DSPTEXT

DSPBITMAP

DSPMETAFILEPICT

DSPENHMETAFILE

The value is null if the ICA_TICK event did
not result from a clipboard data transfer, or if or if the channel specified by the
tickChannel property is not a clipboard channel.

Access only
on ICA_TICK events or an error will occur.

frameCutDuration: Number

The frame cut duration, as reported by EUEM beacon.

Access only on
ICA_TICK events or an error will occur.

frameSendDuration: Number

The frame send duration, as reported by EUEM beacon.

Access only on
ICA_TICK events or an error will occur.

host: String

The host name of the Citrix server.

isAborted: Boolean

The value is true if the application fails to launch
successfully.

Access only on ICA_CLOSE events or an error will
occur.

isCleanShutdown: Boolean

The value is true if the application shuts down cleanly.

Access
only on ICA_CLOSE events or an error will occur.

isClientDiskRead: Boolean

The value is true if a file was read from the client disk to the
Citrix server. The value is null if the command is not a file
operation, or
if the
channel specified by the tickChannel property is not a file
channel.

Access only on ICA_TICK events or an error will
occur.

isClientDiskWrite: Boolean

The value is true if a file was written from the Citrix server to the
client disk. The value is null if the command is not a file operation,
or if the channel specified by the tickChannel property is not a file
channel.

Access only on ICA_TICK events or an error will
occur.

isEncrypted: Boolean

The value is true if the application is encrypted with RC5
encryption.

isSharedSession: Boolean

The value is true if the application is launched over an existing
connection.

launchParams: String

The string that represents the parameters.

loadTime: Number

The load time of the given application, expressed in milliseconds.

Note:

The load time
is recorded only for the initial application load. The ExtraHop system does not
measure load time for applications launched over existing sessions and instead reports
the initial load time on subsequent application loads. Choose
ICA.isSharedSession to distinguish between initial and subsequent
application loads.

loginTime: Number

The user login time, expressed in milliseconds.

Access only on
ICA_OPEN, ICA_CLOSE, or ICA_TICK
events or an error will occur.

Note:

The login time is recorded only for the
initial application load. The ExtraHop system does not measure login time for
applications launched over existing sessions and instead reports the initial login
time on subsequent application loads. Choose ICA.isSharedSession to
distinguish between initial and subsequent application loads.

networkLatency: Number

The current latency advertised by the client, expressed
in milliseconds.

Network latency is reported when a specific ICA packet from the
client contains latency information.

Access only on ICA_TICK
events or an error will occur.

payload: Buffer

The Buffer object containing the raw payload bytes
of the file that was read or written on the event.

The buffer contains the
N first bytes of the payload, where N is the
number of payload bytes specified by the Bytes to Buffer field
when the trigger was configured through the ExtraHop WebUI. The default number of
bytes is 2048. For more information, see Advanced trigger options.

The value is
null if the channel specified by the tickChannel
property is not a file channel.

Access only on ICA_TICK events
or an error will occur.

program: String

The name of the program, or application, that is being launched.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
ICA.commitRecord on either an ICA_OPEN,
ICA_TICK, or ICA_CLOSE event.

The event on which
the method was called determines which default properties the record object contains
as displayed in the following table:

ICA_CLOSE

ICA_OPEN

ICA_TICK

authDomain

authDomain

authDomain

clientBytes

clientMachine

clientL2Bytes

clientType

clientBytes

clientMachine

clientZeroWnd

clientCGPMsgCount

clientPkts

host

clientL2Bytes

clientRTO

isEncrypted

clientLatency

clientType

isSharedSession

clientMachine

clientZeroWnd

launchParams

clientMsgCount

host

loadTime

clientPkts

isAborted

loginTime

clientRTO

isCleanShutdown

program

clientType

isEncypted

serverZeroWnd

clientZeroWnd

isSharedSession

user

frameCutDuration

launchParams

frameSendDuration

loadTime

host

loginTime

isClientDiskRead

program

isClientDiskWrite

roundTripTime

isEncrypted

serverBytes

isSharedSession

serverL2Bytes

launchParams

serverPkts

loadTime

serverRTO

loginTime

serverZeroWnd

networkLatency

user

program

resource

roundTripTime

serverBytes

serverCGPMsgCount

serverL2Bytes

serverMsgCount

serverPkts

serverRTO

serverZeroWnd

tickChannel

user

Access the record object only on ICA_OPEN,
ICA_CLOSE, and ICA_TICK events or an error will
occur.

resource: String

The path of the file that was read or written on the event, if known. The value is
null if the channel specified by the tickChannel
property is not a file channel.

Access only on ICA_TICK events or an
error will occur.

resourceOffset: Number

The offset of the file that was read or written on the event, if known. The value is
null if the channel specified by the tickChannel
property is not a file channel.

Access only on ICA_TICK events or an
error will occur.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
ICA_CLOSE or ICA_TICK events or an error will
occur.

serverBytes: Number

Upon an ICA_CLOSE event, the incremental number of application-level
server bytes observed since the last ICA_TICK event. Does not specify
the total number of bytes for the session.

Access only on ICA_CLOSE
or ICA_TICK events or an error will occur.

serverCGPMsgCount: Number

The number of CGP server messages since the last ICA_TICK
event.

Access only on ICA_TICK events or an error will
occur.

serverL2Bytes: Number

Upon an ICA_CLOSE event, the incremental number of L2 server bytes
observed since the last ICA_TICK event. Does not specify the total
number of bytes for the session.

Access only on ICA_CLOSE or
ICA_TICK events or an error will occur.

serverMsgCount: Number

The number of server messages since the last ICA_TICK event.

Access
only on ICA_TICK events or an error will occur.

serverPkts: Number

Upon an ICA_CLOSE event, the incremental number of server packets
observed since the last ICA_TICK event. Does not specify the total
number of packets for the session.

Access only on ICA_CLOSE or
ICA_TICK events or an error will occur.

serverRTO: Number

Upon an ICA_CLOSE event, the incremental number of server retransmission timeouts (RTOs) observed since
the last ICA_TICK event. Does not specify the total number of RTOs for
the session.

Access only on ICA_CLOSE or ICA_TICK
events or an error will occur.

serverZeroWnd: Number

The number of zero windows sent by the server.

Access only on
ICA_CLOSE or ICA_TICK events or an error will
occur.

tickChannel: String

The name of the virtual channel that resulted in the current ICA_TICK
event. The following channels are supported:

CTXCLI: clipboard

CTXCDM: file

CTXEUE: end user experience monitoring

Access only on ICA_TICK events or an error will occur.

user: String

The name of the user, if available.

ICMP

The ICMP class enables you to access properties and record metrics from
ICMP_MESSAGE events.

Events

ICMP_MESSAGE

Runs on every ICMP message processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
ICMP_MESSAGE event.

To view the default properties committed to
the record object, see the record property below.

For built-in
records, each unique record is committed only once, even if the
commitRecord() method is called multiple times for the same unique
record.

Properties

gwAddr: IPAddress

For a redirect message, returns the address of the gateway to which traffic for the
network specified in the internet destination network field of the original datagram's
data should be sent. Returns null for all other messages.

Message

ICMPv4 Type

ICMPv6 Type

Redirect Message

5

n/a

hopLimit: Number

The ICMP packet time to live or hop count.

isError: Boolean

The value is true for message types in the following table.

Message

ICMPv4 Type

ICMPv6 Type

Destination Unreachable

3

1

Redirect

5

n/a

Source Quench

4

n/a

Time Exceeded

11

3

Parameter Problem

12

4

Packet Too Big

n/a

2

isQuery: Boolean

The value is true for message types in the following table.

Message

ICMPv4 Type

ICMPv6 Type

Echo Request

8

128

Information Request

15

n/a

Timestamp request

13

n/a

Address Mask Request

17

n/a

Router Discovery

10

151

Multicast Listener Query

n/a

130

Router Solicitation (NDP)

n/a

133

Neighbor Solicitation

n/a

135

ICMP Node Information Query

n/a

139

Inverse Neighbor Discovery Solicitation

n/a

141

Home Agent Address Discovery Solicitation

n/a

144

Mobile Prefix Solicitation

n/a

146

Certification Path Solicitation

n/a

148

isReply: Boolean

The value is true for message types in the following table.

Message

ICMPv4 Type

ICMPv6 Type

Echo Reply

0

129

Information Reply

16

n/a

Timestamp Reply

14

n/a

Address Mask Reply

18

n/a

Multicast Listener Done

n/a

132

Multicast Listener Report

n/a

131

Router Advertisement (NDP)

n/a

134

Neighbor Advertisement

n/a

136

ICMP Node Information Response

n/a

140

Inverse Neighbor Discovery Advertisement

n/a

142

Home Agent Address Discovery Reply Message

n/a

145

Mobile Prefix Advertisement

n/a

147

Certification Path Advertisement

n/a

149

msg: Buffer

A buffer object containing up to message_length_max bytes of the ICMP
message. The message_length_ max option is configured in the ICMP
profile in the running config.

The following running config example changes the ICMP
message_length_ max from its default of 4096 bytes to 1234
bytes:

The time to live, expressed in seconds. This is the length of time during which the
information in this frame is valid, starting with when the information is received.

Memcache

The Memcache class enables you to access properties and
record metrics from MEMCACHE_REQUEST and MEMCACHE_RESPONSE
events.

Events

MEMCACHE_REQUEST

Runs on every memcache request processed by the device.

MEMCACHE_RESPONSE

Runs on every memcache response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on either a
MEMCACHE_REQUEST or MEMCACHE_RESPONSE event.

The
event determines which properties are committed to the record object. To view the
default properties committed for each event, see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

Properties

accessTime: Number

The access time, expressed in milliseconds. Available only if the first key that was
requested produced a hit.

Access only on MEMCACHE_RESPONSE events or
an error will occur.

error: String

The detailed error message recorded by the ExtraHop system.

Access only on
MEMCACHE_RESPONSE events or an error will occur.

hits: Array

An array of objects containing the Memcache key and key size.

Access only on
MEMCACHE_RESPONSE events or an error will occur.

key: String | Null

The Memcache key for which this was a hit, if available.

size: Number

The size of the value returned for the key, expressed in bytes.

isBinaryProtocol: Boolean

The value is true if the request/response corresponds to the binary
version of the memcache protocol.

isNoReply: Boolean

The value is true if the request has the "noreply" keyword and
therefore should never receive a response (text protocol only).

Access only on
MEMCACHE_REQUEST events or an error will occur.

isRspImplicit: Boolean

The value is true if the response was implied by a subsequent
response from the server (binary protocol only).

Access only on
MEMCACHE_RESPONSE events or an error will occur.

method: String

The Memcache method as recorded in Metrics section of the ExtraHop Web UI.

misses: Array

An array of objects containing the Memcache key.

Access only on
MEMCACHE_RESPONSE events or an error will occur.

key: String | Null

The Memcache key for which this was a miss, if available.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
Memcache.commitRecord on either a MEMCACHE_REQUEST
or MEMCACHE_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

MEMCACHE_REQUEST

MEMCACHE_RESPONSE

clientZeroWnd

accessTime

isBinaryProtocol

clientZeroWnd

isNoReply

error

method

hits

reqBytes

isBinaryProtocol

reqL2Bytes

isRspImplicit

reqPkts

method

reqRTO

misses

reqSize

roundTripTime

serverZeroWnd

rspBytes

vbucket

rspL2Bytes

rspPkts

rspRTO

serverZeroWnd

statusCode

vbucket

reqBytes: Number

The number of application-level request bytes.

reqKeys: Array

An array containing the Memcache key strings sent with the request.

The value of the
reqKeys property is the same when accessed on either the
MEMCACHE_REQUEST or the MEMCACHE_RESPONSE
event.

reqL2Bytes: Number

The number of request L2 bytes.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request RTOs.

Access only on MEMCACHE_REQUEST events
or an error will occur.

reqSize: Number

The size of the request payload, expressed in bytes. The value is NaN
for requests with no playload, such as GET and DELETE.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

rspBytes: Number

The number of application-level response bytes.

rspL2Bytes: Number

The number of response L2 bytes.

rspPkts: Number

The number of response packets.

rspRTO: Number

The number of response RTOs.

Access only on MEMCACHE_RESPONSE
events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

statusCode: String

The Memcache status code. For the binary protocol, the ExtraHop system metrics prepend
the method to status codes other than NO_ERROR, but the statusCode
property does not. Refer to the examples for code that matches the behavior of the
ExtraHop system metrics.

Searches the NetFlow record and returns the specified field. Returns a null value if
the field is not in the record. If the optional enterpriseId argument
is included, the specified field is returned only if the enterprise ID is a match,
otherwise the method returns a null value.

hasField(field: Number): Boolean

Determines whether the specified field is in the NetFlow record.

Properties

age: Number

The amount of time elapsed, expressed in seconds, between the first
and last property values reported in the NetFlow record.

deltaBytes: Number

The number of L3 bytes in the flow since the last
NETFLOW_RECORD event.

deltaPkts: Number

The number of packets in the flow since the last NETFLOW_RECORD
event.

dscp: Number

The number representing the last differentiated services code point (DSCP) value of
the flow packet.

dscpName: String

The name associated with the DSCP value of the flow packet. The following table
displays well-known DSCP names:

The value of the IP precedence field associated with the DSCP of the flow packet.

ipproto: String

The IP protocol associated with the flow, such as TCP or UDP.

last: Number

The amount of time elapsed, expressed in milliseconds, since the epoch of the last
packet in the flow.

network: FlowNetwork

An object that identifies the FlowNetwork and
contains the following properties:

id: String

The identifier of the FlowNetwork.

ipaddr: IPAddress

The IP address of the FlowNetwork.

nextHop: IPAddress

The IP address of the next hop router.

receiver: Object

An object that identifies the receiver and contains the following properties:

asn: Number

The autonomous system number (ASN) of the destination device.

ipaddr: IPAddress

The IP address of the destination device.

prefixLength: Number

The number of bits in the prefix of the destination address.

port: Number

The TCP or UDP port number of the destination device.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
NetFlow.commitRecord on a NETFLOW_RECORD
event.

Note:

A null value is returned if the record contains one or more enterprise
fields.

The record object contains the following default properties:

age

dscpName

deltaBytes

deltaPkts

egressInterface

first

format

ingressInterface

last

network

networkAddr

nextHop

proto

receiverAddr

receiverAsn

receiverPort

receiverPrefixLength

senderAddr

senderAsn

senderPort

senderPrefixLength

tcpFlagName

tcpFlags

sender: Object

An object that identifies the sender and contains the following properties:

asn: Number

The autonomous system number (ASN) of the source device.

ipaddr: IPAddress

The IP address of the source device.

prefixLength: Number

The number of bits in the prefix of the source address.

port: Number

The TCP or UDP port number of the source device.

tcpFlagNames: Array

A string array of TCP flag names, such as SYN or ACK, found in the flow packets.

tcpFlags: Number

The bitwise OR of all TCP flags set on the flow.

templateID: Number

The ID of the template that is referred to by the record. Template IDs are applicable
only to IPFIX and NetFlow v9 records.

tos: Number

The type of service (ToS) number defined in the IP header.

NFS

The NFS class enables you to access properties and record metrics from
NFS_REQUEST and NFS_RESPONSE events.

Events

NFS_REQUEST

Runs on every NFS request processed by the device.

NFS_RESPONSE

Runs on every NFS response processed by the device

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
NFS_RESPONSE event. Record commits on NFS_REQUEST
events are not supported.

To view the default properties committed to the record
object, see the record property below.

For built-in records,
each unique record is committed only once, even if the commitRecord()
method is called multiple times for the same unique record.

Properties

accessTime: Number

The amount of time taken by the server to access a file on disk, expressed in
milliseconds. For NFS, it is the time from every non-pipelined READ and WRITE command in
an NFS flow until the payload containing the response is recorded by the ExtraHop
system. The value is NaN on malformed and aborted responses, or if the
timing is invalid or is not applicable.

Access only on NFS_RESPONSE
events or an error will occur.

authMethod: String

The method for authenticating users.

error:String

The detailed error message recorded by the ExtraHop system.

Access only on
NFS_RESPONSE events or an error will occur.

fileHandle: Buffer

The file handle returned by the server on LOOKUP, CREATE, SYMLINK, MKNOD, LINK, or
READDIRPLUS operations.

isCommandFileInfo: Boolean

The value is true for file info commands.

isCommandRead: Boolean

The value is true for READ commands.

isCommandWrite: Boolean

The value is true for WRITE commands.

method: String

The NFS method. Valid methods are listed under the NFS metric in the ExtraHop Web
UI.

offset: Number

The file offset associated with NFS READ and WRITE commands.

Access only on
NFS_REQUEST events or an error will occur.

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on NFS_RESPONSE events or an error will
occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
NFS.commitRecord on a NFS_RESPONSE event.

The
record object contains the following default properties:

accessTime

authMethod

clientZeroWnd

error

isCommandFileInfo

isCommandRead

isCommandWrite

isRspAborted

method

offset

processingTime

renameDirChanged

reqSize

reqXfer

resource

rspSize

rspXfer

serverZeroWnd

statusCode

txID

user

version

Access the record object only on NFS_RESPONSE events or an
error will occur.

renameDirChanged: Boolean

The value is true if a resource rename request includes a directory
move.

Access only on NFS_REQUEST events or an error will
occur.

reqBytes: Number

The number of L4 request bytes.

Access only on NFS_RESPONSE events
or an error will occur.

reqL2Bytes: Number

The number of L2 request bytes.

Access only on
NFS_RESPONSE events or an error will occur.

reqPkts: Number

The number of request packets.

Access only on NFS_RESPONSE events
or an error will occur.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

Access only on NFS_REQUEST events or an
error will occur.

reqSize: Number

The size of the request payload, expressed in bytes.

reqTransferTime: Number

The request transfer time, expressed in milliseconds. If the request is contained in a
single packet, the transfer time is zero. If the request spans multiple packets, the
value is the amount of time between detection of the first NFS request packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
NFS request or a network delay. The value is NaN if there is no valid
measurement, or if the timing is invalid.

Access only on NFS_REQUEST
events or an error will occur.

reqZeroWnd: Number

The number of zero windows in the request.

resource: String

The path and filename, concatenated together.

roundTripTime: Number

The median round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
NFS_RESPONSE events or an error will occur.

rspBytes: Number

The number of L4 response bytes.

Access only on NFS_RESPONSE events
or an error will occur.

rspL2Bytes: Number

The number of L2 response bytes.

Access only on NFS_RESPONSE events
or an error will occur.

rspPkts: Number

The number of response packets.

Access only on NFS_RESPONSE events
or an error will occur.

rspRTO: Number

The number of request retransmission
timeouts (RTOs).

Access only on NFS_RESPONSE events or an
error will occur.

rspSize: Number

The size of the response payload, expressed in bytes.

Access only on
NFS_RESPONSE events or an error will occur.

rspTransferTime: Number

The response transfer time, expressed in milliseconds. If the response is contained in
a single packet, the transfer time is zero. If the response spans multiple packets, the
value is the amount of time between detection of the first NFS response packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
NFS response or a network delay. The value is NaN if there is no valid
measurement, or if the timing is invalid.

Access only on NFS_RESPONSE
events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

statusCode: String

The NFS status code of the request or response.

txId: Number

The transaction ID.

user: String

The ID of the Linux user, formatted as uid:xxxx@ip_address.

version: Number

The NFS version.

POP3

The POP3 class enables you to access properties and record metrics from
POP3_REQUEST and POP3_RESPONSE events.

Events

POP3_REQUEST

Runs on every POP3 request processed by the device.

POP3_RESPONSE

Runs on every POP3 response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on a
POP3_RESPONSE event. Record commits on POP3_REQUEST
events are not supported.

To view the default properties committed to the record
object, see the record property below.

For built-in records,
each unique record is committed only once, even if the commitRecord()
method is called multiple times for the same unique record.

Properties

dataSize: Number

The size of the message, expressed in bytes.

Access only on
POP3_RESPONSE events or an error will occur.

error: String

The detailed error message recorded by the ExtraHop system.

Access only on
POP3_RESPONSE events or an error will occur.

isEncrypted: Boolean

The value is true if the transaction is over a secure POP3
server.

isReqAborted: Boolean

The value is true if the connection is closed before the POP3 request
was complete.

isRspAborted: Boolean

The value is true if the connection is closed before the POP3
response was complete.

Access only on POP3_RESPONSE events or an
error will occur.

method: String

The POP3 method such as RETR or DELE.

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on POP3_RESPONSE events or an error will
occur.

recipientList: Array

An array that contains a list of recipient addresses.

Access only on
POP3_RESPONSE events or an error will occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
POP3.commitRecord on a POP3_RESPONSE event.

The
record object contains the following default properties:

clientZeroWnd

dataSize

error

isEncrypted

isReqAborted

isRspAborted

method

processingTime

recipientList

reqSize

reqTimeToLastByte

rspSize

rspTimeToFirstByte

rspTimeToLastByte

sender

serverZeroWnd

statusCode

Access the record object only on POP3_RESPONSE events or an
error will occur.

reqBytes: Number

The number of L4 request bytes.

reqL2Bytes: Number

The number of L2 request bytes.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

reqSize: Number

The size of the request payload, expressed in bytes. The size does not include
headers.

reqTimeToLastByte: Number

The time from the first byte of the request until the last byte of the request,
expressed in milliseconds. The value is NaN on expired requests and
responses, or if the timing is invalid.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median TCP round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

Access only on
POP3_RESPONSE events or an error will occur.

rspBytes: Number

The number of L4 response bytes.

Access only on POP3_RESPONSE
events or an error will occur.

rspL2Bytes: Number

The number of response L2 bytes.

Access only on POP3_RESPONSE
events or an error will occur.

rspPkts: Number

The number of response packets.

Access only on POP3_RESPONSE events
or an error will occur.

rspRTO: Number

The number of response retransmission
timeouts (RTOs).

Access only on POP3_RESPONSE events or an
error will occur.

rspSize: Number

The size of the response payload, expressed in bytes. The size does not include
headers.

Access only on POP3_RESPONSE events or an error will
occur.

rspTimeToFirstByte: Number

The time from the first byte of the request until the furst byte of the response,
expressed in milliseconds. The value is NaN on malformed and aborted
responses, or if the timing is invalid.

Access only on POP3_RESPONSE
events or an error will occur.

rspTimeToLastByte: Number

The time from the first byte of the request until the last byte of the response,
expressed in milliseconds. The value is NaN on malformed and aborted
responses, or if the timing is invalid.

Access only on POP3_RESPONSE
events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

sender: String

The address of the sender of the message.

Access only on
POP3_RESPONSE events or an error will occur.

status: String

The POP3 status message of the response which can be OK,
ERR or NULL.

Access only on
POP3_RESPONSE events or an error will occur.

Redis

Remote Dictionary Server (Redis) is an open-source, in-memory data structure server.
The Redis class enables you to access properties and record metrics from
REDIS_REQUEST and REDIS_RESPONSE events.

Events

REDIS_REQUEST

Runs on every Redis request processed by the device.

REDIS_RESPONSE

Runs on every Redis response processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on either a
REDIS_REQUEST or REDIS_RESPONSE event.

The event
determines which properties are committed to the record object. To view the default
properties committed for each event, see the record property
below.

For built-in records, each unique record is committed only once, even if
the commitRecord() method is called multiple times for the same
unique record.

Properties

errors: Array

An array of detailed error messages recorded by the ExtraHop system.

Access only on
REDIS_RESPONSE events or an error will occur.

isReqAborted: Boolean

The value is true if the connection is closed before the Redis
request was complete.

isRspAborted: Boolean

The value is true if the connection is closed before the Redis
response was complete.

Access only on REDIS_RESPONSE events or an
error will occur.

method: String

The Redis method such as GET or KEYS.

payload: Buffer

The body of the response or request.

processingTime: Number

The server processing time, expressed in milliseconds. The value is
NaN on malformed and aborted responses, or if the timing is
invalid.

Access only on REDIS_RESPONSE events or an error will
occur.

record: Object

The record object committed to the ExtraHop Explore appliance through a call to
Redis.commitRecord on either an REDIS_REQUEST or
REDIS_RESPONSE event.

The event on which the method was called
determines which default properties the record object contains as displayed in the
following table:

REDIS_REQUEST

REDIS_RESPONSE

clientZeroWnd

clientZeroWnd

method

error

reqKey

method

reqSize

processingTime

reqTransferTime

reqKey

isReqAborted

rspSize

serverZeroWnd

rspTransferTime

isRspAborted

rspTimeToFirstByte

rspTimeToLastByte

serverZeroWnd

reqKey: Array

An array containing the Redis key strings sent with the request.

reqBytes: Number

The number of L4 request bytes.

reqL2Bytes: Number

The number of L2 request bytes.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request retransmission
timeouts (RTOs).

reqSize: Number

The size of the request payload, expressed in bytes. The size does not include
headers.

reqTransferTime: Number

The request transfer time, expressed in milliseconds. If the request is contained in a
single packet, the transfer time is zero. If the request spans multiple packets, the
value is the amount of time between detection of the first Redis request packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
Redis request or a network delay. The value is NaN if there is no valid
measurement, or if the timing is invalid.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median TCP round-trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.

rspBytes: Number

The number of L4 response bytes.

rspL2Bytes: Number

The number of response L2 bytes.

rspPkts: Number

The number of response packets.

rspRTO: Number

The number of response retransmission
timeouts (RTOs).

rspTransferTime: Number

The response transfer time, expressed in milliseconds. If the response is contained in
a single packet, the transfer time is zero. If the response spans multiple packets, the
value is the amount of time between detection of the first Redis response packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
Redis response or a network delay. The value is NaN if there is no
valid measurement, or if the timing is invalid.

Access only on
REDIS_RESPONSE events or an error will occur.

rspSize: Number

The size of the response payload, expressed in bytes. The size does not include
headers.

Access only on REDIS_RESPONSE events or an error will
occur.

rspTimeToFirstByte: Number

The time from the first byte of the request until the furst byte of the response,
expressed in milliseconds. The value is NaN on malformed and aborted
responses, or if the timing is invalid.

Access only on REDIS_RESPONSE
events or an error will occur.

rspTimeToLastByte: Number

The time from the first byte of the request until the last byte of the response,
expressed in milliseconds. The value is NaN on malformed and aborted
responses, or if the timing is invalid.

Access only on REDIS_RESPONSE
events or an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

RTCP

The RTCP class enables you to access properties and record metrics from
RTCP_MESSAGE events.

Events

RTCP_MESSAGE

Runs on every RTCP UDP packet processed by the device.

Methods

commitRecord(): void

Commits a record object to the ExtraHop Explore appliance on an
RTCP_MESSAGE event.

To view the default properties committed to
the record object, see the record property below.

For built-in
records, each unique record is committed only once, even if the
commitRecord() method is called multiple times for the same unique
record.

Properties

callId: String

The Call ID for associating with a SIP flow.

packets: Array

An array of RTCP packet objects where each object represents a packet and contains a
packetType field. Each object has different fields based on the message type, as
described below.

packetType: String

The type of packet. If the packet type is not recognizable, then the
packetType will be "Unknown N" where N is the RTP control
packet type value.

Value

Type

Name

194

SMPTETC

SMPTE time-code mapping

195

IJ

Extended inter-arrival jitter report

200

SR

sender report

201

RR

receiver report

202

SDES

source description

203

BYE

goodbye

204

APP

application-defined

205

RTPFB

Generic RTP Feedback

206

PSFB

Payload-specific

207

XR

extended report

208

AVB

AVB RTCP packet

209

RSI

Receiver Summary Information

210

TOKEN

Port Mapping

211

IDMS

IDMS Settings

APP packet objects have the following fields:

name: String

The name chosen by the person defining the set of APP packets to be
unique. Interpreted as four case-sensitive ASCII characters.

ssrc: Number

The SSRC of the sender.

value: Buffer

The optional application-dependent data.

BYE packet objects have the following fields:

packetType: Number

Contains the number 203 to identify this as an RTCP BYE packet.

SR packet objects have the following fields:

ntpTimestamp: Number

The NTP timestamp, converted to milliseconds since the epoch (January 1,
1970).

reportBlocks: Array

An array of report objects which contain:

fractionLost: Number

The 8-bit number indicating the number of packets lost divided by
the number of packets expected.

jitter: Number

An estimate of the statistical variance of the RTP data packet
interarrival time, expressed in milliseconds.

lastSR: Number

The middle 32 bits of the ntp_Timestamp received as part of the
most recent RTCP sender report (SR) packet from the source SSRC. If
no SR has been received yet, this field is set to zero.

lastSRDelay: Number

The delay between receiving the last SR packet from the source
SSRC and sending this reception block, expressed in units of 1/65536
seconds. If no SR packet has been received yet, this field is set to
zero.

packetsLost: Number

The total number of RTP data packets from the source SSRC that
have been lost since the beginning of reception.

seqNum: Number

The highest sequence number received from the source SSRC.

ssrc: Number

The SSRC of the sender.

rtpTimestamp: Number

The RTP timestamp, converted to milliseconds since the epoch (January 1,
1970).

senderOctets: Number

The sender octet count.

senderPkts: Number

The sender packet count.

RR packet objects have the following fields:

reportBlocks: Array

An array of report objects which contain:

fractionLost: Number

The 8-bit number indicating the number of packets last divided by
the number of packets expected.

jitter: Number

An estimate of the statistical variance of the RTP data packet
interarrival, expressed in milliseconds.

lastSR: Number

The middle 32 bits of the ntp_Timestamp received as part of the
most recent RTCP sender report (SR) packet from the source SSRC. If
no SR has been received yet, this field is set to zero.

lastSRDelay: Number

The delay between receiving the last SR packet from the source
SSRC and sending this reception report block, expressed in units of
1/65536 seconds. If no SR packet has been received yet, this field
is set to zero.

packetsLost: Number

The total number of RTP data packets from the source SSRC that
have been lost since the beginning of reception.

seqNum: Number

The highest sequence number received from the source SSRC.

ssrc: Number

The SSRC of the sender.

ssrc: Number

The SSRC of the sender.

SDES packet objects have the following fields:

descriptionBlocks: Array

An array of objects that contain:

type: Number

The SDES type.

SDES Type

Abbrev.

Name

0

END

end of SDES list

1

CNAME

canonical name

2

NAME

user name

3

EMAIL

user's electronic mail address

4

PHONE

user's phone number

5

LOC

geographic user location

6

TOOL

name of application or tool

7

NOTE

notice about the source

8

PRIV

private extensions

9

H323-C ADDR

H.323 callable address

10

APSI

Application Specific Identifier

value: Buffer

A buffer containing the text portion of the SDES packet.

ssrc: Number

The SSRC of the sender.

XR packet objects have the following fields:

ssrc: Number

The SSRC of the sender.

xrBlocks: Array

An array of report blocks which contain:

statSummary: Object

Type 6 only. The statSummary object contains the
following properties:

beginSeq: Number

The beginning sequence number for the interval.

devJitter: Number

The standard deviation of the relative transit time between
each two packet series in the sequence interval.

devTTLOrHL: Number

The standard deviation of TTL or Hop Limit values of data
packets in the sequence number range.

dupPackets: Number

The number of duplicate packets in the sequence number
interval.

endSeq: Number

The ending sequence number for the interval.

lostPackets: Number

The number of lost packets in the sequence number
interval.

maxJitter: Number

The maximum relative transmit time between two packets in
the sequence interval, expressed in milliseconds.

maxTTLOrHL: Number

The maximum TTL or Hop Limit value of data packets in the
sequence number range.

meanJitter: Number

The mean relative transit time between two packet series in
the sequence interval, rounded to the nearest value
expressible as an RTP timestamp, expressed in
milliseconds.

meanTTLOrHL: Number

The mean TTL or Hop Limit value of data packets in the
sequence number range.

minJitter: Number

The minimum relative transmit time between two packets in
the sequence interval, expressed in milliseconds.

minTTLOrHL: Number

The minimum TTL or Hop Limit value of data packets in the
sequence number range.

ssrc: Number

The SSRC of the sender.

type: Number

The XR block type.

Block Type

Name

1

Loss RTE Report Block

2

Duplicate RLE Report Block

3

Packet Receipt Times Report Block

4

Receiver Reference Time Report Block

5

DLRR Report Block

6

Statistics Summary Report Block

7

VoIP Metrics Report Block

8

RTCP XP

9

Texas Instruments Extended VoIP Quality Block

10

Post-repair Loss RLE Report Block

11

Multicast Acquisition Report Block

12

IBMS Report Block

13

ECN Summary Report

14

Measurement Information Block

15

Packet Delay Variation Metrics Block

16

Delay Metrics Block

17

Burst/Gap Loss Summary Statistics Block

18

Burst/Gap Discard Summary Statistics Block

19

Frame Impairment Statistics Summary

20

Burst/Gap Loss Metrics Block

21

Burst/Gap Discard Metrics Block

22

MPEG2 Transport Stream PSI-Independent

Decodability Statistics Metrics Block

23

De-Jitter Buffer Metrics Block

24

Discard Count Metrics Block

25

DRLE (Discard RLE Report)

26

BDR (Bytes Discarded Report)

27

RFISD (RTP Flows Initial Synchronization
Delay)

28

RFSO (RTP Flows Synchronization Offset Metrics
Block)

29

MOS Metrics Block

30

LCB (Loss Concealment Metrics Block)

31

CSB (Concealed Seconds Metrics Block)

32

MPEG2 Transport Stream PSI Decodability Statistics
Block

typeSpecific: Number

The contents of this field depend on the block type.

value: Buffer

The contents of this field depend on the block type.

voipMetrics: Object

Type 7 only. The voipMetrics object contains the
following properties:

burstDensity: Number

The fraction of RTP data packets within burst periods since
the beginning of reception that were either lost or
discarded.

burstDuration: Number

The mean duration, expressed in milliseconds, of the burst
periods that have occurred since the beginning of
reception.

discardRate: Number

The fraction of RTP data packets from the source that have
been discarded since the beginning of reception, due to late
or early arrival, under-run or overflow at the receiving
jitter buffer.

endSystemDelay: Number

The most recently estimated end system delay, expressed in
milliseconds.

extRFactor: Number

The external R factor quality metric. A value of 127
indicates this parameter is unavailable.

gapDensity: Number

The fraction of RTP data packets within inter-burst gaps
since the beginning of reception that were either lost or
discarded.

gapDuration: Number

The mean duration of the gap periods that have occurred
since the beginning of reception, expressed in
milliseconds.

gmin: Number

The gap threshold.

jbAbsMax: Number

The absolute maximum delay, expressed in milliseconds, that
the adaptive jitter buffer can reach under worst case
conditions.

jbMaximum: Number

The current maximum jitter buffer delay, which corresponds
to the earliest arriving packet that would not be discarded,
expressed in milliseconds.

jbNominal: Number

The current nominal jitter buffer delay, which corresponds
to the nominal jitter buffer delay for packets that arrive
exactly on time, expressed in milliseconds.

lossRate: Number

The fraction of RTP data packets from the source lost since
the beginning of reception.