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.

1. Log in to the ExtraHop system through https://<extrahop-hostname-or-IP-address>.
2. Click the System Settings icon and then click Metric Catalog.
3. Click the command menu and select Create Metric Manually.
4. In the Parameters section, complete the following steps to create the code that will be referenced by a trigger:
   1. 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.
      For example, a custom metric that collects the maximum number of HTTP responses by client might be specified as max_http_responses.by_client.
   2. 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.
   3. 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.
   4. 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.

5. In the Display section, complete the following steps to specify metric information that is searchable by users in the ExtraHop system:
   1. 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.
   2. (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.
   3. (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.
   4. (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.
6. (Optional): 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.
7. (Optional): 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.
   1. (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.
   2. (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.

8. 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.