API Gateway

Note

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

API Gateway exposes a REST API for the ITRS Analytics platform. Integrations and apps call these endpoints to query entities, metrics, analytics, and lookups.

Rate limiting Copied

All public REST endpoints on the API Gateway are subject to rate limiting. The exact limit is deployment-specific and configured by your ITRS Analytics administrators. This protects the platform when many clients or automated jobs send traffic at once.

• When you exceed the limit, the service responds with 429 Too Many Requests. Treat this as a signal to slow down and use retries with backoff, along with cap total retries, instead of tight loops.
• The limit is shared for the Gateway, not allocated per API client or user. Traffic from every integration counts toward the same pool for that environment, so heavy usage by one consumer can cause others to see 429 sooner.
• How high the limit is (requests per second or per window) is set per deployment by your platform operators (for example, via Helm values). If you need a higher sustained throughput, discuss capacity with your ITRS Analytics administrator rather than only increasing client parallelism.

The individual endpoint sections below focus on success and validation errors (400, 404, and so on). 429 can apply to any of them when rate limits are hit.

Helm configuration for rate limiting Copied

If you deploy or upgrade the API Gateway with Helm, rate limits are not changed inside the application image. They are applied at runtime from environment variables on the pod environment. You can set these variables through the chart’s env values, which are a list of name / value pairs, typically in a values file passed to helm install or helm upgrade with -f.

Rate limit environment variables reference Copied

Use this table when you edit chart defaults or cluster-specific overrides. The same RL_* names appear in the chart env list in both cases.

Note

The values for limit-refresh-period must be valid Spring Boot duration strings (for example, 10s, 1m) to match what application.yml expects. Quote numeric limits and durations as strings in YAML (for example, value: "50" and value: "10s").

Edit default rate limits in the Helm chart Copied

Follow this to change the chart’s default values.yaml and publish a new chart version, so installs that use the chart without extra overrides pick up the new RL_* rate limits.

1. Open helm/src/main/resources/values.yaml in the API Gateway Helm chart module.
2. Under the env: key, locate the RL_* entries after the comment # Rate limiting - default config.
3. Change the value strings for the limits you need, using the variable names in the table above.
4. Commit and run your normal Helm build or release pipeline to publish the updated chart.

Overrides at install or upgrade Copied

Follow this to change rate limits for a running deployment by passing or updating a values file at helm install or helm upgrade time, without editing or republishing the chart source.

1. Supply an additional values file using helm -f.
2. Alternatively, set the equivalent values in your GitOps configuration or parent chart so the rendered workload includes the desired RL_* environment variables.

Note

env is defined as a YAML list. By default, Helm replaces lists when both the base chart and an override define the same field, rather than merging them element by element.

To avoid this, you can:

• Copy the chart’s env block from values.yaml into your override file, update only the RL_* value fields while preserving all other required entries, and supply the file using -f.
• If the API Gateway is deployed as a subchart of a larger product chart, place the same structure under the appropriate subchart values key, which is the key that maps to this chart’s root values. Refer to that product’s deployment documentation for the correct key.

Override file format (full-values style) Copied

Follow this when you author or edit a values file for helm install or helm upgrade (-f) so its layout matches the chart, your RL_* entries stay valid, and merges with other value layers stay predictable.

When you pass -f my-values.yaml, that file is typically a custom values file that mirrors the chart’s default top-level structure. It may be based on the chart’s default values.yaml, the output of helm get values -o yaml from an existing release, or a consolidated file you maintain alongside the installation.

When creating a custom values file, it is important to stay consistent with the chart’s expected values structure. For example, a typical structure contains the following keys:

Abbreviated example:

docker:
  registry: your-registry.example.com

env:
  - name: ANALYTICS_CACHE_ENABLED
    value: "true"
  - name: OBCERV_APP_APISERVICE_SERVICE_GRPC_DEADLINE_SECONDS
    value: "60"
  # … keep every other non-RL variable your deployment needs …
  - name: RL_DEFAULT_LIMIT_FOR_PERIOD
    value: "50"
  - name: RL_DEFAULT_LIMIT_REFRESH_PERIOD
    value: "10s"
  - name: RL_GET_METRICS_LIMIT_FOR_PERIOD
    value: "100"
  - name: RL_GET_METRICS_LIMIT_REFRESH_PERIOD
    value: "10s"
  # … one LIMIT_FOR_PERIOD + one LIMIT_REFRESH_PERIOD per RPC you override …

image:
  repository: your-org/obcerv-app-api-gateway
  tag: "2.9.0"

ingress:
  path: /obcerv-app-api-gateway/

internal:
  mesh:
    inbound:
      timeout:
        connect: 60s
    resources:
      limits:
        cpu: "1"
        memory: 2Gi
      requests:
        cpu: 20m
        memory: 32Mi

resources:
  limits:
    cpu: 1500m
    memory: 2Gi
  requests:
    cpu: 100m
    memory: 256Mi

service:
  name: obcerv-app-api-gateway

# Optional: nested keys for shared Web Platform charts, if your product uses them
obcerv-app-helm-charts-spring-wp:
  global: {}
  obcerv-app-helm-charts-common:
    global: {}

Copy the complete env list from the chart defaults or from your cluster’s exported values, then change only the value fields you need. Omitting unrelated root keys is only safe if your Helm invocation still supplies the rest of the values (for example, through another -f layer or chart defaults). Otherwise, keep the same full structure your install already uses.

Note

Rebuilding the application container image is not required to change rate limits. Only the pod environment must be updated for Spring to read the new RL_* values at startup.

Analytics Copied

Get summary statistics grouped by dimensions or attributes Copied

POST /analytics/grouped-summary-statistics

Returns summary statistics grouped by dimensions or attributes over a historical period. The calculation uses a map step (one statistic per bucket per series) and a reduce step (aggregate across buckets).

Parameters Copied

Example Request Copied

{
  "metric": {
    "namespace": "itrsgroup.com/c2/kubernetes-plugin",
    "name": "kube_container_cpu_limit"
  },
  "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 parameters
• 404 Not Found — Metric not found
• default — Error body may follow Status

Get seasonal model for time-series data Copied

POST /analytics/models/seasonal

Returns a seasonal model by aggregating buckets across integer multiples of the supplied periodicity. Use this to compare current behavior to a typical seasonal profile (for example hourly patterns within a week).

Parameters Copied

Example Request Copied

{
  "metric": {
    "namespace": "itrsgroup.com/c2/kubernetes-plugin",
    "name": "kube_container_mem_limit_usage"
  },
  "entityFilter": {
    "dimensions": {
      "dimensions": {
        "container": "dpd"
      }
    }
  },
  "latestLookbackTs": "2023-07-21T08:00:00Z",
  "numPeriods": 12,
  "periodicity": "INTERVAL_1_WEEK",
  "bucketSize": "INTERVAL_1_HOUR",
  "aggregations": {
    "functions": [
      {
        "function": "BUCKET_FUNCTION_PERCENTILE",
        "percentile": 5
      },
      {
        "function": "BUCKET_FUNCTION_PERCENTILE",
        "percentile": 95
      },
      {
        "function": "BUCKET_FUNCTION_MIN"
      },
      {
        "function": "BUCKET_FUNCTION_MAX"
      }
    ]
  }
}

Example Response Copied

{
  "unit": "UNIT_PERCENT",
  "dataPoints": [
    {
      "ts": "2023-07-14T00:00:00Z",
      "values": [
        {
          "function": "BUCKET_FUNCTION_PERCENTILE",
          "percentile": 5.0,
          "value": 12.34
        },
        {
          "function": "BUCKET_FUNCTION_PERCENTILE",
          "percentile": 95.0,
          "value": 77.66
        },
        {
          "function": "BUCKET_FUNCTION_MIN",
          "value": 8.12
        },
        {
          "function": "BUCKET_FUNCTION_MAX",
          "value": 89.45
        }
      ],
      "bucketCount": 12
    },
    {
      "ts": "2023-07-14T01:00:00Z",
      "values": [
        {
          "function": "BUCKET_FUNCTION_PERCENTILE",
          "percentile": 5.0,
          "value": 15.22
        },
        {
          "function": "BUCKET_FUNCTION_PERCENTILE",
          "percentile": 95.0,
          "value": 82.11
        },
        {
          "function": "BUCKET_FUNCTION_MIN",
          "value": 9.03
        },
        {
          "function": "BUCKET_FUNCTION_MAX",
          "value": 91.2
        }
      ],
      "bucketCount": 12
    },
    {
      "ts": "2023-07-14T02:00:00Z",
      "values": [
        {
          "function": "BUCKET_FUNCTION_PERCENTILE",
          "percentile": 5.0,
          "value": 18.56
        },
        {
          "function": "BUCKET_FUNCTION_PERCENTILE",
          "percentile": 95.0,
          "value": 79.33
        },
        {
          "function": "BUCKET_FUNCTION_MIN",
          "value": 10.45
        },
        {
          "function": "BUCKET_FUNCTION_MAX",
          "value": 88.9
        }
      ],
      "bucketCount": 11
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid parameters
• 404 Not Found — Metric not found
• default — Error body may follow Status

Get summary statistics for entities Copied

POST /analytics/summary-statistics

Returns summary statistics for one or more entities over a historical period using map–reduce aggregation (same family of operations as grouped statistics, without grouping).

Parameters Copied

Example Request Copied

{
  "metric": {
    "namespace": "itrsgroup.com/c2/kubernetes-plugin",
    "name": "kube_container_cpu_limit"
  },
  "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 parameters
• 404 Not Found — Metric not found
• default — Error body may follow Status

Entities Copied

Get entities Copied

POST /entities

Returns entities that match the filter, including dimensions, attributes, and available metrics for each entity.

Parameters Copied

Example Request Copied

{
  "filter": {
    "expression": "cluster='prod-k8s' AND namespace='itrs'",
    "dimensions": [
      {
        "key": "cluster",
        "value": "prod-k8s"
      },
      {
        "key": "namespace",
        "value": "itrs"
      }
    ],
    "mode": 0
  },
  "limit": 100
}

Example Response Copied

{
  "entities": [
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "node",
          "value": "worker-1"
        }
      ],
      "attributes": [
        {
          "namespace": "itrsgroup.com/c2/kubernetes-plugin",
          "name": "kubernetes.io/hostname",
          "value": {
            "string": "worker-1.example.com"
          },
          "unit": 0,
          "userWritable": false,
          "inheritable": false,
          "inherited": false
        }
      ],
      "metrics": [
        {
          "namespace": "itrsgroup.com/c2/kubernetes-plugin",
          "name": "kube_node_cpu_capacity",
          "type": "GAUGE",
          "unit": "MILLICORES"
        }
      ]
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Get the most recent entity severities Copied

POST /entities/severity/latest

Returns the latest severity per matching entity. Only entities that have a severity value are included.

Parameters Copied

Example Request Copied

{
  "filter": {
    "expression": "cluster='prod-k8s' AND namespace='itrs'"
  },
  "limit": 100
}

Example Response Copied

{
  "severities": [
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "node",
          "value": "worker-1"
        }
      ],
      "severity": "WARNING"
    },
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "node",
          "value": "worker-2"
        }
      ],
      "severity": "CRITICAL"
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Logs Copied

Get log data Copied

POST /logs/log-data

Returns log lines from a single log source (identified by entity dimensions, log namespace, and log name) over a time range. Optional logFilter narrows by message text, severity, trace/span IDs, or log attributes. Results are ordered by timestamp (newest first unless reverseSort is true).

Parameters Copied

Example Request Copied

{
  "dimensions": [
    { "key": "cluster", "value": "prod-k8s" },
    { "key": "namespace", "value": "itrs" },
    { "key": "pod", "value": "app-server-1" }
  ],
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "output.log",
  "from": "2026-01-01T08:00:00Z",
  "to": "2026-01-01T12:00:00Z",
  "logFilter": {
    "messageFilters": ["Exception"],
    "includedLogSeverities": ["LOG_SEVERITY_ERROR", "LOG_SEVERITY_CRITICAL"]
  },
  "maxResults": 100
}

Example Response Copied

{
  "logData": [
    {
      "dimensions": [
        { "key": "cluster", "value": "prod-k8s" },
        { "key": "namespace", "value": "itrs" },
        { "key": "pod", "value": "app-server-1" }
      ],
      "namespace": "itrsgroup.com/geneos",
      "name": "/opt/itrs/gateway/gateways/*/gateway.log",
      "timestamp": "2026-01-07T03:59:21.054Z",
      "message": "2026-01-07 03:59:21.054+0000 Exception: Forecaster Obcerv Data Access Token not available",
      "traceId": "",
      "spanId": "",
      "logAttributes": {
        "matchKey": "Exception",
        "itrsgroup.com/geneos/source_gateway": "Exchange Demo"
      },
      "logSeverity": "LOG_SEVERITY_CRITICAL"
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Get log sources Copied

POST /logs/log-sources

Returns log sources (files) that have entries matching the filter and time range, with counts and first/last timestamps. Results are ordered by the number of matching entries in descending order. Use the returned dimensions, namespace, and name with /logs/log-data to fetch lines.

Parameters Copied

Example Request Copied

{
  "filter": {
    "expression": "application='app1'"
  },
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "from": "2026-01-01T08:00:00Z",
  "to": "2026-01-01T23:59:59Z",
  "logFilter": {
    "messageFilters": ["Exception"]
  },
  "maxResults": 50
}

Example Response Copied

{
  "logSources": [
    {
      "dimensions": [
        { "key": "cluster", "value": "prod-k8s" },
        { "key": "application", "value": "app1" }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "output.log",
      "numMatchingEntries": 42,
      "firstMatchEntry": "2026-01-01T08:03:11Z",
      "lastMatchEntry": "2026-01-01T23:57:54Z"
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Lookup Copied

Lookup dimension, attribute, and metric names Copied

POST /lookup/names

Returns dimension, attribute, and metric names. Use filters to narrow by type, namespace, or name substring.

Parameters Copied

Example Request Copied

{
  "type": [
    "METRIC_GAUGE"
  ],
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "namePattern": "cpu",
  "limit": 50
}

Example Response Copied

{
  "names": [
    {
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_node_cpu_capacity",
      "types": [
        4
      ]
    },
    {
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_node_cpu_usage",
      "types": [
        4
      ]
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Lookup dimension and attribute values Copied

POST /lookup/values

Returns distinct values for a given dimension or attribute (namespace + name), optionally filtered by substring.

Parameters Copied

Example Request Copied

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kubernetes.io/hostname",
  "valuePattern": "worker",
  "limit": 50
}

Example Response Copied

{
  "values": [
    {
      "string": "derek-api1-node-1"
    },
    {
      "string": "derek-api1-node-2"
    },
    {
      "string": "derek-api1-control-1"
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Metrics Copied

Get bucketed metric time series Copied

POST /metrics

Returns time-series points for a metric over a range, aggregated into buckets. Required fields: namespace, name, and from.

Parameters Copied

Example Request Copied

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kube_pod_cpu_usage",
  "filter": {
    "expression": "cluster='prod-k8s' AND namespace='itrs'"
  },
  "from": "2024-10-15T10:00:00Z",
  "to": "2024-10-15T12:00:00Z",
  "bucketSize": "BUCKET_SIZE_FIVE_MINUTE",
  "bucketFunction": "BUCKET_FUNCTION_AVG",
  "metricType": "GAUGE"
}

bucketSize, bucketFunction, and metricType are integer enum values in the API (for example bucket size 6 for five-minute buckets and bucket function 1 for average, as in the schema examples).

Example Response Copied

{
  "metrics": [
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "namespace",
          "value": "itrs"
        },
        {
          "key": "pod",
          "value": "app-server-1"
        }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_pod_cpu_usage",
      "metricType": "GAUGE",
      "unit": "MILLICORES",
      "timestamp": "2024-10-15T10:00:00Z",
      "value": 0.45
    },
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "namespace",
          "value": "itrs"
        },
        {
          "key": "pod",
          "value": "app-server-2"
        }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_pod_cpu_usage",
      "metricType": "GAUGE",
      "unit": "MILLICORES",
      "timestamp": "2024-10-15T10:05:00Z",
      "value": 0.52
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Get the most recent metrics Copied

POST /metrics/latest

Returns the latest sample per entity for a metric (or metrics matching the filter). Optimized for live views.

Parameters Copied

Example Request Copied

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kube_pod_cpu_usage",
  "filter": {
    "expression": "cluster='prod-k8s' AND namespace='itrs'"
  },
  "limit": 100
}

Example Response Copied

{
  "metrics": [
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "namespace",
          "value": "itrs"
        },
        {
          "key": "pod",
          "value": "app-server-1"
        }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_pod_cpu_usage",
      "metricType": "GAUGE",
      "unit": "MILLICORES",
      "timestamp": "2024-10-15T14:32:15Z",
      "value": 0.45
    },
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "namespace",
          "value": "itrs"
        },
        {
          "key": "pod",
          "value": "app-server-2"
        }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_pod_cpu_usage",
      "metricType": "GAUGE",
      "unit": "MILLICORES",
      "timestamp": "2024-10-15T14:32:18Z",
      "value": 0.62
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Get the latest status metrics Copied

POST /status-metrics/latest

Returns the most recent status string per entity for a status metric within a time window. Required: namespace, name, and from.

Parameters Copied

Example Request Copied

{
  "namespace": "itrsgroup.com/c2/kubernetes-plugin",
  "name": "kube_pod_status",
  "filter": {
    "expression": "cluster='prod-k8s' AND namespace='itrs'"
  },
  "from": "2024-10-15T10:00:00Z",
  "to": "2024-10-15T11:00:00Z"
}

Example Response Copied

{
  "statusMetrics": [
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "namespace",
          "value": "itrs"
        },
        {
          "key": "pod",
          "value": "app-server-1"
        }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_pod_status",
      "timestamp": "2024-10-15T10:28:45Z",
      "value": "Running"
    },
    {
      "dimensions": [
        {
          "key": "cluster",
          "value": "prod-k8s"
        },
        {
          "key": "namespace",
          "value": "itrs"
        },
        {
          "key": "pod",
          "value": "app-server-2"
        }
      ],
      "namespace": "itrsgroup.com/c2/kubernetes-plugin",
      "name": "kube_pod_status",
      "timestamp": "2024-10-15T10:29:12Z",
      "value": "CrashLoopBackOff"
    }
  ]
}

Response Codes Copied

• 200 OK — Success
• 400 Bad Request — Invalid request
• default — Error body may follow Status

Schemas Copied

The following request and response models are defined by the API (listed in alphabetical order).

AggregationResult Copied

The aggregated value and the aggregation it corresponds to

Any Copied

Wrapper for a protobuf Any value plus optional YAML. Used inside NamedAny for structured expression payloads.

Dimension Copied

A key-value pair representing a hierarchical identifier for entities. Dimensions form the unique identity of an entity and are ordered from highest to lowest in the hierarchy (e.g., cluster > namespace > pod > container).

Entity Copied

A monitored entity in the observability platform. Entities are uniquely identified by their dimensions, contain metadata in attributes, and have associated metrics for monitoring.

EntityArtifactFilter Copied

Restricts EntityFilter to entities that have specific artifacts (for example named configuration or deployment objects).

EntityAttribute Copied

A metadata attribute associated with an entity. Attributes provide descriptive information about entities, such as configuration details, labels, tags, and dynamic properties.

EntityFilter Copied

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

EntityMetric Copied

Metadata about a metric available for this entity. This describes what can be measured, but does not contain actual metric values. Use the /metrics or /metrics/latest endpoints to retrieve actual time-series data or latest values.

Expression Copied

Protobuf-compatible expression tree used inside EntityFilter. The published OpenAPI mirrors the internal message shape; for typical HTTP JSON usage, prefer the string expression field on Filter for entity queries.

Filter Copied

Filter for querying entities. Supports two filtering modes:

1. Expression filter: Use a query language for complex filtering (e.g., “node=‘worker-1’ AND namespace=‘production’”)

2. Dimensions filter: Match entities by dimension key-value pairs with a specified mode:

   • ANY: Matches entities containing these dimensions (may have additional dimensions)
   • EXACT: Exact match - entities must have exactly these dimensions, no more, no less

Note

Use either expression OR dimensions, not both. Expression provides more flexibility, while dimensions offer simpler matching.

GetEntitiesRequest Copied

Query entities from the observability platform based on filtering criteria. Entities represent monitored infrastructure components such as:

• Kubernetes nodes, pods, containers, and services

• Virtual machines and hosts

• Applications and processes

• Network devices and interfaces

Each entity has dimensions (hierarchical identifiers), attributes (metadata properties), and metrics (available measurements). Filtering can be done using:

• Expression filter — Query language for complex filtering (e.g., “node=‘worker-1’ AND namespace=‘production’”)

• Dimensions filter — Simple key-value pair matching with ANY or EXACT mode

Note

Use either expression OR dimensions in the filter, not both. Expression provides more flexibility with logical operators (AND, OR, NOT), while dimensions offer simpler exact or partial matching.

It is recommended to use specific filters to reduce result size and improve response times.

GetEntitiesResponse Copied

List of entities matching the request filter. Each entity includes its complete hierarchy of dimensions, all attributes with their current values, and the list of available metrics.

GetEntitySeveritiesRequest Copied

Query the latest severity values for entities matching the specified filter criteria. Severity represents the current health or alert state of an entity, indicating how critical its condition is.

Severity values follow the SignalSeverity enumeration:

• NONE (1) — No severity associated, typically used to clear a pre-existing signal

• WARNING (2) — Issue that may require attention

• CRITICAL (3) — Severe issue requiring immediate action

• OK (4) — Entity is healthy, no issues detected

Filtering can be done using:

• Expression filter — Query language for complex filtering (e.g., “node=‘worker-1’ AND namespace=‘production’”)

• Dimensions filter — Simple key-value pair matching with ANY or EXACT mode

Note

Only entities that have a severity value will be returned. The endpoint automatically applies a ‘severity EXISTS’ filter to exclude entities without severity data.

It is recommended to use specific filters to reduce result size and improve response times.

GetEntitySeveritiesResponse Copied

List of entity severities matching the request filter. Each result includes the entity’s dimensions for identification and its current severity value.

GetEntitySeveritiesResponse_Severity Copied

An entity’s severity information, combining the entity’s identifying dimensions with its current severity level.

GetGroupedSummaryStatisticsRequest Copied

Returns grouped summary statistics based on the supplied parameters:

• metric — The namespace and name of the metric.
• entityFilter — Defines a set of ordered/unordered dimensions that can only match up to one entity or an expression. If an expression is provided and it matches more than one entity then the metric values of all these entities will be indiscriminately contribute to the summary statistics.
• from/to — The historical period the summary statistics will be based on.
• aggregations — One or more statistical aggregations to return.
• groupBy — The dimensions or attributes to group the summary statistics by.

GetGroupedSummaryStatisticsResponse Copied

A list of grouped aggregated values based on the supplied parameters

GetLogDataRequest Copied

Request to retrieve log data from a single log source, over the specified time range and filtering criteria.

GetLogDataResponse Copied

Response containing log data entries from a single log source.

GetLogSourcesRequest Copied

Request to retrieve log sources that match filtering criteria over a time range.

GetLogSourcesResponse Copied

Response containing log sources. Each entry is one log source with summary stats for the matching window.

GetMetricsLatestRequest Copied

Request to retrieve the most recent metrics given the filtering criteria. This endpoint is optimized for real-time monitoring scenarios where only the current value is needed, not historical time-series data.

Filtering options — at least one of the following must be provided:

• namespace and name — Retrieve a specific metric for all entities that have it
• filter — Restrict results to specific entities using expression or dimension-based filtering

If both are specified, they are combined (AND logic) to return the specific metric for matching entities only.

Use the limit parameter to control the maximum number of results returned (default: 100, max: 10,000).

GetMetricsLatestResponse Copied

Response containing the most recent metrics given the filtering criteria. Each metric represents the latest measurement for a specific entity, including entity identification, metric metadata, and the current value.

GetMetricsRequest Copied

Request to retrieve time-series metric data aggregated into time buckets. This is the primary request for querying historical metric measurements for visualization, analysis, and monitoring.

Required parameters — namespace, name, from

Optional parameters — filter, group_by, to (defaults to now), bucket_size (defaults to platform behavior if omitted), bucket_function (defaults to LAST), percentile (when bucket_function is PERCENTILE), metric_type.

Time range — Specify the historical period using from and to timestamps. For raw (un-bucketed) data using BUCKET_SIZE_NONE, the maximum time range is 30 minutes. For bucketed data, larger time ranges are supported depending on the bucket size.

Filtering — Use the filter parameter to restrict results to specific entities. Supports both expression-based filtering (e.g., “cluster=‘prod’ AND namespace=‘default’”) and dimension-based filtering.

Grouping — Use group_by to aggregate metrics across multiple entities by specific dimensions, producing a single time-series per unique dimension value combination.

Metric type — Use the optional metric_type parameter to specify whether to retrieve GAUGE or COUNTER metrics. If not specified, both GAUGE and COUNTER metrics are retrieved.

GetMetricsResponse Copied

Response containing time-series metric data. Returns an array of metric data points, where each point represents a single measurement at a specific time for a specific entity. Data points are organized by entity (identified by dimensions) and ordered by timestamp within each entity’s time-series.

GetSeasonalModelRequest Copied

Generates a seasonal model based on the supplied parameters:

• metric — The namespace, name, and type (optional) of the metric to base the model on

• entityFilter — Targets the entity that the model is going to be based on

• latestLookbackTs — An exclusive timestamp of the latest lookback data to include in the model

• periodicity: The model’s periodicity. Defines the length of the seasonal period of the historical data. Buckets within each season will be merged with buckets 1..N number of seasons apart where N is the supplied number of periods.

• bucketSize — The length of the buckets the model will return. It must be a factor of the periodicity

• numPeriods — The number of seasonal periods to include in the model’s evaluation. A high number may reduce the impact of outliers. When setting this consider whether the data during this time has been consistent with what is considered ’normal’. If the data within the look-back period contain irregularities then consider increasing the number of seasonal periods. Note that setting this to a very high number may have a severe impact on performance, particularly if the bucket size is small.

• aggregations — One or more statistical aggregations to return for each bucket

GetSeasonalModelResponse Copied

A seasonal model as a time series of aggregated buckets. Each model data point contains a timestamp, the number of buckets that were aggregated together, the total number of metric values, and the requested aggregations.

GetStatusMetricsLatestRequest Copied

Request to retrieve the most recent status metric values for entities. Status metrics represent discrete state or condition values (such as ‘OK’, ‘WARNING’, ‘ERROR’, ‘Running’, ‘Stopped’) that indicate the health, operational state, or alert level of monitored entities.

Key characteristics:

• Returns only the latest or most recent status value for each matching entity
• No time-series data or historical values - just the current state

Required parameters — namespace, name, from

Optional parameters — filter, to (defaults to now).

The endpoint returns the most recent status value within this window for each entity.

GetStatusMetricsLatestResponse Copied

Response containing the latest status metric values for matching entities. Returns one status value per entity, representing the most recent state within the specified time window. Each result includes the entity identification, status metric metadata, timestamp of the status, and the status value itself.

GetSummaryStatisticsRequest Copied

Returns summary statistics based on the supplied parameters:

• metric — The namespace and name of the metric
• entityFilter — Defines a set of ordered/unordered dimensions that can only match up to one entity or an expression. If an expression is provided and it matches more than one entity then the metric values of all these entities will be indiscriminately contribute to the summary statistics
• from/to — The historical period the summary statistics will be based on
• aggregations — One or more statistical aggregations to return

GetSummaryStatisticsResponse Copied

A list of aggregated values based on the supplied parameters

GoogleProtobufAny Copied

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

LogAttributeFilterExpression Copied

Defines a filter on log entry logAttributes so only entries whose attributes match are returned. If both keyFilter and valueFilter are set on a term, both must match.

LogAttributeFilterExpression_LogAttributeFilterTerm Copied

One attribute key/value match term for log attribute maps.

LogData Copied

A single log row from a log source for a specific entity.

LogFilter Copied

Optional filters applied to log queries. messageFilters entries are ORed together.

LogSource Copied

One log source identified by dimensions, namespace, and name, with match statistics for the query window.

LookupNamesRequest Copied

Discover available dimension, attribute, and metric names in the system. This endpoint enables discovery of what can be queried and is particularly useful for building dynamic UIs, discovering available metrics for monitoring, and implementing auto-completion features.

Supports filtering by:

• type — Filter by specific types. Multiple types can be combined:

  • DIMENSION (1) — Entity hierarchical identifiers
  • ATTRIBUTE (2) — Entity metadata properties
  • METRIC_COUNTER (3) — Monotonically increasing metrics
  • METRIC_GAUGE (4) — Metrics that can increase or decrease
  • METRIC_HISTOGRAM (5) — Distribution metrics
  • METRIC_STATUS (6) — Status/health metrics

• namespace — Restrict results to a specific namespace (e.g., ‘itrsgroup.com/c2/kubernetes-plugin’)

• namePattern — Search for names containing a specific pattern (case-sensitive substring match)

• limit — Maximum number of results to return (default: 100, max: 1000)

Important

You can request either entity types (dimensions/attributes) OR metric types (counter/gauge/histogram/status), but not both in the same request.

LookupNamesResponse Copied

List of matching names with their namespace, name, and applicable types.

LookupValuesRequest Copied

Retrieve all possible values for a specific dimension or attribute. This endpoint returns the complete set of unique values that exist across all entities in the system.

Use cases:

• Building dynamic filter dropdowns showing actual available values (e.g., all cluster names, all namespaces, all node hostnames)

• Discovering what entities exist by dimension value (e.g., “what clusters do we have?”)

• Validating user input against known values

• Implementing auto-completion features in search interfaces

• Exploring the entity hierarchy (e.g., which namespaces exist in a cluster)

Required parameters — The namespace and name parameters are required to identify which specific dimension or attribute to query. Use the LookupNames endpoint first to discover available dimensions and attributes if needed.

Optional filtering — Results can be filtered using valuePattern for case-sensitive substring matching, useful for large value sets or search-as-you-type functionality.

LookupValuesResponse Copied

List of unique values for the specified dimension or attribute. Values are returned in their native type (string, number, boolean, timestamp, or string list).

MapReduceAnalyticsFunction Copied

Extracts statistics from each time series in the result set based on the map function and reduces it to a single scalar value by applying the reduce function over the values extracted by the map phase. BUCKET_FUNCTION_RATE is not supported in the map phase. BUCKET_FUNCTION_RATE, BUCKET_FUNCTION_FIRST, BUCKET_FUNCTION_LAST are not supported in the reduce phase.

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

Metric Copied

A single metric data point representing a measurement at a specific time for a specific entity. Includes the entity identification (dimensions), metric metadata (namespace, name, type, unit), timestamp, and the measured value.

ModelDataPointValue Copied

A single aggregated value

ModelEntityFilter Copied

Targets a single entity for seasonal modelling. Supply exactly one of the following:

Name Copied

A named entity or metric with its namespace, name, and applicable types.

NamedAny Copied

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

NamespacedName Copied

Qualified name within a namespace (used for attributes, metrics, and artifact references).

OrderedDimensionsFilter Copied

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

SeasonalModelDataPoint Copied

Each seasonal model data point consists of a timestamp and set of one or more aggregated values as supplied in the request. Additionally, the response contains two counts that can aid evaluating the reliability of the data point. These are:

• bucketCount — The number of historical buckets that were combined to generate the model data point. For example, if the look-back period is 12 weeks and the periodicity is 1 week then for each model data point the maximum number of buckets that can be combined is 12. If the count is very low it indicates gap in the data during the look-back window. If the count is 0, then no data was found and the model data point should be ignored.

StatisticalAggregationFunction Copied

The aggregation function to apply on the metric datapoints. If the aggregation function is BUCKET_FUNCTION_PERCENTILE then the percentile must be set to a value in the exclusive range (0, 100).

StatisticalModelAggregations Copied

Specifies one or more statistical aggregations to calculate and return for each bucket

Status Copied

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

StatusMetrics Copied

A single status metric value representing the latest state of a specific entity. Status values are categorical strings (not numbers) that indicate health, operational state, or alert level. Common status values include ‘Running’, ‘Pending’, ‘Failed’, ‘OK’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’, ‘Unknown’, etc.

StringList Copied

A list of string values, used for multi-valued attributes.

SummaryStatisticsGroup Copied

SummaryStatisticsGroupBy Copied

The dimensions or attributes to group the summary statistics by

SummaryStatisticsGroupBy_GroupByAttribute Copied

The attribute to group by

SummaryStatisticsGroup_GroupByAttributeValue Copied

TargetMetric Copied

Identifies a metric by namespace and name (and optionally type for seasonal models).

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

UnorderedDimensionsFilter Copied

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

Value Copied

A polymorphic value that can hold different types. The actual type is indicated by which field is set in the oneof. The displayValue provides a human-readable representation useful for UI display.

Units enumeration Copied

Numeric unit fields in the API use the platform unit enumeration (for example millicores, bytes, percent). The full set matches the protobuf Unit enum used by the analytics platform. Prefer the lookup and metrics responses for the unit applicable to each series.