LogoLogo
StackState.comDownloadSupportExplore playground
SUSE Observability
SUSE Observability
  • SUSE Observability docs!
  • Docs for all SUSE Observability products
  • 🚀Get started
    • Quick start guide
    • SUSE Observability walk-through
    • SUSE Rancher Prime
      • Air-gapped
      • Agent Air-gapped
    • SUSE Cloud Observability
  • 🦮Guided troubleshooting
    • What is guided troubleshooting?
    • YAML Configuration
    • Changes
    • Logs
  • 🚨Monitors and alerts
    • Monitors
    • Out of the box monitors for Kubernetes
    • Notifications
      • Configure notifications
      • Notification channels
        • Slack
        • Teams
        • Webhook
        • Opsgenie
      • Troubleshooting
    • Customize
      • Add a monitor using the CLI
      • Derived State monitor
      • Override monitor arguments
      • Write a remediation guide
  • 📈Metrics
    • Explore Metrics
    • Custom charts
      • Adding custom charts to components
      • Writing PromQL queries for representative charts
      • Troubleshooting custom charts
    • Advanced Metrics
      • Grafana Datasource
      • Prometheus remote_write
      • OpenMetrics
  • 📑Logs
    • Explore Logs
    • Log Shipping
  • 🔭Traces
    • Explore Traces
  • 📖Health
    • Health synchronization
    • Send health data over HTTP
      • Send health data
      • Repeat Snapshots JSON
      • Transactional Increments JSON
    • Debug health synchronization
  • 🔍Views
    • Kubernetes views
    • Custom views
    • Component views
    • Explore views
    • View structure
      • Overview perspective
      • Highlights perspective
      • Topology perspective
      • Events perspective
      • Metrics perspective
      • Traces perspective
      • Filters
      • Keyboard shortcuts
    • Timeline and time travel
  • 🕵️Agent
    • Network configuration
      • Proxy Configuration
    • Using a custom registry
    • Custom Secret Management
      • Custom Secret Management (Deprecated)
    • Request tracing
      • Certificates for sidecar injection
  • 🔭Open Telemetry
    • Overview
    • Getting started
      • Concepts
      • Kubernetes
      • Kubernetes Operator
      • Linux
      • AWS Lambda
    • Open telemetry collector
      • Sampling
      • SUSE Observability OTLP APIs
    • Instrumentation
      • Java
      • Node.js
        • Auto-instrumentation of Lambdas
      • .NET
      • SDK Exporter configuration
    • Troubleshooting
  • CLI
    • SUSE Observability CLI
  • 🚀Self-hosted setup
    • Install SUSE Observability
      • Requirements
      • Kubernetes / OpenShift
        • Kubernetes install
        • OpenShift install
        • Alibaba Cloud ACK install
        • Required Permissions
        • Override default configuration
        • Configure storage
        • Exposing SUSE Observability outside of the cluster
      • Initial run guide
      • Troubleshooting
        • Advanced Troubleshooting
        • Support Package (Logs)
    • Configure SUSE Observability
      • Slack notifications
      • E-mail notifications
      • Stackpacks
      • Advanced
        • Analytics
    • Release Notes
      • v2.0.0 - 11/Sep/2024
      • v2.0.1 - 18/Sep/2024
      • v2.0.2 - 01/Oct/2024
      • v2.1.0 - 29/Oct/2024
      • v2.2.0 - 09/Dec/2024
      • v2.2.1 - 10/Dec/2024
      • v2.3.0 - 30/Jan/2025
      • v2.3.1 - 17/Mar/2025
      • v2.3.2 - 22/Apr/2025
      • v2.3.3 - 07/May/2025
    • Upgrade SUSE Observability
      • Migration from StackState
      • Steps to upgrade
      • Version-specific upgrade instructions
    • Uninstall SUSE Observability
    • Air-gapped
      • SUSE Observability air-gapped
      • SUSE Observability Kubernetes Agent air-gapped
    • Data management
      • Backup and Restore
        • Kubernetes backup
        • Configuration backup
      • Data retention
      • Clear stored data
    • Security
      • Authentication
        • Authentication options
        • Single password
        • File-based
        • LDAP
        • Open ID Connect (OIDC)
          • Microsoft Entra ID
        • KeyCloak
        • Service tokens
        • Troubleshooting
      • RBAC
        • Role-based Access Control
        • Permissions
        • Roles
        • Scopes
      • Self-signed certificates
      • External secrets
  • 🔐Security
    • Service Tokens
    • API Keys
  • ☁️SaaS
    • User Management
  • Reference
    • SUSE Observability Query Language (STQL)
    • Chart units
    • Topology Identifiers
Powered by GitBook
LogoLogo

Legal notices

  • Privacy
  • Cookies
  • Responsible disclosure
  • SOC 2/SOC 3
On this page
  • Overview
  • Component filters
  • Filters
  • Operators
  • Wildcard
  • Examples
  • Functions
  • withNeighborsOf
  • Compatibility basic and advanced filters
  • Basic to advanced filtering
  • Advanced to basic filtering
  • See also
  1. Reference

SUSE Observability Query Language (STQL)

SUSE Observability

PreviousUser ManagementNextChart units

Last updated 7 months ago

Overview

This page describes how to use the built-in SUSE Observability Query Language (STQL) to write advanced topology component filters. STQL queries are used in SUSE Observability to write .

An STQL query consists of and . The query output is a component, or set of components, filtered from the complete topology.

Component filters

Component filters are used in two ways in STQL:

  • Define the set of components to be included in the query output.

  • Specify the set of components to be handled by an in-built STQL function.

Filters

The filters described below can be combined using the available to achieve complex selections of components.

Filter
Default
Description

healthstate

"all"

Components with the named health state.

label

"all"

Components with the named labels.

name

"all"

Components with the specified name.

type

"all"

Components of the specified type.

identifier

"all"

layer

"all"

Components in the named layer.

domain

"all"

Components in the specified domain(s).

environment

"all"

Components in the named environment.

Operators

The operators described below are available to use in STQL queries. Note that boolean operators will be executed in the standard order: NOT, OR, AND.

Operator
Description
Example

=

Equality matching

name = "cert-manager"

!=

Inequality matching

name != "coredns"

IN

Value is in subset

name in ("cert-manager", "cluster_autoscaler")

NOT

Negation

name NOT in ("cert-manager", "cluster_autoscaler")

AND and OR

Filter based on more than one condition or sub-query

name = "cert-manager" OR type = "deployment"

()

Use parenthesis to group results

(name = … AND type = …) OR (…)

For example:

# Return all components named cert-manager or coredns regardless of type:
  name = "cert-manager" OR name = "coredns"

# Return only deployments named coredns and configmaps named kube-root-ca.crt:
  (name = "coredns" AND type = "deployment") OR (name = "kube-root-ca.crt" AND type = "configmap")

Wildcard

You can use * as a full wildcard in a component filter. It isn't possible to filter for partial matches using a wildcard character.

Examples

# Select all components
name = "*"

# Select all components with name "etcd-manager"
name = "etcd-manager"

# Select all components in the "Containers" layer:
layer = "Containers"

# Select all components named either "etcd-manager" or "coredns" that don't have a label "cluster-name:prod.stackstate.io"
name IN ("etcd-manager","coredns") NOT label = "cluster-name:prod.stackstate.io"

# Select all components named "coredns" that don't have a label "bck" or "test"
name = "cert-manager" NOT label in ("image_name:cert-manager/cert-manager-controller:testA", "image_name:cert-manager/cert-manager-controller:testB")

Functions

withNeighborsOf

The function withNeighborsOf extends STQL query output, adding connected components in the specified direction(s). The number of topology levels included can be adjusted up to a maximum of 15.

withNeighborsOf(components=(), levels=, direction=)

Parameters / fields

Parameter
Default
Allowed values
Description

components

"all"

A component filter

levels

1

"all", [1:14]

The number of levels to include in the output. Use "all" to display all available levels (maximum 15)

direction

"both"

"up", "down", "both"

up: only components that depend on the named component(s) will be added down: only dependencies of the named component(s) will be added both: components that depend on and dependencies of the named component(s) will be added.

Example

The example below will return all components in the application layer that have a health state of either DEVIATING or CRITICAL. Components with names "appA" or "appB" and their neighbors will also be included.

layer = "Containers"
  AND (healthstate = "CRITICAL" OR healthstate = "DEVIATING")
  OR withNeighborsOf(components = (name in ("cert-manager","coredns")))

Compatibility basic and advanced filters

Basic to advanced filtering

You can switch from basic to advanced filtering by selecting Advanced under Filter Topology in the View Filters panel.

It's always possible to switch from basic to advanced filtering. The selected basic filters will be converted directly to an STQL query.

Advanced to basic filtering

You can switch from advanced to basic filtering by selecting Basic under Filter Topology in the View Filters panel.

It isn't always possible to switch from advanced filtering to basic filtering. Mpst simple queries can be converted to basic filters, however, some advanced queries aren't compatible with basic filters.

  • Basic filters can't contain an inequality.

  • Basic filters don't use =, they're always formatted using the IN operator. For example name IN ("cert-manager”) and not name = "cert-manager”.

  • Basic filters use AND/OR in a specific way:

    • All items in each basic filter box are joined with an OR: layer IN ("Containers", "Services", "Storage")

    • The different basic filter boxes are chained together with an AND: layer IN ("Containers") AND domain IN ("cluster.test.stackstate.io”)

    • The Include components basic filter box (name) is the exception - this is chained to the other filter boxes with an OR: layer IN ("Containers") AND domain IN ("cluster.test.stackstate.io") OR name IN ("cert-manager”)

    • To be compatible with basic filtering, the withNeighborsOf function and identifier filter must be joined to other filters with an OR: layer in ("Containers") OR identifier IN ("urn:kubernetes:/cluster.test.stackstate.io:kube-system:pod/cert-manager-7749f44bb4-vspjj:container/cert-manager")

If you try to switch from an advanced filter to a basic filter and the query isn't compatible, SUSE Observability will ask for confirmation before removing the incompatible filters. To keep the filters, you can choose to stay in advanced filtering.

See also

Components with the specified URN identifier. The identifier filter is only compatible with basic filtering when it's specified using identifier IN (...) and combined with other filters using an OR operator. When the set filter is compatible with basic filtering, the number of component identifiers queried will be reported in the .

To be compatible with basic filtering, the function can only be combined with other filters using an OR operator. When an advanced filter includes a function withNeighborsOf that's compatible with basic filtering, the number of components whose neighbors are queried for is shown in the .

The component(s) for which the neighbors will be returned, see .

How to filter topology in the SUSE Observability UI
component filters
component filters
functions
operators
advanced topology filters
Other filters box
Basic topology filters
Topology filter limits
Other filters box