jitsi.help
Talk to an engineer

How do I monitor Jitsi Meet with Prometheus and Grafana?

Updated View as Markdown

Short answer

Scrape JVB and Jicofo /metrics with Prometheus and graph them in Grafana. Enable Jicofo access and health checks separately; add exporters for CPU and HTTPS monitoring. Docker stable-11248 supplies Loki logs and distributed tracing through Alloy and Tempo. [S1][S2][S4][S17][S21][S23]

Who this is for

For operators diagnosing service failures and poor media quality. stable-11248, released 2026-09-14, remains the latest Docker release checked on 2026-10-06. [S1]

How it works

Prometheus scrapes metrics; Grafana graphs them. Node Exporter measures host resources; Blackbox probes HTTPS. The handbook log analyser sends Docker logs through OpenTelemetry to Loki. Tracing uses Alloy and Tempo. [S13][S15][S17][S21][S23]

Component Private endpoint Successful response and purpose
JVB :8080/about/health HTTP 200, empty body; bridge health
JVB :8080/metrics HTTP 200, native metrics
JVB :8080/colibri/stats HTTP 200, legacy JSON when enabled
Jicofo :8888/about/health HTTP 200, literal OK when health checks are enabled
Jicofo :8888/metrics HTTP 200, native metrics
Jicofo :8888/stats HTTP 200, JSON conference statistics

Jicofo’s older health documentation differs from current source. JVB health and metrics need no COLIBRI. Health failures normally return 500 or 503. [S3][S5][S6][S7][S49]

JVB checks address requirements and UDP binding, not XMPP. Jicofo checks bridge availability, a synthetic conference and XMPP. Neither proves working browser media. [S34][S35]

Before you start

  • Keep Jitsi images and Compose files on stable-11248. Use an existing HTTPS site at meet.example.com. [S1][S2]
  • Use Docker Compose 2.24.4 or newer for !override. Keep monitoring private: the Jitsi REST ports also expose administrative controls. Restrict host port 9100 to monitoring traffic. [S3][S5][S20][S21]
  • Logs require a rootful Linux Docker daemon with standard paths. Rootless Docker daemons need adapted mounts, even though rootless Jitsi images work with this recipe. Back up existing monitoring data. [S14][S15][S27][S31]

Steps

  1. Docker stable-11248: enable checks in .env. The REST flag binds Jicofo inside its container; host publications stay loopback. COLIBRI is optional for legacy JSON. [S2][S4][S47]

    Config
    JICOFO_ENABLE_REST=1
JICOFO_ENABLE_HEALTH_CHECKS=1
COLIBRI_REST_ENABLED=1
PROSODY_ENABLE_METRICS=1

  2. Docker stable-11248: create compose.override.yaml. It pins Prometheus, adds exporters and restricts monitoring ports. Host-networked Node Exporter still needs firewall protection for 9100. [S12][S14][S16][S20][S21][S23][S41][S43]

    YAML
    services:
  web:
    logging: &jitsi-logging
      driver: json-file
      options: {labels: service}
  prosody:
    logging: *jitsi-logging
  jicofo:
    logging: *jitsi-logging
  jvb:
    logging: *jitsi-logging
  prometheus:
    image: prom/prometheus:v3.15.0
    ports: !override ["127.0.0.1:9090:9090"]
    extra_hosts: ["host.docker.internal:host-gateway"]
    volumes:
      - prometheus-data:/prometheus
  grafana:
    ports: !override ["127.0.0.1:3000:3000"]
  loki:
    ports: !reset []
  node_exporter:
    image: quay.io/prometheus/node-exporter:v1.12.1
    network_mode: host
    pid: host
    command: ["--path.rootfs=/host"]
    volumes: ["/:/host:ro,rslave"]
    restart: unless-stopped
  blackbox:
    image: prom/blackbox-exporter:v0.28.0
    command: ["--config.file=/config/blackbox.yml"]
    volumes: ["./prometheus/blackbox.yml:/config/blackbox.yml:ro"]
    networks: [meet.jitsi]
    restart: unless-stopped
volumes:
  prometheus-data:

    Logging labels identify Docker records. [S2][S15][S40]

  3. Docker stable-11248: replace prometheus/prometheus.yml. Rule and Blackbox filenames are example choices. [S24][S41]

    YAML
    global:
  scrape_interval: 15s
  evaluation_interval: 15s
rule_files: [/etc/prometheus/jitsi.rules.yml]
scrape_configs:
  - job_name: jvb
    static_configs: [{targets: ["jvb:8080"]}]
  - job_name: jicofo
    static_configs: [{targets: ["jicofo:8888"]}]
  - job_name: node
    static_configs: [{targets: ["host.docker.internal:9100"]}]
  - job_name: otel
    static_configs: [{targets: ["otel:9464"]}]
  - job_name: prosody
    static_configs: [{targets: ["prosody:5280"]}]
  - job_name: webprobe
    metrics_path: /probe
    params: {module: [https_2xx]}
    static_configs: [{targets: ["https://meet.example.com/"]}]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox:9115

    Create prometheus/blackbox.yml: [S23][S42]

    YAML
    modules:
  https_2xx:
    prober: http
    timeout: 5s
    http:
      fail_if_not_ssl: true
      tls_config: {insecure_skip_verify: false}

    Create prometheus/jitsi.rules.yml. Thresholds are examples. Configure Alertmanager or Grafana notification routing separately. [S25]

    YAML
    groups:
  - name: jitsi
    rules:
      - alert: JitsiMetricsTargetDown
        expr: up{job=~"jvb|jicofo|node|webprobe"} == 0
        for: 2m
      - alert: JitsiComponentUnhealthy
        expr: jitsi_jvb_healthy == 0 or jitsi_jicofo_healthy == 0
        for: 2m
      - alert: JicofoNoOperationalBridge
        expr: jitsi_jicofo_bridge_selector_bridge_count_operational == 0
        for: 2m
      - alert: JitsiHttpsProbeFailed
        expr: probe_success{job="webprobe"} == 0
        for: 2m
      - alert: JitsiCertificateExpiring
        expr: probe_ssl_earliest_cert_expiry{job="webprobe"} - time() < 14 * 86400
        for: 10m

    Operational counts include graceful shutdown. Failed TLS can leave certificate metrics absent, hence the probe alert. [S10][S23][S35]

  4. Docker stable-11248: prepare logs and optional tracing. For a fresh Loki installation, change three paths in log-analyser/loki/conf/loki-config.yaml to match its /data volume: path_prefix: /data, chunks_directory: /data/chunks, and rules_directory: /data/rules. Preserve existing data before changing a running installation. [S14][S27]

    Prepare fresh bind directories: [S14][S16][S18][S28][S29][S30]

    Terminal
    mkdir -p ./log-analyser/grafana ./log-analyser/loki/data ./tracing/tempo-data
sudo chown 472:0 ./log-analyser/grafana
sudo chown 10001:10001 ./log-analyser/loki/data ./tracing/tempo-data

    Tracing arrived in stable-11248, PR #2303. Add to .env; Prosody appends /v1/traces to its HTTP base URL. [S17][S19][S38]

    Config
    ENABLE_TRACING=1
TRACING_ENDPOINT=http://alloy:4317
TRACING_PROTOCOL=grpc
TRACING_HTTP_ENDPOINT=http://alloy:4318

    Use this helper consistently. Changes recreate containers, so schedule maintenance. Without tracing, omit -f tracing.yml and leave it disabled. [S2][S14][S18][S20][S41]

    Terminal
    dc() {
  docker compose -f docker-compose.yml -f prometheus.yml \
    -f grafana.yml -f log-analyser.yml -f tracing.yml \
    -f compose.override.yaml "$@"
}
dc config --quiet
dc run --rm --no-deps --entrypoint promtool prometheus \
  check config /etc/prometheus/prometheus.yml
dc up -d

  5. Docker stable-11248: build Grafana panels. Use your management tunnel. Select Prometheus at http://prometheus:9090. Tempo uses http://tempo:3200. [S16][S26][S39]

    Panel PromQL Unit
    Meetings jitsi_jicofo_conferences Count
    Participants, including visitors jitsi_jicofo_participants_current Count
    Incoming bitrate, per bridge jitsi_jvb_incoming_bitrate / 1e6 Mbps
    Outgoing bitrate, per bridge jitsi_jvb_outgoing_bitrate / 1e6 Mbps
    Incoming loss, per bridge 100 * jitsi_jvb_incoming_loss_fraction Percent
    Outgoing loss, per bridge 100 * jitsi_jvb_outgoing_loss_fraction Percent
    Host non-idle CPU 100 * (1 - avg by (instance) (rate(node_cpu_seconds_total{job="node",mode="idle"}[5m]))) Percent
    Bridge stress jitsi_jvb_stress Ratio

    Loss is a gauge. CPU includes iowait/steal; stress is not CPU percentage. [S8][S9][S22][S36]

    Legacy JVB JSON uses conferences, local_endpoints, bit_rate_download and bit_rate_upload; its bitrates are kilobits per second. stress_level is a load ratio. rtt_aggregate is milliseconds. participants includes relayed endpoints and is deprecated. Jicofo JSON uses conferences and participants for current counts, and total_participants for cumulative joins. Do not sum bridge meeting counts across an Octo deployment. [S7][S8][S44]

  6. Debian/Ubuntu, Jitsi Meet 11248 components: enable local checks. Merge into /etc/jitsi/jicofo/jicofo.conf: [S5][S46]

    Text
    jicofo.health.enabled = true
jicofo.rest.enabled = true
jicofo.rest.host = "127.0.0.1"
jicofo.rest.port = 8888
jicofo.rest.prometheus.enabled = true

    JVB metrics and health already default to enabled on the private loopback listener. For legacy JSON, add videobridge.apis.rest.enabled = true to /etc/jitsi/videobridge/jvb.conf. Restart the affected services: [S3][S7][S11][S45]

    Terminal
    sudo systemctl restart jicofo jitsi-videobridge2

    For native Prometheus 3.15.0, Grafana and exporters on that host, use targets 127.0.0.1:8080, 127.0.0.1:8888, 127.0.0.1:9100 and Blackbox 127.0.0.1:9115. Omit Docker-only otel/prosody jobs. Set your native rule path and Grafana source http://127.0.0.1:9090. Container localhost cannot reach these host listeners. [S24][S26]

    Package logs need a separate file collector for /var/log/jitsi/jvb.log, /var/log/jitsi/jicofo.log and /var/log/prosody/prosody.log; the supplied Docker receiver does not read them. [S11][S15]

Configuration reference

Defaults apply to the pinned versions. [S2][S3][S4][S5][S19][S24]

Setting Location Default Purpose
JICOFO_ENABLE_REST Docker .env 0 Allow container-network access
JICOFO_ENABLE_HEALTH_CHECKS Docker .env Off Register health checks
COLIBRI_REST_ENABLED Docker .env false Enable legacy JVB API
jicofo.health.enabled Package HOCON false Enable health checker
jicofo.rest.enabled, jicofo.rest.host, jicofo.rest.port, jicofo.rest.prometheus.enabled Package HOCON true, 127.0.0.1, 8888, true REST listener and metrics
PROSODY_ENABLE_METRICS, PROSODY_METRICS_ALLOWED_CIDR Docker .env false, 172.16.0.0/12 Enable metrics; permit scraper network [S47][S48]
videobridge.apis.rest.enabled Package HOCON false Enable COLIBRI
ENABLE_TRACING Docker .env 0 Enable trace export
TRACING_ENDPOINT, TRACING_PROTOCOL, TRACING_HTTP_ENDPOINT Docker .env http://alloy:4317, grpc, http://alloy:4318 Trace destinations
scrape_interval, evaluation_interval Prometheus YAML 1m, 1m Example uses 15s
rule_files Prometheus YAML None Load alert rules
job_name, static_configs.targets, metrics_path Scrape jobs Name/targets required; /metrics Identify and locate targets
params, relabel_configs Web probe job None Pass target through Blackbox
alert, expr, for Rule YAML Name/expression required; 0s Example pending periods
prober, timeout, fail_if_not_ssl, insecure_skip_verify Blackbox YAML Prober required; effective timeout depends on scrape; false, false HTTPS validation [S42]
path_prefix, chunks_directory, rules_directory Loki YAML Stock /tmp/loki paths Align persisted storage [S27]
image, ports, volumes, networks, extra_hosts Compose override Inherited or unset Versions, isolation, storage, routing [S20][S41][S43]
logging.driver, logging.options.labels Compose override Daemon default; unset Label JSON logs [S40]
network_mode, pid, command, restart Exporter services Bridge, private PID, image command, no restart Host metrics and exporter startup [S21][S23]

Common mistakes

  • Jicofo health returns 404: enable health checks. Pod-IP probes also need JICOFO_ENABLE_REST=1, the workaround in #2107, closed 2025-06-11. [S4][S5][S32]
  • Grafana cannot connect: use the Prometheus container address and check imported data-source IDs. [S26]
  • Lost logs: fix Loki persistence; preserve volumes when fixing Grafana credentials. [S13][S27]
  • Grafana subpath access: #2272 closed as stale on 2026-09-08. Compose pins Grafana 12.4.8 but supplies no subpath proxy. [S16][S33]

Verify

For both covered install types, run on the Jitsi host with default published ports: [S2][S6][S7]

Terminal
curl --silent --show-error --fail --output /dev/null \
  --write-out '%{http_code}\n' http://127.0.0.1:8080/about/health
curl --silent --show-error --fail http://127.0.0.1:8888/about/health
curl --silent --show-error --fail \
  -H 'Accept: text/plain; version=0.0.4' http://127.0.0.1:8080/metrics

Expect 200, then OK. Prometheus queries jitsi_jvb_healthy, up{job="jvb"}, up{job="jicofo"} and probe_success{job="webprobe"} should return 1. [S8][S23][S24][S34][S37][S49]

Join and leave a test meeting: Grafana conference and participant gauges should change. In Loki Explore, use {exporter="OTLP"} | json | attributes_attrs_service="jitsi-jicofo" and generate fresh activity. In Tempo Explore, confirm new traces after a join. [S9][S13][S15][S17]

If it still fails

Docker: dc logs --tail=100 prometheus otel loki jvb jicofo; include alloy tempo when tracing is enabled. Check targets, permissions and parsing. Packages: read the three log files. For Prosody, check the allowed scraper CIDR. [S11][S14][S18][S47]

FAQ

Do I need a Jitsi Prometheus exporter?

JVB and Jicofo expose /metrics. Node and Blackbox supply host resources and HTTPS probes. [S3][S5][S21][S23]

Can I expose the REST ports publicly?

Keep them private. These listeners include administrative routes beyond health and statistics. [S3][S5]

Does a healthy bridge guarantee working calls?

No. Correlate health with Jicofo bridge status, packet loss and an actual browser meeting test. [S34][S35]

What does tracing add?

Trace spans connect instrumented operations across components, complementing metrics and logs. [S17][S38][S39]

Sources

All sources checked 2026-10-06.

[S1] stable-11248 release, 2026-09-14, release note.

[S2] Docker Compose, stable-11248, source code.

[S3] JVB defaults, 11248, source code.

[S4] Docker Jicofo template, stable-11248, source code.

[S5] Jicofo defaults, 11248, source code.

[S6] Jicofo HTTP handlers, 11248, source code.

[S7] JVB REST API and statistics, 11248, official doc.

[S8] JVB periodic metrics, 11248, source code.

[S9] Jicofo conference metrics, 11248, source code.

[S10] Bridge selector, 11248, source code.

[S11] Quickstart and service restarts, checked 2026-10-06, official doc.

[S12] Prometheus 3.15.0, 2026-09-25, release note.

[S13] Log analyser handbook, checked 2026-10-06, official doc.

[S14] Log Compose, stable-11248, source code.

[S15] Log collector, stable-11248, source code.

[S16] Grafana Compose, stable-11248, source code.

[S17] Distributed tracing PR #2303, 2026-08-28, source code.

[S18] Tracing Compose, stable-11248, source code.

[S19] Environment reference, stable-11248, source code.

[S20] Compose merge rules, checked 2026-10-06, official doc.

[S21] Node Exporter Docker setup, v1.12.1, official doc.

[S22] CPU metric, v1.12.1, source code.

[S23] Blackbox Exporter, v0.28.0, official doc.

[S24] Prometheus configuration, checked 2026-10-06, official doc.

[S25] Alert rules, checked 2026-10-06, official doc.

[S26] Grafana Prometheus connection, checked 2026-10-06, official doc.

[S27] Loki paths, stable-11248, source code.

[S28] Grafana image, v12.4.8, source code.

[S29] Loki image, v3.0.0, source code.

[S30] Tempo image, v3.0.2, source code.

[S31] Rootless Docker paths, checked 2026-10-06, official doc.

[S32] Jicofo probe issue #2107, closed 2025-06-11, community report.

[S33] Grafana issue #2272, closed 2026-09-08, community report.

[S34] JVB health checker, 11248, source code.

[S35] Jicofo health checker, 11248, source code.

[S36] JVB load manager, 11248, source code.

[S37] Metrics negotiation, a09ed33, source code.

[S38] Alloy configuration, stable-11248, source code.

[S39] Tempo configuration, stable-11248, source code.

[S40] JSON logging options, checked 2026-10-06, official doc.

[S41] Prometheus Compose, stable-11248, source code.

[S42] Blackbox configuration, v0.28.0, official doc.

[S43] Docker host gateway, checked 2026-10-06, official doc.

[S44] Jicofo statistics, 11248, source code.

[S45] JVB package configuration, 11248, source code.

[S46] Jicofo package configuration, 11248, source code.

[S47] Prosody template, stable-11248, source code.

[S48] Prosody OpenMetrics, checked 2026-10-06, official doc.

[S49] Health response handler, a09ed33, source code.

Open questions

Server testing remains necessary for the combined stack, alert delivery, dashboards and trace propagation. Rootless daemons, Docker Desktop, package log collection and package tracing need separate configuration.

Stuck, or would rather not do this by hand?

Deploy it in one click

A private Jitsi server in your own AWS account with SSL, your domain and optional recording, transcription and JWT. Free 15 minute trial.

Start free trial

Talk to a Jitsi engineer

Setup, fixes, branding, recording, scaling. Tell us what is happening and we reply with a plan and a quote.

Get expert help

Related

Recently updated