API Gateway

Note
Version: 0.0.1
Base URL: https://your.iax.fqdn.com/obcerv-app-api-gateway/api

API Gateway provides a publicly accessible REST API to interact with the ITRS Analytics platform. Some apps require access to the API Gateway to provide functionality.

Public API endpoints Copied

Get Grouped Summary Statistics Copied

POST /analytics/grouped-summary-statistics

Returns summary statistics grouped by dimensions or attributes over a historical period.

The grouped summary statistics are calculated using a two-step process:

Map: Extracts a single statistic from every bucket
Reduce: Applies aggregation function across all extracted values to produce a single value

Parameters Copied

Parameter	Type	Location	Required	Description
`metric`	object	body	✓	The namespace and name of the metric
`entityFilter`	object	body		Filter to match entities
`from`	string (date-time)	body	✓	Starting inclusive timestamp
`to`	string (date-time)	body		Ending exclusive timestamp
`aggregations`	array	body	✓	List of unique aggregations to return
`unit`	string (enum)	body		Unit to return response in
`groupBy`	object	body	✓	Dimensions or attributes to group by

Example Request Copied

{
  "metric": {
    "namespace": "itrsgroup.com/c2/kubernetes-plugin",
    "name": "kube_container_cpu_limit"
  },
  "entityFilter": {
    "expression": {
      "comparison": {
        "name": "namespace",
        "value": "itrs"
      }
    }
  },
  "from": "2023-10-01T09:00:00Z",
  "aggregations": [
    {
      "map": {
        "function": "BUCKET_FUNCTION_LAST"
      },
      "reduce": {
        "function": "BUCKET_FUNCTION_SUM"
      }
    }
  ],
  "unit": "UNIT_MILLICORES",
  "groupBy": {
    "dimensions": ["node", "container"]
  }
}

Example Response Copied

{
  "unit": "UNIT_MILLICORES",
  "aggregations": [
    {
      "map": {
        "function": "BUCKET_FUNCTION_LAST"
      },
      "reduce": {
        "function": "BUCKET_FUNCTION_SUM"
      }
    }
  ],
  "groups": [
    {
      "values": [112521.0],
      "attributes": [
        {
          "namespace": "itrsgroup.com/c2/kubernetes-plugin",
          "name": "kubernetes.io/name",
          "value": "obcerv-operator"
        }
      ],
      "dimensions": [
        {
          "key": "pod",
          "value": "obcerv-operator"
        }
      ]
    }
  ]
}

Response Codes Copied

200 OK - Success
400 Bad Request - Invalid request parameters
404 Not Found - Metric not found

Get Seasonal Model Copied

POST /analytics/models/seasonal

Returns a seasonal model by aggregating buckets across integer multiples of the supplied periodicity.

A seasonal model aggregates buckets of size bucketSize for matching entities, combining buckets that are integer multiples of the periodicity apart.

Parameters Copied

Parameter	Type	Location	Required	Description
`seasonality`	object	body	✓	Length of a season (must be integer multiple of granularity)
`granularity`	object	body	✓	Granularity of returned buckets (must be factor of seasonality)
`window`	object	body	✓	Amount of source data used to generate the model
`functions`	object	body	✓	Aggregation functions to apply
`entityFilter`	object	body	✓	Entity filter for matching entities
`namespace`	string	body	✓	Metric namespace
`metric`	string	body	✓	Metric name
`timezone`	string	body		Timezone for daylight saving time adjustments
`calendarFilter`	string	body		Calendar name for filtering source data

Example Request Copied

{
  "seasonality": {
    "hours": 24
  },
  "granularity": {
    "hours": 1
  },
  "window": {
    "latestLookback": "2023-10-29T22:00:00Z",
    "seasonalPeriods": 7
  },
  "functions": {
    "functions": [
      {
        "bucketFunction": "BUCKET_FUNCTION_AVG"
      }
    ]
  },
  "entityFilter": {
    "expression": {
      "comparison": {
        "name": "hostname",
        "value": "server-01"
      }
    }
  },
  "namespace": "system.metrics",
  "metric": "cpu_usage"
}

Example Response Copied

{
  "value": {
    "aggregatedValues": {
      "values": [
        {
          "bucketFunction": "BUCKET_FUNCTION_AVG",
          "value": 45.2
        }
      ]
    },
    "bucketCount": 7
  },
  "footer": {
    "start": "2023-10-22T22:00:00Z",
    "unit": "UNIT_PERCENT"
  }
}

Response Codes Copied

200 OK - Success
400 Bad Request - Invalid request parameters
404 Not Found - Metric not found

Get Summary Statistics Copied

POST /analytics/summary-statistics

Returns summary statistics for one or more entities over a historical period using map-reduce aggregation.

Parameters Copied

Parameter	Type	Location	Required	Description
`metric`	object	body	✓	The namespace and name of the metric
`entityFilter`	object	body		Filter to match entities
`from`	string (date-time)	body	✓	Starting inclusive timestamp
`to`	string (date-time)	body		Ending exclusive timestamp
`aggregations`	array	body	✓	List of unique aggregations to return
`unit`	string (enum)	body		Unit to return response in

Example Request Copied

{
  "metric": {
    "namespace": "itrsgroup.com/c2/kubernetes-plugin",
    "name": "kube_container_cpu_limit"
  },
  "entityFilter": {
    "expression": {
      "comparison": {
        "name": "namespace",
        "value": "itrs"
      }
    }
  },
  "from": "2023-10-01T09:00:00Z",
  "aggregations": [
    {
      "map": {
        "function": "BUCKET_FUNCTION_LAST"
      },
      "reduce": {
        "function": "BUCKET_FUNCTION_SUM"
      }
    }
  ],
  "unit": "UNIT_MILLICORES"
}

Example Response Copied

{
  "aggregations": [
    {
      "aggregation": {
        "map": {
          "function": "BUCKET_FUNCTION_LAST"
        },
        "reduce": {
          "function": "BUCKET_FUNCTION_SUM"
        }
      },
      "value": 112521.0
    }
  ],
  "unit": "UNIT_MILLICORES"
}

Response Codes Copied

200 OK - Success
400 Bad Request - Invalid request parameters
404 Not Found - Metric not found

Entity Service (Deprecated) Copied

Note
All Entity Service endpoints are deprecated and may be removed in future releases.

Get Entities Copied

POST /entity/GetEntities Deprecated

Get entities matching specified filtering criteria with pagination support.

Parameters Copied

Parameter	Type	Location	Description
`entityFilter`	object	body	Filter for specific entities
`activityFilter`	object	body	Filter entities active during time range
`namesFilter`	object	body	Include only specific attribute names
`pagingToken`	string	body	Token for pagination
`pageSize`	integer	body	Maximum results to return (default: 1000)

Example Request Copied

{
  "entityFilter": {
    "expression": {
      "comparison": {
        "name": "environment",
        "value": "production"
      }
    }
  },
  "pageSize": 100
}

Example Response Copied

{
  "entities": [
    {
      "dimensions": [
        {
          "key": "hostname",
          "value": "server-01"
        }
      ],
      "attributes": [
        {
          "namespace": "system",
          "name": "environment",
          "value": {
            "string": "production"
          },
          "unit": "UNIT_NONE",
          "userWritable": true
        }
      ],
      "metrics": [
        {
          "namespace": "system.metrics",
          "name": "cpu_usage",
          "type": "METRIC_TYPE_GAUGE",
          "unit": "UNIT_PERCENT"
        }
      ]
    }
  ],
  "pagingToken": "eyJvcmRlckJ5IjpbXSwiZmlyc3RSb3ciOm51bGwsImxhc3RSb3ciOlt7IiRsYXN0Um93Ijp7InByaW1hcnlLZXkiOjEyM319XX0="
}

Response Codes Copied

200 OK - Success

Get Names Copied

POST /entity/GetNames Deprecated

Get available entity attribute names based on filtering criteria.

Parameters Copied

Parameter	Type	Location	Description
`typeFilter`	array	body	Include only names of specific types
`entityFilter`	object	body	Filter by entities matching criteria
`nameFilter`	object	body	Filter names by pattern/namespace
`limit`	integer	body	Max results (default: 100, max: 1000)

Example Request Copied

{
  "typeFilter": ["ATTRIBUTES_ONLY", "STRING_ATTRIBUTES"],
  "limit": 50
}

Example Response Copied

{
  "names": [
    {
      "name": {
        "namespace": "system",
        "name": "environment"
      },
      "type": "ATTRIBUTE",
      "valueType": "STRING"
    },
    {
      "name": {
        "namespace": "system", 
        "name": "hostname"
      },
      "type": "DIMENSION",
      "valueType": "STRING"
    }
  ]
}

Response Codes Copied

200 OK - Success

Get Values Copied

POST /entity/GetValues Deprecated

Get available values for a specific attribute name.

Parameters Copied

Parameter	Type	Location	Required	Description
`name`	object	body	✓	Name and namespace to retrieve values for
`entityFilter`	object	body		Filter by entities matching criteria
`valueFilter`	object	body		Filter values by pattern
`limit`	integer	body		Max results (default: 100, max: 1000)

Example Request Copied

{
  "name": {
    "namespace": "system",
    "name": "environment"
  },
  "limit": 20
}

Example Response Copied

{
  "values": [
    {
      "value": {
        "string": "development"
      },
      "unit": "UNIT_NONE",
      "enDisplayValue": "development"
    },
    {
      "value": {
        "string": "production"
      },
      "unit": "UNIT_NONE", 
      "enDisplayValue": "production"
    }
  ]
}

Response Codes Copied

200 OK - Success
400 Bad Request - Invalid request

Metric Query Service (Deprecated) Copied

Note
All Metric Query Service endpoints are deprecated and may be removed in future releases.

Get Latest Metrics Copied

POST /metrics/GetLatestMetrics Deprecated

Get the latest metric time series data matching filtering criteria.

Parameters Copied

Parameter	Type	Location	Description
`metric`	string	body	Metric name (limits results to 1000 if omitted)
`namespace`	string	body	Metric namespace
`entityFilter`	object	body	Entity filter
`window`	string	body	Time window for latest samples (default: 6 hours)
`pageOffset`	object	body	Pagination information

Example Request Copied

{
  "metric": "cpu_usage",
  "namespace": "system.metrics",
  "window": "1h"
}

Response Codes Copied

200 OK - Success

Get Latest Status Metrics Copied

POST /metrics/GetLatestStatusMetrics Deprecated

Get the latest status metric samples matching filtering criteria.

Parameters Copied

Parameter	Type	Location	Description
`metric`	string	body	Metric name
`namespace`	string	body	Metric namespace
`entityFilter`	object	body	Entity filter
`window`	string	body	Time window for latest samples (default: 6 hours)
`pageOffset`	object	body	Pagination information

Example Request Copied

{
  "metric": "service_status",
  "namespace": "application.health",
  "window": "30m"
}

Response Codes Copied

200 OK - Success

Get Metric Metadata Copied

POST /metrics/GetMetricMetadata Deprecated

Get metadata for available metrics including type and unit information.

Parameters Copied

Parameter	Type	Location	Description
`name`	string	body	Metric name or pattern
`namespace`	string	body	Specific namespace filter
`nameMatchType`	string	body	String matching technique (default: “contains”)
`entityFilter`	object	body	Filter by entities
`typeUnitFilter`	array	body	Filter by type and unit combinations
`pageOffset`	object	body	Pagination information

Example Request Copied

{
  "name": "cpu",
  "nameMatchType": "MATCH_TYPE_STARTS_WITH",
  "namespace": "system.metrics"
}

Example Response Copied

{
  "offset": 0,
  "hasNextPage": false,
  "results": [
    {
      "namespace": "system.metrics",
      "name": "cpu_usage",
      "typeUnitTuples": [
        {
          "type": "METRIC_TYPE_GAUGE",
          "unit": "UNIT_PERCENT"
        }
      ]
    }
  ]
}

Response Codes Copied

200 OK - Success

Get Metrics Copied

POST /metrics/GetMetrics Deprecated

Get metric data over a time range with optional bucketing and forecasting.

Parameters Copied

Parameter	Type	Location	Required	Description
`metric`	string	body	✓	Metric name
`namespace`	string	body		Metric namespace
`entityFilter`	object	body		Entity filter
`from`	string (date-time)	body	✓	Starting timestamp
`to`	string (date-time)	body		Ending timestamp
`bucket`	object	body		Bucketing parameters
`groupByDimensions`	array	body		Dimensions to group by
`forecast`	object	body		Forecasting parameters
`seriesLimit`	integer	body		Max series to return (default: 20, max: 50)

Example Request Copied

{
  "metric": "memory_usage",
  "namespace": "system.metrics",
  "from": "2023-10-01T00:00:00Z",
  "to": "2023-10-01T23:59:59Z",
  "bucket": {
    "interval": "BUCKET_INTERVAL_ONE_HOUR",
    "function": "BUCKET_FUNCTION_AVG"
  }
}

Response Codes Copied

200 OK - Success
400 Bad Request - Invalid request

Get Status Metrics Copied

POST /metrics/GetStatusMetrics Deprecated

Get status metric time series data over a specified time range.

Parameters Copied

Parameter	Type	Location	Required	Description
`metric`	string	body	✓	Metric name
`namespace`	string	body		Metric namespace
`entityFilter`	object	body		Entity filter
`from`	string (date-time)	body	✓	Starting timestamp
`to`	string (date-time)	body		Ending timestamp

Example Request Copied

{
  "metric": "service_health",
  "namespace": "application.monitoring",
  "from": "2023-10-01T00:00:00Z",
  "to": "2023-10-01T23:59:59Z"
}

Response Codes Copied

200 OK - Success
400 Bad Request - Invalid request

Common Error Responses Copied

All endpoints may return the following error responses:

400 Bad Request Copied

{
  "title": "Bad Request",
  "message": "The metric name must be set"
}

404 Not Found Copied

{
  "title": "Not Found", 
  "message": "The requested resource was not found"
}

Schemas Copied

This section describes the data structures used throughout the API.

ActivityFilter Copied

Filters entities based on their activity during a time range.

Field	Type	Required	Description
`from`	string (date-time)	✓	Include entities active after this time
`to`	string (date-time)	✓	Include entities active before this time

AggregationResult Copied

Represents the result of a single aggregation function with its corresponding value.

Field	Type	Required	Description
`aggregation`	object	✓	The aggregation function that was applied
`value`	number	✓	The aggregated value

{
  "aggregation": {
  "map": {
    "function": "BUCKET_FUNCTION_LAST"
  },
  "reduce": {
    "function": "BUCKET_FUNCTION_SUM"
  }
  },
  "value": 112521.0
}

Any Copied

Contains a message with optional YAML representation.

Field	Type	Required	Description
`value`	object		The protobuf Any value
`yaml`	string		YAML representation

AnyValue Copied

Used to represent any type of attribute value including primitives and nested objects.

Field	Type	Description
`stringValue`	string	String value
`boolValue`	boolean	Boolean value
`intValue`	string	Integer value as string
`doubleValue`	number	Double precision number
`arrayValue`	object	Array of values
`kvlistValue`	object	Key-value list
`bytesValue`	string (bytes)	Bytes value

ArrayValue Copied

A list of AnyValue messages used in oneof fields.

Field	Type	Required	Description
`values`	array		Array of AnyValue messages (may be empty)

BucketRequest Copied

Defines bucketing parameters for metric queries.

Field	Type	Required	Description
`interval`	string (enum)		Time interval for bucketing
`buckets`	integer		Desired number of samples (hint for dynamic bucketing)
`function`	string (enum)	✓	Aggregation function to apply
`customNthPercentile`	number		Percentile value (0-100) for percentile functions

Bucket Intervals:

BUCKET_INTERVAL_RAW - Raw data
BUCKET_INTERVAL_TEN_SECOND - 10-second intervals
BUCKET_INTERVAL_THIRTY_SECOND - 30-second intervals
BUCKET_INTERVAL_ONE_MINUTE - 1-minute intervals
BUCKET_INTERVAL_FIVE_MINUTE - 5-minute intervals
BUCKET_INTERVAL_FIFTEEN_MINUTE - 15-minute intervals
BUCKET_INTERVAL_ONE_HOUR - 1-hour intervals
BUCKET_INTERVAL_ONE_DAY - 1-day intervals

Dimension Copied

A single entity dimension consisting of a key-value pair.

Field	Type	Required	Description
`key`	string	✓	The dimension key
`value`	string	✓	The dimension value

{
  "key": "hostname",
  "value": "server-01"
}

Entity Copied

Represents a complete entity with its dimensions, attributes, metrics, and logs.

Field	Type	Required	Description
`dimensions`	array	✓	Immutable, uniquely identifying characteristics
`attributes`	array		Entity attributes including observed and user-supplied data
`metrics`	array		Available metrics for this entity
`logs`	array		Available logs for this entity

EntityAttribute Copied

An entity attribute with metadata about its source and editability.

Field	Type	Required	Description
`namespace`	string	✓	Scopes attribute names to the source
`name`	string	✓	The attribute’s name (unique within namespace)
`value`	object		The attribute’s value
`unit`	string (enum)		The value’s unit of measure
`userWritable`	boolean		Whether this attribute is user editable
`inheritable`	boolean		Whether this attribute can be inherited by children
`inherited`	boolean		Whether this attribute was inherited from ancestor
`enrichmentInfo`	object		Details about enrichment action that created/modified attribute

EntityAttribute_EnrichmentInfo Copied

Provides details about the enrichment action that created or modified an attribute.

Field	Type	Description
`ruleset`	object	Coordinates of the enrichment ruleset
`rule`	integer	The enrichment rule’s index (zero based)
`action`	integer	The enrichment action’s index (zero based)
`enrichmentType`	string (enum)	Type of enrichment (ATTRIBUTE_CREATED, ATTRIBUTE_MODIFIED, ATTRIBUTE_INHERITED)

EntityFilter Copied

Defines filtering criteria for entities. Can be either exact dimension matching or expression-based filtering.

Field	Type	Description
`orderedDimensions`	object	Exact match on entity’s dimensions considering order
`dimensions`	object	Exact match on entity’s dimensions ignoring order
`expression`	object	Filter using expressions for complex matching

{
  "expression": {
    "comparison": {
      "name": "namespace",
      "value": "production"
    }
  }
}

EntityLog Copied

An entity log reference.

Field	Type	Required	Description
`namespace`	string	✓	The log’s namespace
`name`	string	✓	The log’s name (unique within namespace)

EnrichmentRulesetCoordinates Copied

Enrichment ruleset coordinates.

Field	Type	Required	Description
`package`	string		The ruleset’s package (if omitted, no package)
`name`	string	✓	The ruleset’s name

EntityMetric Copied

Describes a metric available for an entity.

Field	Type	Required	Description
`namespace`	string	✓	The metric’s namespace
`name`	string	✓	The metric’s name (unique within namespace)
`type`	string (enum)	✓	The type of metric
`unit`	string (enum)	✓	The metric’s unit of measure

Metric Types:

METRIC_TYPE_COUNTER - Counter metric
METRIC_TYPE_GAUGE - Gauge metric
METRIC_TYPE_HISTOGRAM - Histogram metric
METRIC_TYPE_STATUS - Status metric

EntityName Copied

Information about an entity attribute or dimension name.

Field	Type	Required	Description
`name`	object	✓	The name and namespace
`type`	string (enum)	✓	The name type (DIMENSION or ATTRIBUTE)
`valueType`	string (enum)	✓	The value type

Name Types:

DIMENSION - Entity dimension
ATTRIBUTE - Entity attribute

Value Types:

NONE - No value type
BOOLEAN - Boolean value
DOUBLE - Double precision number
LONG - Long integer
STRING - String value
STRING_LIST - Array of strings
TIMESTAMP - Timestamp value

EntityValue Copied

Represents an entity value with its unit and display formatting.

Field	Type	Required	Description
`value`	object	✓	The typed value
`unit`	string (enum)	✓	The value’s unit of measure
`enDisplayValue`	string	✓	English display string (e.g., “3 GHz”)

Expression Copied

Defines an expression used for complex entity filtering. Used within EntityFilter for advanced matching criteria.

Field	Type	Required	Description
`additionalProperties`	array		Additional properties for the expression

Exemplar Copied

A representation of an exemplar, which is a sample input measurement.

Field	Type	Description
`filteredAttributes`	array	Key/value pairs filtered out by aggregator
`timeUnixNano`	string	UNIX Epoch time in nanoseconds when recorded
`asDouble`	number	Double value
`asInt`	string	Integer value
`spanId`	string (bytes)	Span ID of the exemplar trace
`traceId`	string (bytes)	Trace ID of the exemplar trace

ExponentialHistogram Copied

Represents exponential histogram metric calculated by aggregating measurements.

Field	Type	Required	Description
`dataPoints`	array		Array of exponential histogram data points
`aggregationTemporality`	string (enum)		Aggregation temporality (DELTA or CUMULATIVE)

ExponentialHistogramDataPoint Copied

Single data point in an exponential histogram timeseries.

Field	Type	Description
`attributes`	array	Key/value pairs that identify the timeseries
`startTimeUnixNano`	string	Start time in UNIX Epoch nanoseconds
`timeUnixNano`	string	Time in UNIX Epoch nanoseconds
`count`	string	Number of values in the population
`sum`	number	Sum of values in the population
`scale`	integer	Scale describing histogram resolution
`zeroCount`	string	Count of zero values
`positive`	object	Positive range bucket counts
`negative`	object	Negative range bucket counts
`flags`	integer	Flags for this data point
`exemplars`	array	List of exemplars
`min`	number	Minimum value
`max`	number	Maximum value
`zeroThreshold`	number	Width of the zero region

ExponentialHistogramDataPoint_Buckets Copied

Set of bucket counts encoded in a contiguous array.

Field	Type	Required	Description
`offset`	integer		Bucket index of first entry in bucket_counts array
`bucketCounts`	array		Array of count values for buckets

ForecastRequest Copied

Parameters for forecasting operations.

Field	Type	Required	Description
`forecast`	boolean		Whether to enable forecasting
`from`	string (date-time)	✓	Inclusive from time
`to`	string (date-time)	✓	Exclusive to time
`model`	string (enum)		Forecasting model to use
`modelParams`	object		Model-specific parameters

Gauge Copied

Gauge metric that exports the current value for every data point.

Field	Type	Required	Description
`dataPoints`	array		Array of number data points

GetEntitiesRequest Copied

Request object for retrieving entities with filtering and pagination.

Field	Type	Description
`entityFilter`	object	Filter to match specific entities
`activityFilter`	object	Filter entities active during time range
`namesFilter`	object	Include only specific attribute names
`pagingToken`	string	Token for pagination
`pageSize`	integer	Maximum results to return (default: 1000)

GetEntitiesResponse Copied

Response object containing a list of entities and pagination information.

Field	Type	Required	Description
`entities`	array	✓	Array of entities matching the request criteria
`pagingToken`	string		Token for next page (empty if no more pages)

GetGroupedSummaryStatisticsRequest Copied

Request object for retrieving summary statistics grouped by dimensions or attributes.

Field	Type	Required	Description
`metric`	object	✓	The target metric specification
`entityFilter`	object		Filter to match entities
`from`	string (date-time)	✓	Starting inclusive timestamp
`to`	string (date-time)		Ending exclusive timestamp
`aggregations`	array	✓	List of unique aggregations to return
`unit`	string (enum)		Unit to return response in
`groupBy`	object	✓	Dimensions or attributes to group by

GetGroupedSummaryStatisticsResponse Copied

Response object containing grouped summary statistics.

Field	Type	Required	Description
`unit`	string (enum)	✓	The unit of the response values
`aggregations`	array	✓	The requested aggregations in order
`groups`	array	✓	The grouped summary statistics

GetNamesRequest Copied

Request object for retrieving available entity attribute names.

Field	Type	Description
`typeFilter`	array	Include only names of specific types
`entityFilter`	object	Filter by entities matching criteria
`nameFilter`	object	Filter names by pattern/namespace
`limit`	integer	Max results (default: 100, max: 1000)

GetNamesResponse Copied

Response object containing available entity names.

Field	Type	Required	Description
`names`	array	✓	Names sorted by namespace, name and type

GetSeasonalModelRequest Copied

Request object for seasonal model generation.

Field	Type	Required	Description
`seasonality`	object	✓	Length of a season (integer multiple of granularity)
`granularity`	object	✓	Granularity of returned buckets
`window`	object	✓	Amount of source data used to generate model
`functions`	object	✓	Aggregation functions to apply
`entityFilter`	object	✓	Entity filter for matching entities
`namespace`	string	✓	Metric namespace
`metric`	string	✓	Metric name
`timezone`	string		Timezone for daylight saving adjustments
`calendarFilter`	string		Calendar name for filtering source data

GetSeasonalModelRequest_AggregationFunction Copied

Defines an aggregation function for seasonal models.

Field	Type	Required	Description
`bucketFunction`	string (enum)	✓	The aggregation function to apply
`nthPercentile`	number		Percentile value (0-100) if function is PERCENTILE

GetSeasonalModelRequest_AggregationFunctions Copied

Container for aggregation functions in seasonal model requests.

Field	Type	Required	Description
`functions`	array	✓	List of unique aggregation functions

{
  "functions": [
    {
      "bucketFunction": "BUCKET_FUNCTION_AVG"
    }
  ]
}

GetSeasonalModelRequest_LookbackWindow Copied

Defines the lookback window for seasonal model generation.

Field	Type	Required	Description
`latestLookback`	string (date-time)	✓	The latest timestamp of the look-back window
`seasonalPeriods`	integer	✓	Number of seasonal periods to include (minimum: 1)

{
  "latestLookback": "2023-10-29T22:00:00Z",
  "seasonalPeriods": 7
}

GetSeasonalModelRequest_SeasonalValue Copied

Defines temporal values for seasonality and granularity in seasonal model requests.

Field	Type	Description
`minutes`	integer	Value in minutes (15, 30)
`hours`	integer	Value in hours (1-23)
`days`	integer	Value in days (minimum: 1)
`weeks`	integer	Value in weeks (minimum: 1)

GetSeasonalModelResponse Copied

Response object containing seasonal model data.

Field	Type	Required	Description
`value`	object		Model data point
`footer`	object		Response footer with metadata

GetSeasonalModelResponse_AggregatedValue Copied

Individual aggregated value in seasonal model response.

Field	Type	Required	Description
`bucketFunction`	string (enum)	✓	The aggregation function
`percentile`	number		Percentile value (set only if function is PERCENTILE)
`value`	number	✓	The aggregated value

GetSeasonalModelResponse_AggregatedValues Copied

Container for aggregated values in seasonal model response.

Field	Type	Required	Description
`values`	array	✓	List of aggregated values

GetSeasonalModelResponse_Footer Copied

Footer information for seasonal model response.

Field	Type	Required	Description
`start`	string (date-time)	✓	Start timestamp rounded to nearest granularity
`unit`	string (enum)	✓	Unit of the metric

GetSeasonalModelResponse_ModelDataPoint Copied

Individual data point in the seasonal model.

Field	Type	Description
`histogram`	string (bytes)	Histogram data
`aggregatedValues`	object	Aggregated values for this data point
`bucketCount`	integer	Number of merged buckets (0 if no data)

GetSummaryStatisticsRequest Copied

Request object for retrieving summary statistics.

Field	Type	Required	Description
`metric`	object	✓	The target metric specification
`entityFilter`	object		Filter to match entities
`from`	string (date-time)	✓	Starting inclusive timestamp
`to`	string (date-time)		Ending exclusive timestamp
`aggregations`	array	✓	List of unique aggregations to return
`unit`	string (enum)		Unit to return response in

GetSummaryStatisticsResponse Copied

Response object containing summary statistics.

Field	Type	Required	Description
`aggregations`	array	✓	The aggregated values with their functions
`unit`	string (enum)	✓	The unit of the response values

GetValuesRequest Copied

Request object for retrieving available values for a specific attribute name.

Field	Type	Required	Description
`name`	object	✓	Name and namespace to retrieve values for
`entityFilter`	object		Filter by entities matching criteria
`valueFilter`	object		Filter values by pattern
`limit`	integer		Max results (default: 100, max: 1000)

GetValuesResponse Copied

Response object containing available attribute values.

Field	Type	Required	Description
`values`	array	✓	Values sorted alphanumerically

GoogleProtobufAny Copied

Contains an arbitrary serialized message along with a type descriptor.

Field	Type	Required	Description
`@type`	string	✓	The type of the serialized message

Histogram Copied

Histogram metric calculated by aggregating measurements over a time interval.

Field	Type	Required	Description
`dataPoints`	array		Array of histogram data points
`aggregationTemporality`	string (enum)		Aggregation temporality (DELTA or CUMULATIVE)

HistogramDataPoint Copied

Single data point in a histogram timeseries.

Field	Type	Description
`attributes`	array	Key/value pairs that identify the timeseries
`startTimeUnixNano`	string	Start time in UNIX Epoch nanoseconds
`timeUnixNano`	string	Time in UNIX Epoch nanoseconds
`count`	string	Number of values in the population
`sum`	number	Sum of values in the population
`bucketCounts`	array	Count values of histogram buckets
`explicitBounds`	array	Bucket boundaries for values
`exemplars`	array	List of exemplars
`flags`	integer	Flags for this data point
`min`	number	Minimum value
`max`	number	Maximum value

KeyValue Copied

Key-value pair used to store attributes and other metadata.

Field	Type	Required	Description
`key`	string	✓	The key
`value`	object	✓	The AnyValue

KeyValueList Copied

A list of KeyValue messages.

Field	Type	Required	Description
`values`	array		Collection of key/value pairs (keys must be unique)

LatestMetricRequest Copied

Request for retrieving latest metric time series data.

Field	Type	Description
`metric`	string	Metric name (limits results to 1000 if omitted)
`namespace`	string	Metric namespace
`entityFilter`	object	Entity filter
`window`	string	Time window for latest samples (default: 6 hours)
`pageOffset`	object	Pagination information

LatestStatusMetricRequest Copied

Request for retrieving latest status metric samples.

Field	Type	Description
`metric`	string	Metric name
`namespace`	string	Metric namespace
`entityFilter`	object	Entity filter
`window`	string	Time window for latest samples (default: 6 hours)
`pageOffset`	object	Pagination information

ListLatestMetric Copied

Response containing latest metrics.

Field	Type	Required	Description
`metrics`	array		Array of metric data

ListLatestStatusMetric Copied

Response containing latest status metrics.

Field	Type	Required	Description
`metrics`	array		Array of status metric data

MapReduceAnalyticsFunction Copied

Defines the two-step process for analytics aggregations.

Field	Type	Required	Description
`map`	object		Statistical function to extract from each bucket
`reduce`	object	✓	Aggregation function to apply across extracted values

{
  "map": {
    "function": "BUCKET_FUNCTION_LAST"
  },
  "reduce": {
    "function": "BUCKET_FUNCTION_SUM"
  }
}

Metric Copied

Defines a metric with one or more timeseries and metadata.

Field	Type	Required	Description
`name`	string	✓	Name of the metric
`description`	string		Description of the metric
`unit`	string		Unit in which the metric value is reported
`gauge`	object		Gauge data
`sum`	object		Sum data
`histogram`	object		Histogram data
`exponentialHistogram`	object		Exponential histogram data
`summary`	object		Summary data
`metadata`	array		Additional metadata attributes

MetricMetadata Copied

Metadata for available metrics including type and unit information.

Field	Type	Required	Description
`namespace`	string	✓	Namespace of the metric
`name`	string	✓	Name of the metric
`typeUnitTuples`	array		List of metric type + unit pairings

MetricMetadataPage Copied

Paginated response for metric metadata queries.

Field	Type	Required	Description
`offset`	integer	✓	Offset index of the first data sample
`hasNextPage`	boolean	✓	Whether there is more data after this page
`results`	array	✓	Results sorted by metric name and namespace

MetricMetadataRequest Copied

Request for retrieving metric metadata.

Field	Type	Description
`name`	string	Metric name or pattern to match
`namespace`	string	Specific namespace filter
`nameMatchType`	string (enum)	String matching technique (default: “contains”)
`entityFilter`	object	Filter by entities
`typeUnitFilter`	array	Filter by type and unit combinations
`pageOffset`	object	Pagination information

MetricRequest Copied

Request for retrieving metric data over a time range.

Field	Type	Required	Description
`metric`	string	✓	Metric name
`namespace`	string		Metric namespace
`entityFilter`	object		Entity filter
`from`	string (date-time)	✓	Starting timestamp
`to`	string (date-time)		Ending timestamp
`bucket`	object		Bucketing parameters
`groupByDimensions`	array		Dimensions to group by
`forecast`	object		Forecasting parameters
`seriesLimit`	integer		Max series to return (default: 20, max: 50)

NameFilter Copied

Filters names by pattern and namespace matching.

Field	Type	Description
`matchType`	string (enum)	How to match the name (default: CONTAINS)
`name`	string	Name pattern to match (case-insensitive)
`namespace`	string	Specific namespace filter (case-insensitive)

Match Types:

MATCH_TYPE_CONTAINS - Contains matching
MATCH_TYPE_STARTS_WITH - Starts with matching
MATCH_TYPE_EXACT - Exact matching

NamespacedName Copied

A name scoped within a namespace.

Field	Type	Required	Description
`namespace`	string		Namespace (max 128 characters)
`name`	string	✓	Name (non-blank, max 64 characters)

{
  "namespace": "system",
  "name": "environment"
}

NamedAny Copied

Used to represent maps of Any as ordered (name,value) pairs.

Field	Type	Required	Description
`name`	string	✓	Map key
`value`	object	✓	Mapped Any value

NumberDataPoint Copied

Single data point in a timeseries that describes time-varying scalar values.

Field	Type	Description
`attributes`	array	Key/value pairs that identify the timeseries
`startTimeUnixNano`	string	Start time in UNIX Epoch nanoseconds
`timeUnixNano`	string	Time in UNIX Epoch nanoseconds
`asDouble`	number	Double value
`asInt`	string	Integer value
`exemplars`	array	List of exemplars
`flags`	integer	Flags for this data point

OrderedDimensionsFilter Copied

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

Field	Type	Required	Description
`dimensions`	array	✓	Dimensions in specific order (cannot be empty)

PageOffset Copied

Defines pagination parameters for offset-based paging.

Field	Type	Required	Description
`offset`	integer		Offset into the matching data (default: 0, minimum: 0)
`pageSize`	integer		Size of the page to return (default: 100, min: 1, max: 1000)

PagingToken Copied

Token-based pagination to handle entity deletions between requests.

Field	Type	Required	Description
`pagingToken`	string		Token from previous response for next page
`pageSize`	integer		Maximum results to return

SeasonalValue Copied

Defines temporal values for seasonality and granularity.

Field	Type	Description
`minutes`	integer	Value in minutes (15, 30)
`hours`	integer	Value in hours (1-23)
`days`	integer	Value in days (minimum: 1)
`weeks`	integer	Value in weeks (minimum: 1)

SelectedNames Copied

Defines which attribute names to include in entity responses.

Field	Type	Required	Description
`attributeNames`	array		Specific attribute names to include (if unset, no attributes returned)

{
  "attributeNames": [
    {
      "namespace": "system",
      "name": "hostname"
    }
  ]
}

StatusMetric Copied

Represents a status metric with optional time window.

Field	Type	Required	Description
`value`	string	✓	Status value (max 64 characters)
`window`	object		Optional time window for which the value applies

StatusMetricRequest Copied

Request for retrieving status metric time series data.

Field	Type	Required	Description
`metric`	string	✓	Metric name
`namespace`	string		Metric namespace
`entityFilter`	object		Entity filter
`from`	string (date-time)	✓	Starting timestamp
`to`	string (date-time)		Ending timestamp

StringList Copied

A list of string values.

Field	Type	Required	Description
`values`	array		Array of string values

Sum Copied

Sum metric calculated as sum of all reported measurements over a time interval.

Field	Type	Description
`dataPoints`	array	Array of number data points
`aggregationTemporality`	string (enum)	Aggregation temporality (DELTA or CUMULATIVE)
`isMonotonic`	boolean	Whether the sum is monotonic

Summary Copied

Summary metric data used to convey quantile summaries.

Field	Type	Required	Description
`dataPoints`	array		Array of summary data points

SummaryDataPoint Copied

Single data point in a summary timeseries.

Field	Type	Description
`attributes`	array	Key/value pairs that identify the timeseries
`startTimeUnixNano`	string	Start time in UNIX Epoch nanoseconds
`timeUnixNano`	string	Time in UNIX Epoch nanoseconds
`count`	string	Number of values in the population
`sum`	number	Sum of values in the population
`quantileValues`	array	Values at different quantiles
`flags`	integer	Flags for this data point

SummaryDataPoint_ValueAtQuantile Copied

Represents value at a given quantile of a distribution.

Field	Type	Required	Description
`quantile`	number	✓	The quantile of distribution [0.0, 1.0]
`value`	number	✓	The value at the given quantile

StatisticalAggregationFunction Copied

Specifies the aggregation function and parameters.

Field	Type	Required	Description
`function`	string (enum)	✓	The aggregation function to apply
`percentile`	number		Percentile value (0-100) when function is `BUCKET_FUNCTION_PERCENTILE`

Function Values:

BUCKET_FUNCTION_AVG - Average value
BUCKET_FUNCTION_MIN - Minimum value
BUCKET_FUNCTION_MAX - Maximum value
BUCKET_FUNCTION_PERCENTILE - Percentile value
BUCKET_FUNCTION_SUM - Sum of values
BUCKET_FUNCTION_COUNT - Count of values
BUCKET_FUNCTION_FIRST - First value
BUCKET_FUNCTION_LAST - Last value
BUCKET_FUNCTION_RATE - Rate calculation
BUCKET_FUNCTION_STDDEV - Standard deviation
BUCKET_FUNCTION_VARIANCE - Variance

SummaryStatisticsGroup Copied

Represents a group of summary statistics with the dimensions and attributes they were grouped by.

Field	Type	Required	Description
`attributes`	array		The attributes that the summary statistics were grouped by
`dimensions`	array		The dimensions that the summary statistics were grouped by
`values`	array	✓	The aggregated values (order corresponds to request aggregations)

{
  "values": [112521.0],
  "attributes": [
    {
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kubernetes.io/name", 
      "value": "obcerv-operator"
    }
  ],
  "dimensions": [
    {
      "key": "pod",
      "value": "obcerv-operator"
    }
  ]
}

SummaryStatisticsGroup_GroupByAttributeValue Copied

Represents an attribute value that summary statistics were grouped by.

Field	Type	Required	Description
`namespace`	string	✓	The namespace of the attribute
`name`	string	✓	The name of the attribute
`value`	string	✓	The value of the attribute

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kubernetes.io/name",
  "value": "obcerv-operator"
}

SummaryStatisticsGroupBy Copied

Defines dimensions or attributes to group summary statistics by.

Field	Type	Required	Description
`attributes`	array		Array of attributes to group by
`dimensions`	array		Array of dimension names to group by

{
  "dimensions": ["node", "container"],
  "attributes": [
    {
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kubernetes.io/name"
    }
  ]
}

SummaryStatisticsGroupBy_GroupByAttribute Copied

Specifies an attribute to group summary statistics by.

Field	Type	Required	Description
`namespace`	string	✓	The namespace of the attribute to group by
`name`	string	✓	The name of the attribute to group by

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kubernetes.io/name"
}

TargetMetric Copied

Specifies the target metric for analytics operations.

Field	Type	Required	Description
`namespace`	string	✓	The metric namespace (e.g., “itrsgroup.com/c2/kubernetes-plugin”)
`name`	string	✓	The metric name (e.g., “kube_container_cpu_limit”)

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kube_container_cpu_limit"
}

TypeUnitFilter Copied

Tuple filter used to define a filter on Metric Type and/or Unit pairs.

Field	Type	Required	Description
`typeFilter`	string (enum)		Filter by metrics containing this MetricType
`unitFilter`	string (enum)		Filter by metrics containing this Unit

TypeUnitTuple Copied

Tuple containing Metric Type + Unit pairing.

Field	Type	Required	Description
`type`	string (enum)	✓	The metric type
`unit`	string (enum)	✓	The metric unit

UnorderedDimensionsFilter Copied

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

Field	Type	Required	Description
`dimensions`	object	✓	Dimensions as key-value pairs (cannot be empty)

Value Copied

Represents a typed value that can be boolean, numeric, string, timestamp, or string list.

Field	Type	Description
`boolean`	boolean	Boolean value
`long`	string	Long integer value (as string)
`double`	number	Double precision number
`string`	string	String value
`timestamp`	string (date-time)	Timestamp value
`stringList`	object	Array of string values

{
  "string": "production"
}

ValueFilter Copied

Filters values by pattern matching.

Field	Type	Required	Description
`matchType`	string (enum)		How to match the filter term (default: CONTAINS)
`filter`	string	✓	Filter term to match (case-insensitive)

Window Copied

Represents a time window with duration and end time.

Field	Type	Required	Description
`durationNanos`	string		Duration in nanoseconds
`endTimeNanos`	string		End time in nanoseconds

Units Enumeration Copied

The API supports a comprehensive set of units for measurements:

Data Units:

UNIT_BYTES, UNIT_KILOBYTES, UNIT_MEGABYTES, UNIT_GIGABYTES, UNIT_TERABYTES, UNIT_PETABYTES, UNIT_EXABYTES
UNIT_KIBIBYTES, UNIT_MEBIBYTES, UNIT_GIBIBYTES, UNIT_TEBIBYTES, UNIT_PEBIBYTES, UNIT_EXBIBYTES
UNIT_BITS, UNIT_KILOBITS, UNIT_MEGABITS, UNIT_GIGABITS, UNIT_TERABITS

Rate Units:

UNIT_BITS_PER_SECOND, UNIT_BYTES_PER_SECOND, UNIT_KILOBYTES_PER_SECOND, UNIT_MEGABYTES_PER_SECOND, UNIT_GIGABYTES_PER_SECOND, UNIT_TERABYTES_PER_SECOND
UNIT_PER_SECOND, UNIT_PER_MINUTE

Time Units:

UNIT_NANOSECONDS, UNIT_MICROSECONDS, UNIT_MILLISECONDS, UNIT_SECONDS, UNIT_MINUTES, UNIT_HOURS, UNIT_DAYS
UNIT_EPOCH_NANOSECONDS, UNIT_EPOCH_MILLISECONDS

Computing Units:

UNIT_CORES, UNIT_MILLICORES, UNIT_MICROCORES, UNIT_NANOCORES
UNIT_HERTZ, UNIT_MEGAHERTZ, UNIT_GIGAHERTZ

Other Units:

UNIT_PERCENT, UNIT_FRACTION
UNIT_DEGREES_CELSIUS
UNIT_WATTS, UNIT_VOLTS, UNIT_KILOVOLTS, UNIT_AMPERES, UNIT_MILLIAMPERES
Currency units: UNIT_USD, UNIT_EUR, UNIT_GBP, UNIT_JPY, etc.

Previous article Next article