Custom Metrics
  • 24 Oct 2022
  • 3 Minutes to read
  • Dark
    Light

Custom Metrics

  • Dark
    Light

Article Summary

Minimum Role: Organization role of Organization Administrator (for creating custom metrics); an API user account with an Organization role of Standard User (for creating custom metrics and adding data to a custom metric)

Prerequisites: None

Overview

Custom metrics allow you to track data not available through other functionality. For example, you may want to know the number of times a particular Playbook was run. Data collected for custom metrics can be visualized on a dashboard with a User Metrics dashboard card.

This article describes how to create custom metrics on the Organization Settings screen with an Organization Administrator account, and via the ThreatConnect v2 API with an API user account. It also describes how you can add data to a custom metric.

Creating a Custom Metric

Organization Settings Screen

  1. Log into ThreatConnect with an Organization Administrator account.
  2. On the top navigation bar, hover the cursor over Settings A picture containing text, clipart, light  Description automatically generatedand select Org Settings. The Membership tab of the Organization Settings screen will be displayed.
  3. Click the Metrics tab. The Metrics screen will be displayed (Figure 1).

    Table  Description automatically generated

     

  4. Click the NEW METRIC button. The Configure Metric window will be displayed (Figure 2).

    Graphical user interface, application  Description automatically generated

     

    • Name: Enter a name for the new metric (up to 45 characters).
    • Data Type: Select the type of data to be run. Table 1 provides a description of each available data type.

       

      Data TypeDescription
      SumValues sent within the given interval are summed into one data point
      CountNumber of hits received within the given interval are counted (equivalent to Sum, but providing a value of 1 per item)
      MinRetains the minimum value received within a given interval
      MaxRetains the maximum value received within a given interval
      FirstRetains the first value received within a given interval
      LastRetains the last value received within a given interval
      AverageMaintains a running average of values received within a given interval
    • Interval: Select a time interval from which to create a single data point using the selected Data Type. Available options include Hourly, Daily, Weekly, Monthly, and Yearly. This selection is the time interval before the metric is reset, which starts on midnight of the day created for daily, midnight of the first of the month for monthly, etc.
    • Keyed Data Series: Select the checkbox to store the metric as an arbitrary number of key–value pairs. This feature is useful when tracking categorical information in which the categories are not known in advance. For example, this feature would be used when recording a metric of Incidents by status from an integrated ticketing system, where the key is status and the value is number of Incidents.
      Important
      When this checkbox is selected, any data added to the custom metric must include, in addition to the value, a key to identify multiple series of data within the metric. See the “Adding Metric Data” section for more information.
    • Description: Enter an optional description for the metric (up to 500 characters).

ThreatConnect API

Non-Keyed Metric

POST /v2/customMetrics
{
    "name": "dailyOccurrenceCount",
    "description": "A daily count of occurrences",
    "dataType": "Sum",
    "interval": "Daily",
    "keyedValues": false
}

Keyed Metric

POST /v2/customMetrics
{
    "name": "weeklyScoreAverage",
    "description": "A weekly average of scores",
    "dataType": "Average",
    "interval": "Weekly",
    "keyedValues": true
}

Adding Metric Data

After a custom metric is created, you can add data to it using the following methods:

  • Create a Playbook that uses the Add ThreatConnect Custom Metric or Add ThreatConnect Custom Keyed Metric Playbook Apps for custom non-keyed and keyed metrics, respectively.
  • Add a value to the custom non-keyed or keyed metric using v2 of the ThreatConnect API, as described in the following examples.

Non-Keyed Metric

On a given day, two POST requests are submitted as follows:

POST /v2/customMetrics/dailyOccurrenceCount
{
    "value": 13
}

POST /v2/customMetrics/dailyOccurrenceCount
{
    "value": 2
}

On the next day, three more POST requests are submitted as follows:

POST /v2/customMetrics/dailyOccurrenceCount
{
    "value": 1
}

POST /v2/customMetrics/dailyOccurrenceCount
{
    "value": 1
}

POST /v2/customMetrics/dailyOccurrenceCount
{
    "value": 7
}

Since dailyOccurrenceCount is a non-keyed metric with a Sum data type, the resulting metrics will display values of 15 for the first day and 9 for the second day.

Table 2 displays the results for all data types, using the same values included in the preceding POST requests.

 

Data TypeDay 1 ResultDay 2 Result
Sum159
Count23
Min21
Max137
First131
Last27
Average7.53.0

Keyed Metric

Adding data to a keyed metric (weeklyScoreAverage in this example) is similar to adding data to a non-keyed metric, except it requires a name parameter in the body of a POST request. This parameter acts as the key for the value, and it allows multiple series of data to be collected under the same metric.

For example, the following two POST requests are submitted within the same interval:

POST /v2/customMetrics/weeklyScoreAverage
{
    "value": 7,
    "name": "Jack"
}

POST /v2/customMetrics/weeklyScoreAverage
{
    "value": 11,
    "name": "Jill"
}

Instead of averaging the values, they are each kept separate in their own series, one for Jack and one for Jill. Then, the following POST request is submitted:

POST /v2/customMetrics/weeklyScoreAverage
{
    "value": 13,
    "name": "Jack"
}

This request affects Jack's (but not Jill's) value. Since this metric was defined earlier as an Average data type, Jack's value is now 10.


ThreatConnect® is a registered trademark of ThreatConnect, Inc.

200101-01 v.02.C


Was this article helpful?