コンテンツにスキップ
Yagra

Fleet-wide Top-N for a metric: the highest-value nodes right now (or by hourly peak). Powers the dashboard "Top RTT / CPU / memory / …" widgets from one endpoint.

GET
/api/v1/metrics/top
curl --request GET \
  --url 'https://example.com/api/v1/metrics/top?metric=example' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
metric
required
string

Metric to rank by (validated identifier, or a logical alias).

agg
string

now (default) ⇒ most recent value; max_1h ⇒ trailing-hour peak.

limit
integer

How many nodes to return (default 5, clamped 1..=50).

Responses

Section titled “Responses”

200

Section titled “200”

The highest-value nodes, ranked; partial says the scope filter may have shortened the list

Media typeapplication/json

A ranked Top-N result.

object
entries
required

The ranked rows, highest first, at most the requested limit.

Array<object>

One ranked node in a Top-N result.

object
name
required

Display name, joined from PostgreSQL (ADR-011); falls back to the id string if the node has since been deleted.

string
node_id
required
string format: uuid
value
required
number format: double
partial
required

true when this ranking covers only the groups the calling account may see and entries it is entitled to may be missing. Always false for an account with unrestricted visibility.

boolean
Examplegenerated
{
  "entries": [
    {
      "name": "example",
      "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "value": 1
    }
  ],
  "partial": true
}

400

Section titled “400”

metric is neither a logical alias nor an identifier, or agg is unsupported

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks the read permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}