Custom Metrics

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 and 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).

   

    

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

   

    

   • 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 Type	Description
     Sum	Values sent within the given interval are summed into one data point
     Count	Number of hits received within the given interval are counted (equivalent to Sum, but providing a value of 1 per item)
     Min	Retains the minimum value received within a given interval
     Max	Retains the maximum value received within a given interval
     First	Retains the first value received within a given interval
     Last	Retains the last value received within a given interval
     Average	Maintains 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.

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