Querying metrics | Monitoring

About querying metrics
Next steps

You can query metrics to view data about how cluster components and your own workloads are performing.

About querying metrics

The OKD monitoring dashboard enables you to run Prometheus Query Language (PromQL) queries to examine metrics visualized on a plot. This functionality provides information about the state of a cluster and any user-defined workloads that you are monitoring.

As a cluster administrator, you can query metrics for all core OKD and user-defined projects.

As a developer, you must specify a project name when querying metrics. You must have the required privileges to view metrics for the selected project.

Querying metrics for all projects as a cluster administrator

As a cluster administrator or as a user with view permissions for all projects, you can access metrics for all default OKD and user-defined projects in the Metrics UI.

Prerequisites

You have access to the cluster as a user with the cluster-admin cluster role or with view permissions for all projects.
You have installed the OpenShift CLI (oc).

Procedure

Select the Administrator perspective in the OKD web console.
Select Observe → Metrics.
Select Insert Metric at Cursor to view a list of predefined queries.

To create a custom query, add your Prometheus Query Language (PromQL) query to the Expression field.

As you type a PromQL expression, autocomplete suggestions appear in a drop-down list. These suggestions include functions, metrics, labels, and time tokens. You can use the keyboard arrows to select one of these suggested items and then press Enter to add the item to your expression. You can also move your mouse pointer over a suggested item to view a brief description of that item.

To add multiple queries, select Add Query.
To duplicate an existing query, select next to the query, then choose Duplicate query.
To delete a query, select next to the query, then choose Delete query.
To disable a query from being run, select next to the query and choose Disable query.

To run queries that you created, select Run Queries. The metrics from the queries are visualized on the plot. If a query is invalid, the UI shows an error message.

Queries that operate on large amounts of data might time out or overload the browser when drawing time series graphs. To avoid this, select Hide graph and calibrate your query using only the metrics table. Then, after finding a feasible query, enable the plot to draw the graphs.

Optional: The page URL now contains the queries you ran. To use this set of queries again in the future, save this URL.

Additional resources

For more information about creating PromQL queries, see the Prometheus query documentation.

Querying metrics for user-defined projects as a developer

You can access metrics for a user-defined project as a developer or as a user with view permissions for the project.

In the Developer perspective, the Metrics UI includes some predefined CPU, memory, bandwidth, and network packet queries for the selected project. You can also run custom Prometheus Query Language (PromQL) queries for CPU, memory, bandwidth, network packet and application metrics for the project.

Developers can only use the Developer perspective and not the Administrator perspective. As a developer, you can only query metrics for one project at a time in the Observe -→ Metrics page in the web console for your user-defined project.

Prerequisites

You have access to the cluster as a developer or as a user with view permissions for the project that you are viewing metrics for.
You have enabled monitoring for user-defined projects.
You have deployed a service in a user-defined project.
You have created a ServiceMonitor custom resource definition (CRD) for the service to define how the service is monitored.

Procedure

Select the Developer perspective in the OKD web console.
Select Observe → Metrics.
Select the project that you want to view metrics for in the Project: list.
Select a query from the Select query list, or create a custom PromQL query based on the selected query by selecting Show PromQL.
Optional: Select Custom query from the Select query list to enter a new query. As you type, autocomplete suggestions appear in a drop-down list. These suggestions include functions and metrics. Click a suggested item to select it.

In the Developer perspective, you can only run one query at a time.

Additional resources

For more information about creating PromQL queries, see the Prometheus query documentation.

Exploring the visualized metrics

After running the queries, the metrics are displayed on an interactive plot. The X-axis in the plot represents time and the Y-axis represents metrics values. Each metric is shown as a colored line on the graph. You can manipulate the plot interactively and explore the metrics.

Procedure

In the Administrator perspective:

Initially, all metrics from all enabled queries are shown on the plot. You can select which metrics are shown.

By default, the query table shows an expanded view that lists every metric and its current value. You can select ˅ to minimize the expanded view for a query.
- To hide all metrics from a query, click for the query and click Hide all series.
- To hide a specific metric, go to the query table and click the colored square near the metric name.
To zoom into the plot and change the time range, do one of the following:
- Visually select the time range by clicking and dragging on the plot horizontally.
- Use the menu in the left upper corner to select the time range.
To reset the time range, select Reset Zoom.
To display outputs for all queries at a specific point in time, hold the mouse cursor on the plot at that point. The query outputs will appear in a pop-up box.
To hide the plot, select Hide Graph.

In the Developer perspective:

To zoom into the plot and change the time range, do one of the following:
- Visually select the time range by clicking and dragging on the plot horizontally.
- Use the menu in the left upper corner to select the time range.
To reset the time range, select Reset Zoom.
To display outputs for all queries at a specific point in time, hold the mouse cursor on the plot at that point. The query outputs will appear in a pop-up box.

Additional resources

See Querying metrics for details on using the PromQL interface
See Querying metrics for all projects as an administrator for details on accessing metrics for all projects as an administrator.
See Querying metrics for user-defined projects as a developer for details on accessing non-cluster metrics as a developer or a privileged user.

Next steps

Managing metrics targets