Skip to content
F5 Distributed CloudStatistics
Aa

Query reference

The configuration and telemetry APIs use different identifiers for the same load balancer. Run identifier discovery in the Bash session prepared in Set up cURL.

Identifiers

Section titled “Identifiers”
VariableMeaningSource
XCSH_NAMESPACEDemo namespaceSelected namespace
XCSH_LB_NAMEConfiguration object nameSelected load balancer name
XCSH_DOMAINNAMEPublic HTTPS hostnameSelected application hostname
XCSH_VIRTUAL_HOSTTelemetry virtual hostUnique service graph match below
XCSH_API_DISCOVERY_ENABLEDWhether API discovery is enabledLoad balancer configuration below
XCSH_APP_TYPEApp type used by API inventoryExact ves.io/app_type label below
XCSH_ORIGIN_POOL, XCSH_ORIGIN_IPConfigured pool and public-IP originOrigin performance
XCSH_GRAPH_SOURCE, XCSH_GRAPH_DESTINATIONServices at each end of the origin request edgeOrigin performance; exact configured address match

In Customize examples → Telemetry and deployment examples, replace the illustrative defaults with exact values returned by discovery. Each field is independent: editing the load balancer never infers its telemetry identity. Clearing a noncredential field immediately restores its default in examples; leaving the field repopulates the input. Reset shared values restores all noncredential defaults. Account identifiers retain angle-bracket placeholders until you supply them.

The synthetic example uses virtual host telemetry-demo-app, application type demo-app, origin address 198.51.100.10, graph source public, destination S:198.51.100.10, and endpoints /health, /httpbin/get, and /vampi. Origin and generator VM names are vm-origin-server-demoapp and vm-traffic-generator-demoapp; the pinned Terraform modules normalize deployer demo-app to demoapp. Replace these with discovered values before querying your deployment. Recorded response identifiers follow the form; captured times, counts, and metric values stay unchanged.

Leave the token field empty to render $XCSH_API_TOKEN in shell commands. An entered token stays in this tab’s session and appears in copied inline commands. Clear credentials restores the environment reference. Downloadable scripts keep runtime credentials in the environment.

Selected namespace: <XCSH_NAMESPACE>; load balancer: <XCSH_LB_NAME>; telemetry virtual host: <XCSH_VIRTUAL_HOST>; application type: <XCSH_APP_TYPE>.

Read the load balancer identifiers

Section titled “Read the load balancer identifiers”

  1. Fetch the load balancer configuration.

    Terminal window
    XCSH_LB_JSON="$(curl --silent --show-error --fail-with-body \
      --header "Authorization: APIToken <XCSH_API_TOKEN>" \
      --header 'Accept: application/json' \
      "<XCSH_API_URL>/api/config/namespaces/<XCSH_NAMESPACE>/http_loadbalancers/<XCSH_LB_NAME>")"

  2. Read its API discovery state and app type.

    Terminal window
    XCSH_API_DISCOVERY_ENABLED="$(jq -er '(.spec.enable_api_discovery != null)' <<<"$XCSH_LB_JSON")"
    XCSH_APP_TYPE="$(jq -r '.metadata.labels["ves.io/app_type"] // empty' <<<"$XCSH_LB_JSON")"
    export XCSH_API_DISCOVERY_ENABLED XCSH_APP_TYPE
    jq -er '{name: .metadata.name, namespace: .metadata.namespace,
      waf: .spec.app_firewall.name,
      api_discovery_enabled: (.spec.enable_api_discovery != null)}' <<<"$XCSH_LB_JSON"

Observed load balancer response

Section titled “Observed load balancer response”

Captured 2026-10-06T03:13:41Z; HTTP 200.

{
  "name": "<XCSH_LB_NAME>",
  "namespace": "<XCSH_NAMESPACE>",
  "waf": "<XCSH_WAF_NAME>",
  "api_discovery_enabled": true
}

Find the telemetry virtual host

Section titled “Find the telemetry virtual host”

  1. Request active service graph nodes in the current window.

    Terminal window
    XCSH_REQUEST="$(jq -nc --arg ns "<XCSH_NAMESPACE>" --arg start "$XCSH_START_TIME" \
      --arg end "$XCSH_END_TIME" '{
        namespace: $ns, start_time: $start, end_time: $end,
        step: "5m", range: "5m", group_by: ["VHOST"],
        field_selector: {node: {metric: {upstream: ["HTTP_REQUEST_RATE"]}}}
      }')"
    XCSH_GRAPH_JSON="$(curl --silent --show-error --fail-with-body \
      --request POST \
      --header "Authorization: APIToken <XCSH_API_TOKEN>" \
      --header 'Content-Type: application/json' \
      --data-binary "$XCSH_REQUEST" \
      "<XCSH_API_URL>/api/data/namespaces/<XCSH_NAMESPACE>/graph/service")"

  2. Select this load balancer’s unique virtual host.

    Terminal window
    XCSH_VIRTUAL_HOST="$(jq -er --arg suffix "-<XCSH_LB_NAME>" '
      [.data.nodes[]?.id.vhost // empty | select(endswith($suffix))]
      | unique
      | if length == 1 then .[0] else error("Expected one demo VHOST") end
    ' <<<"$XCSH_GRAPH_JSON")"
    export XCSH_VIRTUAL_HOST
    printf 'XCSH_VIRTUAL_HOST=%s\n' "$XCSH_VIRTUAL_HOST"

Observed virtual-host selection

Section titled “Observed virtual-host selection”

Captured 2026-10-06 02:22:43 UTC; the service graph request returned HTTP 200.

XCSH_VIRTUAL_HOST=<XCSH_VIRTUAL_HOST>

The configuration name, telemetry XCSH_VIRTUAL_HOST, and XCSH_APP_TYPE serve different APIs. Check the generator timer and allow for telemetry delay if the graph has no matching node.

Refresh the time window

Section titled “Refresh the time window”

The queries use a two-hour window for metrics and access logs and a 24-hour window for security events. Times are Unix epoch seconds in UTC (Coordinated Universal Time). The API accepts them as strings. Refresh all three values before a later query:

Terminal window
export XCSH_END_TIME="$(date -u +%s)"
export XCSH_START_TIME="$((XCSH_END_TIME - 7200))"
export XCSH_START_24H="$((XCSH_END_TIME - 86400))"
test "$XCSH_START_24H" -lt "$XCSH_START_TIME"
test "$XCSH_START_TIME" -lt "$XCSH_END_TIME"

A reversed window can return HTTP 500.

Read responses consistently

Section titled “Read responses consistently”

The examples use --fail-with-body so HTTP errors stop the command while preserving the error body. Some counts and point values are JSON strings; convert them with tonumber only when present. A missing metric series means no data for that selector and window. Service graph points can arrive several minutes after requests; the measured graph comparison returned a new five-minute bucket about six minutes after the request sequence. Allow up to ten minutes before investigating a missing new sample. Logs and discovery can have different delays.

Keep set -o pipefail enabled so a failed cURL request cannot be hidden by a successful jq filter. Published examples are measured summaries: identifiers become <XCSH_...> placeholders, and credentials, client addresses, headers, raw logs, and captured request/response bodies are omitted. JSON code blocks show measured values, including string-valued numbers and the API’s own units. Keep private receipts outside Git with owner-only permissions. Record the UTC capture time, HTTP status, request selector, original response, and summary. Output order is sorted where useful for comparison.

A rate in requests per second is a sampled metric, not an exact request count. Do not sum rate samples to count requests. Use paginated access logs for complete logged-request totals, and keep API activity totals scoped to their endpoint population. Missing series are unavailable telemetry, while a returned point with value "0" is a measured zero. HTTP 200 proves that the query succeeded; it does not prove that data is populated.