Querying and Exporting Datasets

There are several ways to interact with the data stored in VictoriaMetrics, from building dashboards in Grafana to running ad-hoc queries and exporting datasets for analysis.

These dashboards are fully configured and populated with data from your VictoriaMetrics instance, making them ideal for quick demonstrations and immediate operational insights.

MetricsQL

VictoriaMetrics uses MetricsQL, a powerful and flexible query language that extends PromQL. MetricsQL allows you to filter metrics by labels, aggregate data, perform calculations, and more.

For example, to count all Pods that have entered the Failed phase, you could use the following query:

count(kube_pod_status_phase{job="kube-state-metrics",phase="Failed"})

Here, kube_pod_status_phase is the metric name, job and phase are labels, and count() is a MetricsQL function. Labels are fundamental for refining your queries, allowing you to broaden or narrow the scope of your data retrieval. To illustrate this, consider the example above:

• Narrowing a Query: Adding more label matchers makes your query more specific. For instance, if you start with kube_pod_status_phase{job="kube-state-metrics"} (showing all pod statuses for that job), adding phase="Failed" narrows the results to only those pods in the "Failed" state.
• Broadening a Query: Removing label matchers makes your query less specific. Removing phase="Failed" would broaden the results to include pods in all phases.

You can also use various operators for precise control, such as Negative Exact Match (!=), Regex Match (=~) or Negative Regex Match (!~):

caution

The specific labels and their values that are available for a given metric often vary depending on the data source, which is identified by the job label. To discover the precise labels you can use, always refer to the specific data source's documentation or interactively explore the metrics and their labels within Grafana.

For a complete guide on syntax and functions, please visit the official MetricsQL documentation.

Querying via the HTTP API

VictoriaMetrics provides an HTTP API that allows you to run queries and export data programmatically using MetricsQL. This is useful for integrating with custom tools or applications.

The main endpoint for running queries is /api/v1/query.

1. Forward the port: First, you will need to forward the vmsingle service port from your Kubernetes cluster to your local machine.

   kubectl port-forward -n monitoring services/vmsingle-vmks-victoria-metrics-k8s-stack 8428:8428

   tip

   To expose the database to other devices on your network, add the --address 0.0.0.0 flag. Other machines can then connect using http://<control-plane-ip>:8428.

2. Run queries with curl: You can now send GET requests to http://localhost:8428/api/v1/query.

   Example 1: Instant Query This query gets the most recent value of the available memory for all the nodes in cluster.

   curl -G http://localhost:8428/api/v1/query \
     --data-urlencode 'query=node_memory_MemAvailable_bytes{job="node-exporter"}'

   Example 2: Range Query To retrieve data over a time period, use the /api/v1/query_range endpoint with start, end, and step parameters. This example retrieves for a scenario the downlink throughput values for all the UEs attached to a single gNB over one hour with a one-minute resolution.

   curl -G http://localhost:8428/api/v1/query_range \
     --data-urlencode 'query=kpm_drb_ue_thp_dl{job="raw_ran", sm="kpm", scenario="dataset", e2node_id="50"}' \
     --data-urlencode 'start=2026-01-01T00:00:00Z' \
     --data-urlencode 'end=2026-01-01T01:00:00Z' \
     --data-urlencode 'step=1m'

   tip

   In RAN metric queries like kpm_drb_ue_thp_dl{...}, specific labels such as e2node_id and ran_ue_id are essential for narrowing down the query surface.

   • Narrowing: Adding ran_ue_id="<ran_ue_id>" will focus the query on a specific User Equipment (UE).
   • Broadening: Removing e2node_id="<e2node_id>" would broaden the query to include data from all gNBs for the specified scenario and service model.

For more advanced exporting and back-filling scenarios, refer to the official VictoriaMetrics API documentation.

Dataset Export with brc

While you can use the HTTP API for direct queries, the simplest way to export a full dataset for analysis is by using the brc extract dataset command. This tool acts as a powerful wrapper around the VictoriaMetrics export endpoint to export time-series data from a RAN deployment into a structured CSV file, ready for use in external tools and AI/ML applications.

The command's core logic revolves around the scenario label, which it uses to group and export all metrics associated with a specific test run or xApp deployment (see xApps Generated Metrics). You can easily discover the available scenario names stored into the database either via command autocompletion or by running brc get scenarios.

Basic Usage

To export all data tagged with a specific scenario, simply provide the scenario name as an argument.

brc extract dataset <your-scenario-name>

This will connect to the default VictoriaMetrics instance, find all metrics with the label scenario="<your-scenario-name>", and export them into a file named dataset_<your-scenario-name>.csv in your current directory.

Common Export Options

You can customize the export using several flags:

• Time Range (--start and --end): By default, the export covers the last 7 days. You can specify a different time window using RFC3339 timestamps (e.g., 2026-01-30T14:00:00Z) or relative durations (e.g., 1h, 30m).
• Time Precision (--time.precision): This crucial parameter determines the time resolution of the exported data by grouping metrics into time buckets. The default is 500ms, which also reflects the default xApp collection interval.
• Output File (--output.file): To specify a custom name for the output CSV file.

As an example, the following command exports data for the rfsim_high_traffic scenario from a specific one-hour window and saves it to a custom file named traffic-analysis.csv.

brc extract dataset rfsim_high_traffic \
  --start "1h"
  --output.file "traffic-analysis.csv"

For a complete list of all available flags, including those for performance tuning and custom VictoriaMetrics connections, run brc extract dataset --help.