Metrics API Reference :: Kloudfuse Docs

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.

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>"

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)"

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"]
      }
    ]
  }
}

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"

Response

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {},
        "values": [
          [1783216619, "499231.209575953"],
          [1783216679, "499430.6628708646"],
          [1783216739, "490244.2783889528"],
          [1783216799, "484306.3455091215"]
        ]
      }
    ]
  }
}

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"}'

Response (truncated)

{
  "status": "success",
  "data": ["analytics-service", "archive-writer", "az-service",
           "config-mgmt-service", "envoy-gateway", "events-query-service",
           "ingester", "logs-query-service", "..." ]
}
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)"

Response (truncated)

{
  "status": "success",
  "data": [
    {
      "__name__": "go_goroutines",
      "app_kubernetes_io_instance": "kfuse",
      "app_kubernetes_io_name": "query-service",
      "availability_zone": "eu-central-1a",
      "...": "..."
    }
  ]
}

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"

Response

{
  "status": "success",
  "data": {
    "go_goroutines": [
      { "type": "gauge", "help": "Number of goroutines that currently exist.", "unit": "" }
    ]
  }
}

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.