Extract metrics through the REST API

You can extract metrics from an ExtraHop system through the REST API to visualize metrics in a third-party tool or compare ExtraHop data with other data you have collected. To extract a metric, you must first get identifiers for both the metrics you want to extract and the objects you want to extract metrics for. You can then build and test a metric query in the REST API Explorer before incorporating your request into a script that can read the metrics into a format that can be imported into applications.

Before you begin

  • You must log in to the ExtraHop system with an account that has unlimited privileges to generate an API key.
  • You must have a valid API key to make changes through the REST API and complete the procedures below. (See Generate an API key.)
  • Familiarize yourself with the ExtraHop REST API Guide to learn how to navigate the ExtraHop REST API Explorer.

Retrieve metric IDs

Metrics are identified in the ExtraHop REST API through a combination of the metric_category, the name, and the object_type. You can retrieve all three identifiers through the Metric Explorer.

  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. In the Type to filter field, type the name of the metric you want to extract and then click the name of the metric in the search results below.
  4. In the right pane, scroll down to REST API parameters and record the values.
    For example, the following information is displayed for the HTTP server responses metric:

Retrieve object IDs

Next, you must find the unique identifier for the object that you want to extract metrics for in the REST API. You can retrieve this ID through the REST API Explorer.

Important:The REST API Explorer is not available on Reveal(x) 360.
  1. In a browser, navigate to the REST API Explorer.
    The URL is the hostname or IP address of your ExtraHop system, followed by /api/v1/explore/. For example, if your hostname is seattle-eda, the URL is https://seattle-eda/api/v1/explore/.
  2. Click Enter API Key and then paste or type your API key into the API Key field.
  3. Click Authorize and then click Close.
  4. Click the type of object you want to collect metrics for, such as Device, Device Group, Application, or Appliance.
  5. Click GET /<objects>.
    For example, if you are extracting metrics for a device group, click Get/ Device Groups.
  6. Click Try it out.
  7. (Optional): In the Parameters section, specify search criteria for the object you want to locate.
    For example, you can search for object names, IP addresses, or MAC addresses. If you are having difficulty locating a device in the ExtraHop system, see Find a device.
  8. Click Send Request.
    In the Server response section, the Response Body displays information about each object that matches the search criteria.
  9. Note the number in the id field for the object you want to collect metrics for.
    For example, the id of the following server is 1298:
    [
      {
        "mod_time": 1516639693474,
        "node_id": null,
        "id": 1298,
        "extrahop_id": "fff4c3090a0a0000",
        "discovery_id": "fff4c3090a0a0000",
        "display_name": "server1",
        "description": null,
        "user_mod_time": 1512688149084,
        "discover_time": 1498685400000,
        "vlanid": 0,
        "parent_id": 140,
        "macaddr": "A1:01:01:01:1A:01",
        "vendor": "Mellanox",
        "is_l3": true,
        "ipaddr4": "10.10.10.200",
        "ipaddr6": null,
        "device_class": "node",
        "default_name": "Mellanox 10.10.10.200",
        "custom_name": "server1",
        "cdp_name": "",
        "dhcp_name": "server1.company.com",
        "netbios_name": "",
        "dns_name": "server1.company.com",
        "custom_type": "",
        "analysis_level": 1,
        "activity": []
      }
    ]

Query for metrics

You can query metrics through the REST API Explorer to make sure you have configured the right request body before adding the request to a script.

Important:The REST API Explorer is not available on Reveal(x) 360.
  1. In the REST API Explorer, click Assets, and then click POST /metrics.
  2. Click Try it out.
  3. In the body field, specify the metric that you want to extract.
    For example, the following body extracts five minute metrics on HTTP responses for a server with an ID of 1298:
    {
      "metric_category": "http_server",
      "metric_specs": [
        {
          "name": "rsp"
        }
      ],
      "object_type": "device",
      "object_ids": [
        1298
      ],
      "cycle": "5min"
    }

    The body must include the following parameters:

    object_type: The type of object you want to collect metrics for.

    object_ids: The id of the object you want to extract metrics for.

    metric_category: The category of the metric you want to collect.

    name: The name of the metric you want to collect.

    cycle: The aggregation period for metrics.

  4. Click Send Request to send the request to your ExtraHop system.
    In the Server response section, the Response body displays the requested metrics in JSON format.

Retrieve and run the example Python script

The ExtraHop GitHub repository contains an example Python script that extracts the total count of HTTP responses a server with an ID of 1298 sent over five minute time intervals and then writes the values to a CSV file.

Important:The example python script authenticates to the ExtraHop system through an API key, which is not compatible with the Reveal(x) 360 REST API. To run this script with Reveal(x) 360, you must modify the script to authenticate with API tokens. See the py_rx360_auth.py script in the ExtraHop GitHub repository for an example of how to authenticate with API tokens.
  1. Go to the ExtraHop code-examples GitHub repository and download the extract_metrics/extract_metrics.py file to your local machine.
  2. In a text editor, open the extract_metrics.py file and replace the following configuration variables with information from your environment:

    HOST: The IP address or hostname of the ExtraHop system.

    APIKEY: The API key.

  3. Run the following command:
    python3 extract_metrics.py
    Note:If the script returns an error message that the SSL certificate verification failed, make sure that a trusted certificate has been added to your ExtraHop system. Alternatively, you can add the verify=False option to bypass certificate verification. However, this method is not secure and not recommended. The following code sends an HTTP GET request without certificate verification:
    requests.get(url, headers=headers, verify=False)
Last modified 2023-11-07