Use PromQL

In practice, this means that PromQL queries written for a standard Prometheus environment are expected to work in Sysdig Monitor without modification, subject to the same PromQL versions and features covered by our compliance testing. On top of this, Sysdig Monitor automatically enriches your metrics with Kubernetes and infrastructure context through the Extended Label Set. For most use cases, labels like cluster, namespace, pod, and deployment are already present on your metrics, so you can filter and aggregate directly without writing joins. Before writing any query, it is worth reading the Extended Label Set page to understand which labels are available and how they affect query structure.

PromQL queries in Sysdig Monitor can be used in Dashboards, Alerts, and via the Prometheus Public API.

Learn PromQL

If you are new to PromQL or want to deepen your knowledge, the following resources are a good starting point:

• Prometheus Query Basics
• Prometheus Monitoring Guide

To explore and build queries in Sysdig Monitor specifically:

• PromQL Query Explorer
• PromQL Library — Curated query library with sample dashboards
• Prometheus Alerts

Vector Matching for Advanced Label Enrichment

The Extended Label Set covers the vast majority of Kubernetes and infrastructure label needs. For cases it does not cover, you can enrich metrics manually using vector matching.

Vector matching works similarly to an SQL join: it lets you attach labels from one metric onto another by matching on a shared label.

Info Metrics

Info metrics are a Prometheus convention for exposing metadata that is not naturally attached to your application metrics. They always carry a value of 1 and hold context such as Kubernetes object properties or cloud provider details as labels. On their own, info metrics are not particularly useful — their value comes from joining their labels onto other metrics, allowing you to correlate a metric’s value with infrastructure, application, or deployment context that would otherwise be unavailable on that metric. Because their value is always 1, multiplying an info metric against a target metric grafts its labels onto the result without changing the underlying value.

Info metrics in Sysdig are typically generated by kube-state-metrics or by Sysdig’s own ingestion pipeline, not by the application being monitored. See Mapping Between Classic Metrics and PromQL Metrics for a list of available info metrics.

Vector matching with info metrics is still needed in the following common cases:

• Enriching metrics with cloud provider labels such as AWS account ID and region
• Joining custom application metrics with infrastructure metadata not in the extended set
• Traversing non-standard Kubernetes ownership chains

Example 1: Average CPU Used Percent in AWS Hosts

Cloud provider labels such as account_id and region are not part of the Kubernetes metadata provided by the Extended Label Set, making this a case where vector matching is still required. The following query calculates average CPU used percent per AWS account and region, filtered by dashboard scope variables:

avg by (region, account_id) (
    sysdig_host_cpu_used_percent
  * on(host_mac) group_left(region, account_id)
    sysdig_cloud_provider_info{account_id=~$AWS_account, region=~$AWS_region}
)

The query performs the following operations:

• Filters sysdig_cloud_provider_info based on the account_id and region labels from the dashboard scope variables.
• Matches sysdig_host_cpu_used_percent with sysdig_cloud_provider_info on host_mac, carrying over region and account_id labels to the result.
• Calculates the average of the resulting metrics grouped by account_id and region.

Example 2: Vector Matching vs. Extended Label Set

To illustrate the difference in query complexity, consider calculating total CPU usage per deployment. Without the Extended Label Set, this requires chaining two vector matches — first joining container metrics to pod metadata, then joining pod metadata to ownership information:

sum by (cluster, namespace, owner_name) (
    sysdig_container_cpu_cores_used
  * on(container_id) group_left(pod, namespace, cluster)
      kube_pod_container_info
  * on(pod, namespace, cluster) group_left(owner_name)
    kube_pod_owner{
      owner_kind="Deployment",
      owner_name=~$deployment,
      cluster=~$cluster,
      namespace=~$namespace
    }
)

With the Extended Label Set, the same result is expressed as:

sum by (kube_cluster_name, kube_namespace_name, kube_deployment_name) (
  sysdig_container_cpu_cores_used{
    kube_cluster_name=~$cluster,
    kube_namespace_name=~$namespace,
    kube_deployment_name=~$deployment
  }
)

The Extended Label Set version is not only shorter — it is also easier to reason about. Filtering on infrastructure labels becomes a straightforward label selector on the metric itself, rather than a condition buried inside a chain of joins.

For more before-and-after examples like this, see Extended Label Set.

Range Interval Behavior

In Prometheus 2, range selectors such as [10s] were inclusive on both sides, effectively capturing 11 seconds of data. Prometheus 3 changed this so the left side is exclusive. Sysdig Monitor intentionally preserves the Prometheus 2 behavior by default. This decision was driven by customer feedback — switching to the new behavior would silently break a large number of existing alerts and dashboards that were written against Prometheus 2 semantics. If you need Prometheus 3 range behavior for consistency with a self-hosted environment, this can be changed on request.

Formatting

Sysdig Monitor supports percentages only as 0-100 values. In calculated ratios, you can skip multiplying the whole query times 100 by selecting percentage as a 0-1 value.