Prometheus Query Workshop

This workshop is designed to help you become proficient with Prometheus Query Language (PromQL). You will learn how to write effective queries to extract meaningful insights from your metrics data, from basic selectors to advanced aggregation patterns.

Shared CLI tools image (OpenShift 102 showroom)

If you prefer not to install oc, kubectl, helm, istioctl, and related tools on your laptop, run the workshop CLI tools image on the cluster. You do not need a local oc client: apply the manifest from the web console (see below). An interactive bash session prints a short list of bundled tools when the shell starts (for example after opening Terminal on the pod and running bash or bash -l if the default shell is sh).

The image build copies the showroom Helm chart into ~/chart so you can run helm upgrade --install from the pod without cloning the git repository; use --set tools.enabled=false when installing from this pod so the chart does not start a second tools Deployment.

Default image (change the tag to match your deployed showroom chart or offline bundle):

ghcr.io/shpwrck/openshift-102-tools:latest

To apply the workload without a local oc client:

  1. In the OpenShift console, select your Project.

  2. Click + in the top bar, then Import YAML.

  3. Paste the manifest below, adjust the image: line if you mirror images, then click Create.

  4. Go to Workloads → Deployments → openshift-102-workshop-tools, open the Pods tab, select the running pod, then Terminal (or Actions → Debug pod). Run bash or bash -l if you need the interactive bash banner.

The same manifest lives in the repository as deploy/openshift-102-tools-deployment.yaml and is shipped in the offline release tarball.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: openshift-102-workshop-tools
  labels:
    app.kubernetes.io/name: openshift-102-workshop-tools
    app.kubernetes.io/part-of: openshift-102-workshop
spec:
  replicas: 1
  revisionHistoryLimit: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: openshift-102-workshop-tools
  template:
    metadata:
      labels:
        app.kubernetes.io/name: openshift-102-workshop-tools
    spec:
      containers:
        - name: tools
          image: "ghcr.io/shpwrck/openshift-102-tools:latest"
          imagePullPolicy: IfNotPresent
          resources:
            requests:
              cpu: 50m
              memory: 128Mi
            limits:
              cpu: "1"
              memory: 512Mi

The container image CMD keeps the process alive (sleep via the image entrypoint) so the pod stays running until you delete the Deployment. The image includes a small docker CLI shim for Helm OCI exercises (no Docker Engine); manifest operations use skopeo under the hood. For disconnected clusters, mirror the tools image and UBI base listed in the release tarball TOOLS.md and images-mirror.txt.

Workshop Structure

This workshop consists of four modules:

  • Module 1: Prometheus Query Language Fundamentals - Learn the basics of PromQL, including metric names, labels, data types, and basic query syntax

  • Module 2: Selectors and Filtering - Master label selectors, regular expressions, and filtering techniques (includes exercises)

  • Module 3: Aggregation Functions - Understand how to use aggregation functions like sum, average, quantiles, and top-k (includes exercises)

  • Module 4: Advanced Query Patterns - Explore rate functions, subqueries, logical operators, and optimization techniques (includes exercises)

Prerequisites

This workshop assumes the following:

  • Basic understanding of Prometheus concepts (metrics, labels, time series)

  • Access to an OpenShift 4.16 cluster with Prometheus installed

  • Ability to access the Prometheus web UI or use the Prometheus API

  • Familiarity with basic command-line operations

If you are new to Prometheus, we recommend reviewing the Prometheus documentation before proceeding.

Expectations

After completing this workshop, you will be able to:

  • Write basic PromQL queries using selectors and filters

  • Apply aggregation functions to summarize metrics across multiple time series

  • Construct advanced queries using rate functions, subqueries, and logical operators

  • Debug and optimize Prometheus queries for better performance

  • Use PromQL effectively in Grafana dashboards and alerting rules