# Monitor YouTrack Performance

YouTrack provides performance metrics that help you monitor the load and health of your site. Continuous monitoring helps you spot changes in these metrics and investigate unusual behavior before it affects users. If a problem does occur, graphs that show metric history can help JetBrains Support troubleshoot the problem and identify when the behavior changed.

For YouTrack Server, you can collect Java Management Extensions (JMX) metrics with Prometheus and `jmx_exporter`, then visualize the collected data in a Grafana dashboard.

![Grafana dashboard for YouTrack metrics.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/grafana-dashboard-heap-memory.png)

This solution lets you monitor the following data over time:

* Application-level metrics for YouTrack activity, version information, and storage usage.

* Database performance metrics for the Xodus environment, including transaction rates and disk usage.

* JVM statistics for heap and off-heap memory, garbage collection, thread counts, loaded classes, and file descriptors.

* Host resource metrics such as process CPU load relative to the host system.

Prometheus scrapes YouTrack metrics on a regular schedule and stores the collected values in your monitoring system.

You can also view metrics in the user interface when you need a current snapshot, or collect telemetry data programmatically with the REST API when you want to store metric values over time.

## Before You Start

* To collect metrics with Prometheus and `jmx_exporter`, you need access to the server host or Docker container where YouTrack Server runs, permission to change JVM options, and the ability to restart YouTrack.

* Make sure the Prometheus server can reach the port that `jmx_exporter` uses to expose metrics. Restrict access to this port so it is only available to trusted monitoring systems.

## Collect Metrics with Prometheus and jmx_exporter

Prometheus can collect YouTrack Server metrics from the `jmx_exporter` Java agent. The Java agent runs in the YouTrack JVM, collects JMX MBean values, and exposes them in Prometheus format on an HTTP endpoint.

> **Note: Availability**
> This method is only available for YouTrack Server. YouTrack Cloud sites cannot be configured with custom JVM agents.

Procedure: To expose YouTrack Server metrics with jmx_exporter:

1. Download the `jmx_prometheus_javaagent` JAR file from the [Prometheus JMX Exporter artifacts page](https://prometheus.github.io/jmx_exporter/reference/artifacts/).

2. Save the JAR file and an exporter configuration file in a location that is readable by the YouTrack service.

For Docker installations, you can store both files in a host directory that is mapped to `/opt/youtrack/prometheus` inside the container. The examples on this page assume the following paths inside the container:

* `/opt/youtrack/prometheus/jmx_prometheus_javaagent.jar`

* `/opt/youtrack/prometheus/jmx_exporter.yml`

3. Add the minimal configuration to the `jmx_exporter.yml` file:

```YAML
---

startDelaySeconds: 10
lowercaseOutputName: false
lowercaseOutputLabelNames: false

whitelistObjectNames:
# JVM
- "java.lang:type=Runtime"
- "java.lang:type=OperatingSystem"
# Xodus
- "jetbrains.exodus.env: type=EnvironmentConfig,*"
- "jetbrains.exodus.env: type=EnvironmentStatistics,*"
- "jetbrains.exodus.entitystore: type=EntityStoreStatistics,*"
# YouTrack
- "jetbrains.youtrack:type=*,name=UserSessions"
- "jetbrains.youtrack:type=*,name=HubIntegration"
- "jetbrains.youtrack:type=*,name=NotificationsSender"
- "jetbrains.youtrack:type=*,name=JobProcessorsTelemetry"
- "jetbrains.youtrack:type=*,name=ZendeskIntegration"
- "jetbrains.youtrack:type=*,name=SemanticSearchMetrics"
- "jetbrains.youtrack:type=*,name=GrazieIntegration"
- "jetbrains.youtrack:type=JobProcessor,*"
- "jetbrains.youtrack:type=JobThreadPool,*"
- "jetbrains.youtrack:type=Workflow,*"
- "jetbrains.youtrack:type=TextIndex,*"
- "jetbrains.youtrack:type=Maintenance,name=Global"

rules:
- pattern: 'java.lang<type=Runtime><>Uptime:'
  name: process_uptime
  help: Total time elapsed since process start in milliseconds
  type: COUNTER

- pattern: 'java.lang<type=OperatingSystem><>ProcessCpuLoad:'
  name: process_cpu_load
  help: Current process cpu usage share
  type: GAUGE

- pattern: 'jetbrains.exodus.env< type=EnvironmentConfig,  location=(.*)><>(EnvIsReadonly|GcEnabled|GcMinUtilization):'
  name: youtrack_$2
  labels:
      path: $1
  help: Xodus environment state

- pattern: 'jetbrains.exodus.env< type=EnvironmentStatistics,  location=(.*)><>(\w+):'
  name: youtrack_$2
  labels:
      path: $1
  help: Xodus environment metrics

- pattern: 'jetbrains.exodus.entitystore< type=EntityStoreStatistics,  location=(.*),  name=teamsysstore><>(\w+):'
  name: youtrack_$2
  labels:
      path: $1
  help: Xodus entity store metrics

- pattern: 'jetbrains.youtrack<type=Maintenance, name=Global><>(\w+): ([\.\w]+)'
  name: youtrack_version_info
  labels:
      $1: $2
  value: 1.0
  type: GAUGE
  help: Application version info

# Background jobs metrics flatten out by type and attribute, name as label
- pattern: 'jetbrains.youtrack<type=(JobProcessor|JobThreadPool), name=(\w+)><>(\w+):'
  name: youtrack_$1_$3
  labels:
      name: $2

- pattern: 'jetbrains.youtrack<type=Workflow, name=(\w+), script=([\w_\-\/@]+)><>(TotalDuration): ([0-9][0-9][0-9][0-9].*)'
  name: youtrack_Workflow_$1_$3
  help: Workflow JS metrics
  labels:
      script: $2
  value: $4

- pattern: 'jetbrains.youtrack<type=Workflow, name=(\w+), script=([\w_\-\/@]+)><>(TotalCount): ([0-9][0-9].*)'
  name: youtrack_Workflow_$1_$3
  help: Workflow JS metrics
  labels:
      script: $2
  value: $4

- pattern: 'jetbrains.youtrack<type=Workflow, name=(\w+), script=([\w_\-\/@]+)><>(FailedCount): ([1-9].*)'
  name: youtrack_Workflow_$1_$3
  help: Workflow JS metrics
  labels:
      script: $2
  value: $4

- pattern: 'jetbrains.youtrack<type=TextIndex, name=\w+><>(\w+):'
  name: youtrack_TextIndex_$1
  help: Text index metrics

# Generic pattern
- pattern: 'jetbrains.youtrack<type=\w+, name=(\w+)><>(\w+):'
  name: youtrack_$1_$2
```

You can later replace this configuration with a stricter rule set that only exports the metrics you want Prometheus to collect.

4. Stop YouTrack Server.

For Docker installations, run:

```CONSOLE
docker exec <containerId> stop
```

5. Add the `jmx_exporter` Java agent to the YouTrack JVM options.

The following example exposes metrics on port `9404`:

```CONSOLE
@jmx_exporter=-javaagent:/opt/youtrack/prometheus/jmx_prometheus_javaagent.jar=9404:/opt/youtrack/prometheus/jmx_exporter.yml-jmx_exporter
```

For more information about setting JVM options, see [Configure JVM Options](configure-jvm-options.html).

6. Make the exporter port reachable from Prometheus.

For Docker installations, publish the exporter port when you run the YouTrack container. Mount the directory that contains the `jmx_prometheus_javaagent` JAR file and the `jmx_exporter.yml` file to `/opt/youtrack/prometheus`. For example, add the following options to the `docker run` command:

```CONSOLE
-v <path to directory with prometheus files>:/opt/youtrack/prometheus \ -p 9404:9404
```

If the existing container was created without this port mapping, recreate the container with the same data, configuration, logs, and backups volumes, then add the exporter port mapping. For more information about running YouTrack in Docker, see [Start YouTrack with a Docker Container](stop-and-start-youtrack.html#youtrack-docker-start).

For non-Docker installations, allow incoming connections to the exporter port only from your Prometheus server or trusted monitoring network.

7. Start YouTrack Server.

8. Check that the metrics endpoint is available:

```CONSOLE
curl http://<youtrack-host>:9404/metrics
```

If YouTrack does not start or the endpoint is unavailable, check the YouTrack logs for errors related to the Java agent path, exporter port, or YAML configuration.

## Docker Configuration Example

If you run YouTrack Server in Docker, mount the directory that contains the `jmx_prometheus_javaagent` JAR file and `jmx_exporter.yml` to `/opt/youtrack/prometheus`, then publish the metrics port.

docker-compose.yaml:

```YAML
services:
    youtrack:
        image: jetbrains/youtrack:<version>
        hostname: youtrack
        ports:
            - "<port on host>:8080"
            - "<metrics port on host>:9404"
        volumes:
            - <path to data directory>:/opt/youtrack/data
            - <path to conf directory>:/opt/youtrack/conf
            - <path to logs directory>:/opt/youtrack/logs
            - <path to backups directory>:/opt/youtrack/backups
            - <path to youtrack.jvmoptions>:/opt/youtrack/conf/youtrack.jvmoptions
            - <path to directory with prometheus files>:/opt/youtrack/prometheus
```

docker run:

```CONSOLE
docker run -it --name <youtrack-server-instance> \
  -v <path to data directory>:/opt/youtrack/data \
  -v <path to conf directory>:/opt/youtrack/conf \
  -v <path to logs directory>:/opt/youtrack/logs \
  -v <path to backups directory>:/opt/youtrack/backups \
  -v <path to directory with prometheus files>:/opt/youtrack/prometheus \
  -v <path to youtrack.jvmoptions>:/opt/youtrack/conf/youtrack.jvmoptions \
  -p <port on host>:8080 \
  -p <metrics port on host>:9404 \
  jetbrains/youtrack:<version>
```

## Scrape Metrics with Prometheus

After `jmx_exporter` exposes metrics from YouTrack Server, add the endpoint to your Prometheus configuration.

If you plan to use a Grafana dashboard, configure labels that let the dashboard filter metrics by Prometheus server and YouTrack instance.

```YAML
global:
    scrape_interval: 15s
    scrape_timeout: 15s
    evaluation_interval: 1m
    label_limit: 16
    label_name_length_limit: 64
    label_value_length_limit: 128
    external_labels:
        prometheus: Prometheus
```

Then add a scrape configuration for the `jmx_exporter` endpoint:

```YAML
scrape_configs:
    - job_name: "youtrack"
      metrics_path: /metrics
      sample_limit: 10000
      label_limit: 20
      relabel_configs:
          - source_labels: [ __address__ ]
            regex: ([^:]+)(:\d+)?
            target_label: instance
      static_configs:
          - targets: ["<youtrack-host>:9404"]
```

If your installation has many workflow scripts, the metrics endpoint can return thousands of samples. Set `sample_limit` high enough for the number of samples returned by `http://<youtrack-host>:9404/metrics`. If the limit is too low, Prometheus cannot scrape the full response.

Reload or restart Prometheus after updating the configuration. Prometheus starts collecting metrics from the YouTrack Server JVM on the next scrape interval.

## Connect AlertManager to Prometheus

You can manage alerts sent by YouTrack Server using Prometheus AlertManager. To receive notifications about current issues displayed on the dashboard, configure the Prometheus AlertManager endpoint:

```YAML
alerting:
  alertmanagers:
    - static_configs:
          - targets: [ '<alertmanager-host>:9093' ]
```

Next, add alert rules configuration to collect alerts exposed by their rules:

```YAML
rule_files:
  - /etc/prometheus/rules/*.yml
```

Choose the appropriate platform as a receiver of notifications via Slack, Email, etc.

## Grafana JMX Exporter Dashboard Overview

The [JMX Exporter dashboard](https://grafana.com/grafana/dashboards/25479-jmx-exporter/) gives administrators a centralized view of YouTrack Server health, performance, and resource usage. It is designed to help you monitor the internal state of the YouTrack application and identify bottlenecks, resource exhaustion, or unusual behavior patterns.

![Grafana dashboard for YouTrack metrics.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/grafana-dashboard-overview.png)

The dashboard combines several layers of monitoring data:

* Application-level metrics for YouTrack activity, version information, and storage usage.

* Database performance metrics for the Xodus environment, including transaction rates and disk usage.

* JVM statistics for heap and off-heap memory, garbage collection, thread counts, loaded classes, and file descriptors.

* Host resource metrics such as process CPU load relative to the host system.

The monitoring data follows the same flow as the Prometheus setup described in the section above. The `jmx_prometheus_javaagent` runs inside the YouTrack JVM, reads MBeans from the platform MBean server, and exposes the collected values as Prometheus-compatible metrics on the `/metrics` endpoint. Prometheus scrapes this endpoint on the configured schedule, and Grafana uses Prometheus as the data source for the dashboard.

The published dashboard is generated with the Grafana Foundation SDK.

## Grafana Dashboard Key Metrics

The dashboard is organized into functional rows that group related YouTrack, Xodus, JVM, and host metrics.

| Dashboard area | Key metrics |
| --- | --- |
| App Overview | Uptime, active users, database and text index size, and YouTrack version information. |
| Application Activity and Performance | User activity, live updates, disk usage history, Xodus transaction rates, cache hit-and-miss rates, cache job queue status, and Grazie integration performance. |
| JVM Internals | Heap memory usage, garbage collection count and duration, off-heap and native memory usage, thread counts, loaded and unloaded classes, open file descriptors, and network sockets. |
| Host Metrics | Process CPU load relative to the host system. |

## Configure the Grafana Data Source

Before you import the dashboard, make sure Grafana has a Prometheus data source that points to the Prometheus server that scrapes YouTrack metrics.

If you provision Grafana from files, create the data source configuration at `grafana/provisioning/datasources/prometheus.yml`:

```YAML
apiVersion: 1
datasources:
    name: Prometheus
    type: prometheus
    uid: YT-pmc
    access: proxy
    url: http://prometheus:9090
    isDefault: true
```

If you add the data source in the Grafana user interface, set the data source type to Prometheus and use the URL for your Prometheus server.

Set the Grafana data source Scrape interval option to a value that matches your metrics storage. For Prometheus and Thanos, use a value that is two to three times the Prometheus `scrape_interval`, for example, `45s` when Prometheus scrapes every `15s`. For VictoriaMetrics, you can use the same value as the Prometheus `scrape_interval`.

YouTrack dashboards use the `$__interval` variable. If dashboard panels return sparse or incomplete data with Prometheus or Thanos, increase the data source scrape interval or use the [$__rate_interval workaround](https://grafana.com/docs/grafana/latest/datasources/prometheus/template-variables/#use-__rate_interval) where appropriate.

## Import the Dashboard into Grafana

After Prometheus starts collecting metrics from YouTrack Server, you can import the [YouTrack JMX Exporter dashboard](https://grafana.com/grafana/dashboards/25479-jmx-exporter/) into Grafana. This dashboard visualizes the metrics that Prometheus collects from the `jmx_exporter` endpoint.

Procedure: To import the YouTrack JMX Exporter dashboard into Grafana:

1. Open Grafana.

2. In the main menu, select Dashboards.

3. Click New, then select Import dashboard.

4. In the import field, enter the dashboard ID `25479` or paste the dashboard URL.

5. Click Load.

6. Select the Prometheus data source that scrapes the YouTrack metrics endpoint.

7. Click Import.

If the dashboard opens without data, check that Prometheus can scrape `http://<youtrack-host>:9404/metrics`, then make sure the dashboard uses the same Prometheus data source.

To manage Grafana dashboards as code, use the Grafana Foundation SDK to define dashboards and generate the JSON files that Grafana imports. This approach lets you keep dashboards in version control and automate updates. For more information, see the [Grafana Foundation SDK documentation](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/).

## Collect Metrics with the REST API

Use the REST API when you want a monitoring tool or script to poll YouTrack and save metric values over time. The telemetry endpoint returns JSON and only includes the fields you request.

The resource path is `/api/admin/telemetry`. The list of returned attributes depends on whether you use YouTrack Server or YouTrack Cloud. For attributes that are not supported in your edition, YouTrack returns `null`.

Procedure: To collect performance metrics with the REST API:

> **Tip:**
> Requires permissions: Low-level Admin Read

1. Generate a permanent token for a user account that has the Low-level Admin Read permission.

2. Choose the telemetry fields that you want to collect. Common fields for performance monitoring include `databaseSize`, `fullDatabaseSize`, `textIndexSize`, `requestsPerSecond`, `transactionsPerSecond`, `pendingAsyncJobs`, `onlineUsers(users)`, `uptime`, and `startedTime`.

3. Send a `GET` request to `<youtrack-base-url>/api/admin/telemetry` with the selected fields in the `fields` query parameter and the token in the `Authorization` header.

4. Configure your monitoring tool to repeat the request on the schedule that matches your monitoring needs.

Replace `youtrack.example.com` with the base URL for your installation.

```BASH
curl -X GET \
  'https://youtrack.example.com/api/admin/telemetry?fields=databaseSize,uptime,startedTime,textIndexSize,onlineUsers(users)' \
  -H 'Authorization: Bearer <permanent-token>' \
  -H 'Accept: application/json'
```

A successful request returns a JSON object with the requested fields.

```JSON
{
    "startedTime": 1610613083628,
    "databaseSize": "5.0 MB",
    "textIndexSize": "0.1 MB",
    "uptime": "644 hours, 19 minutes, 10 seconds and 121 milliseconds",
    "onlineUsers": {
        "users": 12,
        "$type": "OnlineUsers"
    },
    "$type": "Telemetry"
}
```

For the complete list of telemetry fields and their data types, see the [REST API reference for telemetry data](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/operations-api-admin-telemetry.html).

## Collect Metrics from the User Interface

Use the Server Metrics page when you need to review the current values manually, for example, while troubleshooting a slow site or collecting information for a support request.

Procedure: To view performance metrics in YouTrack:

> **Tip:**
> Requires permissions: Low-level Admin Read

1. Open the ![](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/settings.svg) Administration menu and select `Server Settings > Global Settings`.

2. Scroll to the bottom of the Server Configuration tab.

3. In the Server Metrics section, click View server metrics.

4. Review the values on the Server Metrics page and record the metrics that are relevant to your investigation.

For detailed descriptions of the metrics shown on this page, see [Server Metrics](admin-statistics.html).