Metrics API Reference

Kloudfuse serves the standard Prometheus HTTP API, so any Prometheus-compatible client works unchanged. All endpoints use GET, take the PromQL expression in the query parameter, and are served directly on your Kloudfuse hostname. The Metrics Explorer's query builder constructs and runs these same requests behind the scenes.

Replace <your-instance> with your Kloudfuse hostname and <sa-token> with a valid Service Account token.

curl -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/api/v1/query?query=<promql>"
bash

For Service Account token setup, see Authentication. Failed requests return the standardized status codes and JSON error payload described in API Response Codes.

Instant query

GET /api/v1/query evaluates a PromQL expression once, at a single point in time, and returns a vector result — one sample per series.

Parameters:

Parameter Type Required Description

query

string

Yes

The PromQL expression to evaluate.

time

Unix seconds

No

Evaluation timestamp. Default: now.
Top Kloudfuse services by goroutine count
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/api/v1/query" \
     --data-urlencode 'query=topk(2, sum by (app_kubernetes_io_name) (go_goroutines{app_kubernetes_io_instance="kfuse"}))' \
     --data-urlencode "time=$(date -u +%s)"
bash
Response
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": { "app_kubernetes_io_name": "trace-transformer" },
        "value": [1783216799, "106443"]
      },
      {
        "metric": { "app_kubernetes_io_name": "ingester" },
        "value": [1783216799, "105951"]
      }
    ]
  }
}
json

Range query

GET /api/v1/query_range evaluates a PromQL expression at every step across a time range and returns a matrix result — one array of [timestamp, value] samples per series. This is the endpoint behind dashboard panels.

Parameters:

Parameter Type Required Description

query

string

Yes

The PromQL expression to evaluate.

start

Unix seconds

Yes

Start of the range.

end

Unix seconds

Yes

End of the range.

step

seconds

Yes

Resolution: one evaluation per step.
Ingester Kafka consumption rate at one-minute resolution
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/api/v1/query_range" \
     --data-urlencode 'query=sum(rate(ingester_kafka_batch_length_count[5m]))' \
     --data-urlencode "start=$(date -u -v-3M +%s)" \
     --data-urlencode "end=$(date -u +%s)" \
     --data-urlencode "step=60"
bash
Response
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {},
        "values": [
          [1783216619, "499231.209575953"],
          [1783216679, "499430.6628708646"],
          [1783216739, "490244.2783889528"],
          [1783216799, "484306.3455091215"]
        ]
      }
    ]
  }
}
json

Label values

GET /api/v1/label/{name}/values lists the values of one label. Add a match[] selector to restrict the values to series matching an expression — the usual way to discover what exists before writing a query.

Parameters:

Parameter Type Required Description

{name}

path

Yes

The label to enumerate.

match[]

selector

No

Restrict to series matching this selector.

start, end

Unix seconds

No

Restrict to series active in this range.
Kloudfuse service names carrying the goroutine gauge
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/api/v1/label/app_kubernetes_io_name/values" \
     --data-urlencode 'match[]=go_goroutines{app_kubernetes_io_instance="kfuse"}'
bash
Response (truncated)
{
  "status": "success",
  "data": ["analytics-service", "archive-writer", "az-service",
           "config-mgmt-service", "envoy-gateway", "events-query-service",
           "ingester", "logs-query-service", "..."]
}
json
To enumerate metric names themselves, request the values of the reserved __name__ label: /api/v1/label/name/values.

Series

GET /api/v1/series lists the full label sets of series matching one or more selectors.

Parameters:

Parameter Type Required Description

match[]

selector

Yes

One or more series selectors (repeat the parameter).

start, end

Unix seconds

Yes

Range the series must be active in.
Series of the query-service goroutine gauge
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/api/v1/series" \
     --data-urlencode 'match[]=go_goroutines{app_kubernetes_io_name="query-service"}' \
     --data-urlencode "start=$(date -u -v-10M +%s)" \
     --data-urlencode "end=$(date -u +%s)"
bash
Response (truncated)
{
  "status": "success",
  "data": [
    {
      "__name__": "go_goroutines",
      "app_kubernetes_io_instance": "kfuse",
      "app_kubernetes_io_name": "query-service",
      "availability_zone": "eu-central-1a",
      "...": "..."
    }
  ]
}
json

Metric metadata

GET /api/v1/metadata returns the type, help text, and unit recorded for a metric.

Parameters:

Parameter Type Required Description

metric

string

No

Return metadata for this metric only.
Metadata for go_goroutines
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/api/v1/metadata" \
     --data-urlencode "metric=go_goroutines"
bash
Response
{
  "status": "success",
  "data": {
    "go_goroutines": [
      { "type": "gauge", "help": "Number of goroutines that currently exist.", "unit": "" }
    ]
  }
}
json

Label names

GET /api/v1/labels lists label names. On Kloudfuse this endpoint returns a minimal set; for practical discovery, prefer Label values with a match[] selector or Series, which return the labels in the context of actual series.