Dynamic Thresholds API

Note

API Version: v1
Base URL: https://next.itrslab.com/dynamic-thresholds/api

The Dynamic Thresholds API provides endpoints for managing dynamic threshold configurations, monitoring their status, and retrieving application metadata. This API enables you to create and manage threshold configurations that can automatically detect anomalies in your metrics using various statistical methods.

Dynamic Thresholds API endpoints Copied

Application Copied

Get Application Metadata Copied

Returns application metadata including platform limits, settings, and timeouts.

GET /app/metadata

Tags: Application

Description: This is an unversioned endpoint with no guarantees of backward compatibility.

Parameters: None

Example Request:

curl -X GET "https://next.itrslab.com/dynamic-thresholds/api/app/metadata"

Example Response:

{
  "appConfig": {
    "rpc_timeout": "30s",
    "max_concurrent_platform_requests": 10,
    "max_metric_batch_size": 1000,
    "platform_lock_timeout": "5s",
    "max_outbound_message_size_mib": 10,
    "max_num_retries": 3,
    "max_num_configs": 100,
    "refresh_intervals": ["300s", "600s"],
    "threshold_metric_refresh_interval": "60s",
    "dry_run": {
      "rpc_timeout": "30s",
      "ttl": "3600s",
      "max_concurrent_platform_requests": 5,
      "is_cache_enabled": true,
      "cache_capacity": 1000,
      "platform_lock_timeout": "5s"
    }
  },
  "appBuildInfo": {
    "version": "1.0.0",
    "build_time": "2025-05-27T07:42:09Z",
    "commit_hash": "abc123",
    "branch_name": "main"
  }
}

Configuration Copied

Retrieve All Configurations Copied

Retrieves all configurations with optional filtering and pagination.

GET /v1/config

Tags: Configuration

Parameters:

Example Request:

curl -X GET "https://next.itrslab.com/dynamic-thresholds/api/v1/config?skip=0&limit=10&searchTerm=cpu"

Example Response:

{
  "configEntries": [
    {
      "config": {
        "name": "cpu-threshold",
        "sourceMetric": {
          "namespace": "itrsgroup.com/geneos",
          "name": "cpu_utilisation",
          "type": "METRIC_TYPE_GAUGE",
          "unit": "UNIT_PERCENT"
        },
        "deviation": {
          "header": {
            "lookbackModel": {
              "slidingWindow": {
                "size": "86400s"
              }
            },
            "refreshInterval": "300s"
          },
          "warningThreshold": {
            "header": {
              "sourceMetricValue": {
                "slidingWindow": {
                  "duration": "FIVE_MINUTES",
                  "aggregation": {
                    "function": "MEAN"
                  }
                }
              }
            },
            "stdDevFactor": {
              "greaterThan": 2.0
            }
          }
        }
      },
      "version": "1"
    }
  ],
  "numRemainingEntries": 50
}

Create or Update Configuration Copied

Creates a new configuration or updates an existing one.

POST /v1/config

Tags: Configuration

Request Body: UpsertConfigRequest

Example Request:

curl -X POST "https://next.itrslab.com/dynamic-thresholds/api/v1/config" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "name": "deviation",
      "sourceMetric": {
        "namespace": "itrsgroup.com/dynamic-thresholds/demo",
        "name": "memory_usage",
        "type": "METRIC_TYPE_GAUGE",
        "unit": "UNIT_PERCENT"
      },
      "filter": {
        "expression": {
          "comparison": {
            "name": "service",
            "value": "online_orders"
          }
        }
      },
      "deviation": {
        "header": {
          "lookbackModel": {
            "slidingWindow": {
              "size": "86400s"
            }
          },
          "refreshInterval": "300s"
        },
        "warningThreshold": {
          "header": {
            "sourceMetricValue": {
              "slidingWindow": {
                "duration": "FIVE_MINUTES",
                "aggregation": {
                  "function": "MEAN"
                }
              }
            }
          },
          "stdDevFactor": {
            "lessThan": 2.0,
            "greaterThan": 1.8
          }
        },
        "criticalThreshold": {
          "header": {
            "sourceMetricValue": {
              "slidingWindow": {
                "duration": "FIVE_MINUTES",
                "aggregation": {
                  "function": "MEAN"
                }
              }
            }
          },
          "stdDevFactor": {
            "greaterThan": 3.0
          }
        }
      }
    },
    "version": "1"
  }'

Example Response:

{
  "version": "2"
}

Get Configuration Status Copied

Retrieves the status of all configured thresholds.

GET /v1/config/status

Tags: Configuration

Parameters:

Example Request:

curl -X GET "https://next.itrslab.com/dynamic-thresholds/api/v1/config/status?name=deviation"

Example Response:

{
  "status": {
    "deviation": {
      "maxSeverity": "SEVERITY_CRITICAL",
      "status": {
        "severity": "SEVERITY_WARN",
        "message": "Failed to fetch source metric data"
      },
      "lastRefreshedAt": "2025-05-27T07:42:09Z",
      "nextRefreshAt": "2025-05-27T09:42:09Z",
      "thresholds": [
        {
          "key": {
            "severity": "THRESHOLD_SEVERITY_WARNING",
            "bound": "THRESHOLD_BOUND_UPPER"
          },
          "status": {
            "severity": "SEVERITY_CRITICAL",
            "message": "Failed to extract 'mean' from source metric statistics"
          }
        }
      ]
    }
  }
}

Get Specific Configuration Copied

Retrieves a specific configuration by its name.

GET /v1/config/{name}

Tags: Configuration

Parameters:

Example Request:

curl -X GET "https://next.itrslab.com/dynamic-thresholds/api/v1/config/deviation"

Example Response:

{
  "entry": {
    "config": {
      "name": "deviation",
      "sourceMetric": {
        "namespace": "itrsgroup.com/dynamic-thresholds/demo",
        "name": "memory_usage",
        "type": "METRIC_TYPE_GAUGE",
        "unit": "UNIT_PERCENT"
      },
      "filter": {
        "expression": {
          "comparison": {
            "name": "service",
            "value": "online_orders"
          }
        }
      },
      "deviation": {
        "header": {
          "lookbackModel": {
            "slidingWindow": {
              "size": "86400s"
            }
          },
          "refreshInterval": "300s"
        },
        "warningThreshold": {
          "header": {
            "sourceMetricValue": {
              "slidingWindow": {
                "duration": "FIVE_MINUTES",
                "aggregation": {
                  "function": "MEAN"
                }
              }
            }
          },
          "stdDevFactor": {
            "lessThan": 2.0,
            "greaterThan": 1.8
          }
        },
        "criticalThreshold": {
          "header": {
            "sourceMetricValue": {
              "slidingWindow": {
                "duration": "FIVE_MINUTES",
                "aggregation": {
                  "function": "MEAN"
                }
              }
            }
          },
          "stdDevFactor": {
            "greaterThan": 3.0
          }
        }
      }
    },
    "version": "1"
  }
}

Delete Configuration Copied

Deletes a configuration by its name and version.

DELETE /v1/config/{name}

Tags: Configuration

Parameters:

Example Request:

curl -X DELETE "https://next.itrslab.com/dynamic-thresholds/api/v1/config/deviation?version=1"

Example Response:

{}

API Information Copied

Get Supported API Versions Copied

Returns the supported API versions.

GET /versions

Tags: Info

Description: Used for client compatibility checks and API discovery.

Parameters: None

Example Request:

curl -X GET "https://next.itrslab.com/dynamic-thresholds/api/versions"

Example Response:

{
  "versions": ["v1"]
}

Schemas Copied

Any Copied

Represents any type of value that can be serialized.

Properties:

DeleteConfigResponse Copied

Response for a successful delete operation.

Properties:

This response contains no fields as the success is indicated by the absence of an error.

DeviationThreshold Copied

Defines a deviation-based threshold that monitors for values that deviate significantly from the historical mean, based on standard deviation calculations.

Properties:

DeviationThreshold_Threshold Copied

Defines a threshold based on standard deviation from the mean value.

Properties:

Dimension Copied

A single Entity dimension.

Properties:

EntityFilter Copied

An entity filter expressed as either an expression or an exact dimension filter.

Properties (One of):

Expression Copied

Represents an expression for entity filtering.

Properties:

GetApiVersionsResponse Copied

Response containing the list of supported API versions.

Properties:

GetAppMetadataResponse Copied

Response containing the application configuration settings.

Properties:

GetAppMetadataResponse_AppBuildInfo Copied

Build information of the application.

Properties:

GetAppMetadataResponse_AppConfig Copied

Application configuration settings.

Properties:

GetAppMetadataResponse_DryRunConfig Copied

Dry run configuration settings.

Properties:

GetConfigResponse Copied

Response containing the requested configuration entry.

Properties:

GetConfigsResponse Copied

Response containing a list of configurations that match the request criteria.

Properties:

GetStatusResponse Copied

Response containing the status of all configured threshold configurations.

Properties:

GetStatusResponse_ConfigStatus Copied

Detailed status information for a single threshold configuration.

Properties:

GoogleProtobufAny Copied

Contains an arbitrary serialized message along with a type that describes the serialized message.

Properties:

Note: This type also supports additional properties.

HistogramAggregation Copied

Defines how to aggregate histogram values within a time window.

Properties:

LatestHistogram Copied

Extracts a specific percentile value from the latest histogram data.

Properties:

LookbackModel Copied

Defines how far back in time to look for historical data when building a threshold model.

Properties (One of):

LookbackModel_FixedWindow Copied

Defines a fixed time window with specific start and end times.

Properties:

LookbackModel_SlidingWindow Copied

Defines a sliding window that moves with the current time.

Properties:

Metadata Copied

Metadata about creation and modification of a configuration.

Properties:

Metadata_User Copied

Information about a user who interacted with the configuration.

Properties:

MetricAggregation Copied

Defines how to aggregate metric values within a time window.

Properties:

MetricThreshold Copied

Defines a threshold based on another metric.

Properties:

MetricThreshold_Threshold Copied

Defines a threshold based on a relative percentage of another metric.

Properties:

ModelHeader Copied

Common header properties for dynamic threshold models.

Properties:

NamedAny Copied

Automatically-generated message used to represent maps of Any as ordered (name,value) pairs.

Properties:

NamespacedName Copied

Represents a namespaced name consisting of a namespace and name.

Properties:

OrderedDimensionsFilter Copied

A filter that exactly matches entity dimension keys and values, taking the order of dimensions into account.

Properties:

PercentileThreshold Copied

Defines a percentile-based threshold that monitors for values that deviate significantly from historical percentile values.

Properties:

PercentileThreshold_PercentileFactor Copied

Defines how to calculate the factor used in percentile-based thresholds.

Properties (One of):

PercentileThreshold_Threshold Copied

Defines the threshold configuration for a percentile-based model.

Properties:

SeasonalParams Copied

Parameters for seasonal models, which account for recurring patterns in data.

Properties:

SeasonalParams_SeasonalDuration Copied

Defines the duration for seasonal models.

Properties (One of):

SlidingWindow Copied

Defines a sliding window for calculating moving statistics over time.

Properties:

SourceMetric Copied

Represents a source metric that will be monitored by threshold configurations.

Properties:

SourceMetricValue Copied

Specifies how to extract a value from the source metric data.

Properties (One of):

StaticThreshold Copied

Defines a static threshold with fixed values.

Properties:

StaticThreshold_Threshold Copied

Defines a static threshold with a fixed value.

Properties:

Status Copied

Defines a logical error model suitable for different programming environments.

Properties:

ThresholdConfig Copied

Defines a complete threshold configuration that specifies how to monitor a source metric, what threshold algorithms to apply, and how to generate signals when thresholds are breached.

Properties:

ThresholdConfigEntry Copied

A configuration entry with its metadata and version information.

Properties:

ThresholdHeader Copied

Common header fields for threshold configurations.

Properties:

ThresholdValue Copied

Defines threshold boundary conditions that determine when a signal should be triggered.

Properties:

Note: At least one of lessThan or greaterThan must be set.

UnorderedDimensionsFilter Copied

A filter that exactly matches entity dimension keys and values, irrespective of the order of dimensions.

Properties:

UpsertConfigRequest Copied

Request to create or update a configuration.

Properties:

UpsertConfigResponse Copied

Response containing the version of the created or updated configuration.

Properties:

Error Handling Copied

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "title": "Bad Request",
  "message": "The metric name must be set",
  "details": {
    "type": "validation_error",
    "path": ".metric.name"
  }
}

Error Response Fields:

Unit Values Copied

Valid unit values for metrics:

• UNIT_NONE, UNIT_BYTES, UNIT_KILOBYTES, UNIT_KIBIBYTES
• UNIT_MEGABITS, UNIT_MEGABYTES, UNIT_MEBIBYTES
• UNIT_GIGABYTES, UNIT_GIBIBYTES, UNIT_TERABYTES, UNIT_TEBIBYTES
• UNIT_PETABYTES, UNIT_PEBIBYTES, UNIT_EXABYTES, UNIT_EXBIBYTES
• UNIT_BITS_PER_SECOND, UNIT_BYTES_PER_SECOND, UNIT_KIBIBYTES_PER_SECOND
• UNIT_MEGABITS_PER_SECOND, UNIT_GIGABITS_PER_SECOND
• UNIT_PER_SECOND, UNIT_SECONDS, UNIT_NANOSECONDS, UNIT_MICROSECONDS
• UNIT_MILLISECONDS, UNIT_MINUTES, UNIT_HOURS, UNIT_DAYS
• UNIT_DEGREES_CELSIUS, UNIT_HERTZ, UNIT_MEGAHERTZ, UNIT_GIGAHERTZ
• UNIT_FRACTION, UNIT_PERCENT, UNIT_CORES, UNIT_MILLICORES
• And many more currency, measurement, and specialized units…

Window Duration Values Copied

Valid window duration values:

• ONE_MINUTE, TWO_MINUTES, THREE_MINUTES, FIVE_MINUTES, TEN_MINUTES
• FIFTEEN_MINUTES, THIRTY_MINUTES, ONE_HOUR, THREE_HOURS, SIX_HOURS
• TWELVE_HOURS, ONE_DAY, THREE_DAYS, SEVEN_DAYS, FOURTEEN_DAYS
• THIRTY_DAYS, SIXTY_DAYS, NINETY_DAYS, ONE_HUNDRED_AND_EIGHTY_DAYS
• TEN_SECONDS, TWENTY_SECONDS, THIRTY_SECONDS