krpn / youtrack-issues-prometheus-exporter

Export YouTrack issues to Prometheus for any search queries

youtrack-issues-prometheus-exporter

youtrack-issues-prometheus-exporter exports YouTrack issues to Prometheus for any search queries

Table of Contents

• Features
• Quick Start
• Configuration
• Exposed Prometheus Metrics
• Command-Line Flags
• Contribute

Features

• Export issues for any search query from config
• [!] Works only with YouTrack 2018.3 and above because uses "new" REST API
• A docker image available on Docker Hub

(back to top)

Quick Start

1. Prepare config.json file based on example (details in configuration)

2. Run container with command (cli flags):

   docker run -d -p <port>:8080 -v <path to config.json dir>:/config --name youtrack-exporter krpn/youtrack-issues-prometheus-exporter

3. Checkout logs (will be empty if ok):

   docker logs youtrack-exporter

4. Add youtrack-exporter instance to Prometheus scrape targets (port from docker run command)

5. Add alerting rules based on metrics if needed, for example:

   groups:
   - name: youtrack.rules
     rules:
     
     - alert: YouTrackShowStopper
       expr: youtrack_issues{query="showstopper"} == 1
       for: 1m
       annotations:
         description: 'Show-Stopper {{ $labels.id }} {{ $labels.title }}: https://youtrack.company.com/issue/{{ $labels.id }}'
     
     - alert: YouTrackExporterError
       expr: sum(increase(youtrack_errors[1m])) by (error) > 0
       for: 1m
       annotations:
         description: 'YouTrack exporter got error: {{ $labels.error }}'

(back to top)

Configuration

Configuration file based on JSON format. Example:

{
  "endpoint": "https://youtrack.company.com/",
  "token": "perm:YWxleGtydXBpbg==.QWxleGFuZGVy.9nvYkHL4aHy0zHaEGIXmjcGjVNx6Kr",
  "queries": {
    "showstopper": "Show-Stopper #Unresolved #Unassigned",
    "unresolved": "#Unresolved State: Submitted"
  },
  "refresh_delay_seconds": 10,
  "request_timeout_seconds": 10,
  "listen_port": 8080
}

Setting	Type	Description	Example
endpoint	string	YouTrack URL without path	https://youtrack.company.com/
token	string	YouTrack API permanent token	perm:YWxleGtydXBpbg==.QWxleGFuZGVy.9nvYkHL4aHy0zHaEGIXmjcGjVNx6Kr
queries	object	Map of search queries where key is search query name and value is search query string. Query name will be passed to metric label query	{"showstopper": "Show-Stopper #Unresolved #Unassigned", "unresolved": "#Unresolved State: Submitted"}
refresh_delay_seconds	integer	(optional, default: 10) Refresh metrics delay seconds. Metrics automatically refreshes in background	60
request_timeout_seconds	integer	(optional, default: 10) Request timeout seconds for YouTrack REST API HTTP request	30
listen_port	integer	(optional, default: 8080) HTTP port to listen on	80

(back to top)

Exposed Prometheus Metrics

Name	Description	Labels
youtrack_issues	Query issues. Equals 1 if task for this query is found. Equals 0 if not found (but was found before)	query id title
youtrack_errors	Errors counter. Increments when error is occurred	query error

(back to top)

Command-Line Flags

Usage: youtrack-issues-prometheus-exporter [<flags>]

Flag	Type	Description	Default
-c or --config	string	Path to config file	config/config.json
--help		Show help

(back to top)

Contribute

Please feel free to send me pull requests.

(back to top)