Granular metrics requests

Granular metrics collection requests

These requests manage the granular tier of local metrics storage. None of them take a request body.

Get granular metrics status

GET /v1/metrics/granular/status

Get the granular metrics collection status of all nodes or of a specific node.

Required permissions

Request

Example HTTP request

GET /v1/metrics/granular/status

Request headers

Query parameters

Response

Returns a nodes array with one object for each node in scope.

Example JSON body

{
  "nodes": [
    { "uid": "1", "state": "running", "started_at": 1771770600, "expires_in_sec": 2820 },
    { "uid": "2", "state": "stopped", "stopped_at": 1771770600, "auto_cleanup_in_sec": 82800, "disk_usage_bytes": 131072000 }
  ]
}

Node status fields

Timestamps are Unix epoch seconds.

Status codes

Start granular metrics collection

POST /v1/metrics/granular/start

Start granular metrics collection on all nodes or on a specific node. Collection stops automatically after the maximum duration set in granular_metrics_job_settings.

The request is idempotent. Starting collection on a node where it's already running returns already_running.

Required permissions

Request

Example HTTP request

POST /v1/metrics/granular/start

Request headers

Query parameters

Response

Returns a results array with one object for each node in scope.

Example JSON body

{
  "results": [
    { "uid": "1", "outcome": "started", "started_at": 1771770600, "expires_at": 1771774200 },
    { "uid": "2", "outcome": "already_running", "started_at": 1771769000, "expires_at": 1771772600 },
    { "uid": "3", "outcome": "unknown" }
  ]
}

Result fields

Timestamps are Unix epoch seconds.

Status codes

Stop granular metrics collection

POST /v1/metrics/granular/stop

Stop granular metrics collection on all nodes or on a specific node. The collected data stays on disk until it's deleted or the cleanup delay set in granular_metrics_job_settings passes.

The request is idempotent. Stopping collection on a node where it isn't running returns already_stopped.

Required permissions

Request

Example HTTP request

POST /v1/metrics/granular/stop

Request headers

Query parameters

Response

Returns a results array with one object for each node in scope.

Example JSON body

{
  "results": [
    { "uid": "1", "outcome": "stopped", "stopped_at": 1771774200, "ran_for_sec": 3600 },
    { "uid": "2", "outcome": "already_stopped" }
  ]
}

Result fields

Status codes

Delete granular metrics data

DELETE /v1/metrics/granular/data

Delete granular metrics data from all nodes or from a specific node.

If granular collection is still running on any node in scope, the request fails with 409 Conflict. The cluster is checked before any node's data is deleted, so a failed request deletes nothing. Stop collection on those nodes first.

Required permissions

Request

Example HTTP request

DELETE /v1/metrics/granular/data

Request headers

Query parameters

Response

Returns a results array with one object for each node in scope.

Example JSON body

{
  "results": [
    { "uid": "1", "outcome": "deleted", "freed_bytes": 131072000 },
    { "uid": "2", "outcome": "no_data" }
  ]
}

Result fields

Example error response

If granular collection is still running on any node in scope, the response lists those nodes:

{
  "error_code": "granular_metrics_running",
  "description": "cannot cleanup granular metrics — still running on 1 node(s)",
  "running_nodes": [ { "uid": "1", "started_at": 1771770600 } ]
}

Status codes