Create a custom metric
In addition to analyzing built-in protocol metrics in the ExtraHop system, you can create your own custom metrics to collect specific information about your environment. Creating a custom metric requires two parts: specifying metric parameters in the Metric Catalog and building a trigger to discover, collect, and store custom metric data. In this topic, you will learn how to create a custom metric from the Metric Catalog.
By creating a custom metric from the Metric Catalog first, you can add the new metric to a dashboard or chart before custom metric data is collected. If you build a trigger for a custom metric first without specifying metric parameters, you might not be able to access the custom metric until data is observed and collected by the ExtraHop system.
|Note:||Custom metrics are only available in Advanced Analysis.|
The following steps show you how to create a custom metric with the Metric Catalog.
Before you beginBe aware that the parameters you specify in the Metric Catalog become part of the code that is referenced by a trigger. Parameters such as the metric name and metric type cannot be changed after creating the custom metric in the Metric Catalog. Before you create a custom metric or write a trigger, identify which events and devices are needed to extract the data you need and determine whether a solution already exists. For more information, see Triggers.
- Log in to the ExtraHop system through https://<extrahop-hostname-or-IP-address>.
- Click the System Settings icon and then click Metric Catalog.
- Click the command menu and select Create Metric Manually.
In the Parameters section, complete the following steps to
create the code that will be referenced by a trigger:
In the Metric field, type a unique name for your metric. The trigger
method that collects data for your custom metric must reference the
exact metric name that you specify in the Metric field. Avoid spaces
between words by typing underscores. When defining a detail metric name,
specify the detail key in the name by appending the metric name with
<key_name_without_spaces> is the key metric
For example, a custom metric that collects the maximum number of HTTP responses by client might be specified as max_http_responses.by_client.
- In the Source Type field, select a source, or class, from the drop-down list that you want to retrieve data from. For more information about these classes, see General purpose classes in the Trigger API Reference.
- In the Metric Type field, select an option from the drop-down list that specifies how data will be stored and viewed in the ExtraHop system. The Metric Type selection appears in triggers as part of the method name, such as metricAddCount or metricAddDataset. For more information, see ExtraHop data types in the Trigger API Reference.
- In the Type field, select one of the following options:
- Select Base Metric. A base, or top-level metric, includes the metric types, count, dataset. The Type selection appears in triggers as part of the method name, for example metricAddDataset.
- Select Detail Metric. A detail metric consists of key-value pairs, where the key is a string or IP address and the value is a top-level metric type such as a count or dataset metric. The Type selection appears in triggers as part of the method name, for example metricAddDetailDataset.
Important: Selections made in the Parameters section cannot be changed after you create the custom metric.
- In the Metric field, type a unique name for your metric. The trigger method that collects data for your custom metric must reference the exact metric name that you specify in the Metric field. Avoid spaces between words by typing underscores. When defining a detail metric name, specify the detail key in the name by appending the metric name with .by_<key_name_without_spaces>, where <key_name_without_spaces> is the key metric name.
In the Display section, complete the following steps to specify metric
information that is searchable by users in the ExtraHop system:
- In the Name field, type a user-friendly display name for your metric that is displayed in search results and charts in the ExtraHop system. You can include spaces in the display name.
- (Optional): In the Units field, select an option from the drop-down list if you know the unit of measure to display in a chart for your metric data.
- (Optional): In the Description field, type information that is displayed with search results for your metric in the ExtraHop system. The custom base metric description is automatically displayed for the detail metric in search results.
- (Optional): (For detail metrics only) In the Key Label field, type a display name for the set of keys in your metric. For example, you can create the key label, User Agent, for a custom metric that collects requests per HTTP user agent. Key labels do not need to be unique.
In the Detail Relationships section, complete one of the following steps if you
want to associate a custom base metric with a custom detail metric:
- (For base metrics) In the Detail Metrics field, click the field and search for a custom metric that you want users to view by drilling down from the custom metric. You can leave this blank if you do not want to provide drill-down data for your custom metric.
- (For detail metrics) In the Base Metric field, select a top-level metric from the drop-down list that you want to associate with your custom detail metric. You can leave this blank if you do not want to associate additional metrics with your custom metric.
In the Record Relationships section, click the RECORD TYPE drop-down list,
click one or more record types, and then click outside the list. Optionally, you
can filter the query results when you drill down on records for the custom
metric with the following fields.
- (Optional): In the SOURCE FILTER section, select the checkbox next to the source for this custom metric. This filter automatically queries for the source where you drill down from. For example, if you select a checkbox next to Server, when you query for records for this custom metric from a web server named example-web-sea, a filter is automatically added to your query that only returns results for transactions where example-web-sea is acting as the server.
- (Optional): In the ADDITIONAL FILTERS section, you can create advanced filters that query for records based on the specified criteria, or enter a regular expression (regex) to filter records for custom detail metrics.
Note: For more information, see Enable record queries for custom metrics.
When you are satisfied with the parameters, click
Create. Your custom metric parameters are added to the
ExtraHop system. REST API parameters for your metric appear in the Metric
Catalog. You can now search for your metric and add your metric to charts.
Important: You must build a trigger to discover, collect, and store custom metric data.
- To begin collecting data for your custom metric, build a trigger based on the custom metric parameters.
- Create a chart or dashboard featuring your custom metric.
- If you want to see custom metrics for a specific device, prioritize a group for Advanced Analysis or add the device to the watchlist.
Thank you for your feedback. Can we contact you to ask follow up questions?