Custom Metrics

As of ThreatConnect 5.4, it is possible to create Custom Metrics which can be used to monitor and track important data points. A card for Custom Metrics can be created on the ThreatConnect dashboard to show the value(s) of a Metric. This documentation will detail how to retrieve, create, and delete Custom Metrics via the API.

Retrieving Custom Metrics

In order to view the Custom Metrics available to an Organization in ThreatConnect, use the following query:

GET /v2/customMetrics/

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "customMetricConfig": [
      {
        "id": 7,
        "name": "playbookRuns",
        "dataType": "Sum",
        "interval": "Hourly",
        "keyedValues": true,
        "description": "Monitor playbook runs."
      },
      {
        "id": 11,
        "name": "tasksCompleted",
        "dataType": "Sum",
        "interval": "Daily",
        "keyedValues": false,
        "description": "Track the number of tasks closed."
      }
    ]
  }
}

To view a specific metric, add the metric’s name to the end of the query as shown below:

GET /v2/customMetrics/{metricName}

Or, alternatively, you can use the ID of the metric to get the same result:

GET /v2/customMetrics/{metricId}

Creating a Custom Metric

To create a new custom metric, use a query in the following format:

POST /v2/customMetrics
{
  "name" : "newMetric",
  "dataType" : "Sum",
  "interval" : "Daily",
  "keyedValues" : false,
  "description" : "Testing API Updates"
}

JSON Response:

{
  "status": "Success",
  "data": {
    "customMetricConfig": {
      "id": 1234567,
      "name": "newMetric",
      "dataType": "Sum",
      "interval": "Daily",
      "keyedValues": false,
      "description": "Testing API Updates"
    }
  }
}

The following values are the available values for the dataType field in the body of the query above:

• Sum
• Count
• Min
• Max
• First
• Last
• Average

The following values are the available values for the interval field in the body of the query above:

• Hourly
• Daily
• Weekly
• Monthly
• Yearly

Creating Content in a Custom Metric

Note

When passing a “date” field into a request, use a timestamp in ISO format (e.g. 2018-10-19T14:44:00Z).

Creating Content in a Keyed Metric

To add content to a keyed metric, use a query in the following format:

POST /v2/customMetrics/{metricName}/data
{
  "name": "{metricKeyName}",
  "value": "{incrementValue}",
  "date": "{date}", //optional
  "weight": "{weight}" //optional and only needed for average
}

For example, the query below will add one to the value stored in the app1 key in a playbookRuns metric:

POST /v2/customMetrics/playbookRuns/data
{
  "name": "app1",
  "value": "1"
}

Creating Content in a Non-Keyed Metric

To add content to a non-keyed metric, use a query in the following format:

POST /v2/customMetrics/{metricName}/data
{
  "value": "{incrementValue}",
  "date": "{date}", //optional
  "weight": "{weight}" //optional and only needed for average
}

For example, the query below will add two to the count of a tasksCompleted metric:

POST /v2/customMetrics/tasksCompleted/data
{
  "value": "2",
  "date": "2018-01-19T14:44:00Z"
}

Custom Metrics Return Value

When creating a new entry in a metric, it is possible to view the current value by adding the ?returnValue=true flag to the query. For example, the query format below will increment the value of a non-keyed metric by two and return the current value of the metric:

POST /v2/customMetrics/{metricName}/data?returnValue=true
{
  "value": "{incrementValue}",
  "date": "{date}", //optional
  "weight": "{weight}" //optional and only needed for average
}

Here is a notional example that keeps track of how many tasks have been closed. The query below will add two to the tasksCompleted metric and will return the updated value of the metric:

POST /v2/customMetrics/tasksCompleted/data?returnValue=true
{
  "value": "2"
}

JSON Response:

{
  "value": 2.0,
  "date": "2017-07-13T00:00:00Z"
}

Deleting a Custom Metric

To delete a custom metric, use a query in the following format:

DELETE /v2/customMetrics/{metricName}

Or, alternatively, you can use the ID of the metric to get the same result:

DELETE /v2/customMetrics/{metricId}