Service Instance Metrics in Kestra – Expose via the Webserver

Configure which service instance metrics the webserver collects and re-exposes through its monitoring endpoint.

Service instance metrics – expose via the webserver

By default, each Kestra service (Worker, Executor, Scheduler, and so on) publishes its own metrics on its own management port. In deployments where only the webserver is reachable from the outside — for example, behind an ingress or a load balancer — metrics from other service instances are not directly accessible.

The kestra.metrics.sharedServiceInstanceMetrics configuration lets you define a set of metrics per service type that the webserver will collect from all running instances and re-expose on its own monitoring endpoint. This gives any compatible monitoring consumer a single scrape target for the metrics you choose.

How it works

The webserver runs a background task that polls the service instance repository every 30 seconds. For each running service instance whose type is listed in sharedServiceInstanceMetrics, it collects the configured metrics, sums the values across all instances of that type, and registers the results as Micrometer gauges. The webserver itself is excluded from this aggregation.

Metric tags are preserved, so you can still filter by dimensions such as worker_group.

When a service instance is no longer active, its contribution is set to zero at the next poll cycle.

How to configure sharedServiceInstanceMetrics

Set kestra.metrics.sharedServiceInstanceMetrics in your configuration file. The value is a map where each key is a service type and each value is a list of fully-qualified metric names to collect from instances of that type. Kestra ships with the following defaults:

kestra:
  metrics:
    prefix: kestra
    sharedServiceInstanceMetrics:
      WORKER:
        - kestra.worker.job.pending
        - kestra.worker.job.thread
        - kestra.worker.job.running

You can extend or replace these entries to expose any metric listed in the Alerting and Monitoring reference.

Configuration properties

Next steps

• Prometheus Metrics — scrape Kestra metrics using Prometheus
• OpenTelemetry — export Kestra metrics using OpenTelemetry
• Alerting and Monitoring — full metrics reference for each service component
• Observability and Networking Configuration — configure the metrics prefix, tags, and label-based metrics
• Server Components — understand the role of each Kestra service