This is documentation for the next version of Pyroscope. For the latest stable release, go to the latest version.

Open source

Pyroscope query-scheduler

The query-scheduler is a stateless component that retains a queue of queries to execute, and distributes the workload to available queriers.

The query-scheduler is a required component when using the query-frontend.

Query-scheduler architecture

The following flow describes how a query moves through a Pyroscope cluster:

  1. The query-frontend receives queries, and then either splits and shards them, or serves them from the cache.
  2. The query-frontend enqueues the queries into a query-scheduler.
  3. The query-scheduler stores the queries in an in-memory queue where they wait for a querier to pick them up.
  4. Queriers pick up the queries, and executes them.
  5. The querier sends results back to query-frontend, which then forwards the results to the client.

Benefits of using the query-scheduler

Query-scheduler enables the scaling of query-frontends. To learn more, see Mimir Query Frontend documentation.


To use the query-scheduler, query-frontends and queriers need to discover the addresses of query-scheduler instances. To advertise itself, the query-scheduler uses Ring-based service discovery which is configured via the memberlist configuration.

Operational considerations

For high-availability, run two query-scheduler replicas.