First article for Zabbix

Introduction

Zabbix sert souvent à ouvrir un ticket Jira quand un déclencheur se produit. Le sens inverse est rarement exploité : suivre l’avancement des projets de votre équipe, avec les mêmes graphiques et les mêmes alertes que votre infrastructure.

J’ai voulu répondre aux questions que se posent une DSI ou un responsable d’infrastructure. Combien de tickets restent ouverts sur chaque projet ? Combien sont en retard ? Quel est l’âge du backlog, et comment évolue-t-il ? Cet article présente le modèle Zabbix que j’ai écrit pour cela.

Ce que le modèle mesure

J’ai séparé les métriques selon leur usage dans Zabbix : les unes déclenchent une alerte, les autres alimentent des graphiques. Pour un backlog, la tendance compte plus que la valeur du moment.

Les quatre tranches d’âge sont exclusives : leur somme égale le nombre de tickets ouverts, ce qui permet un graphique empilé qui représente tout le backlog. L’âge moyen est stocké en secondes avec l’unité Zabbix uptime, qui l’affiche par exemple sous la forme 10 days, 04:56:04, d’après la documentation des unités.

D’où viennent les données

Les données viennent de l’API REST de Jira Cloud, version 3. Le script s’y connecte avec l’adresse e-mail d’un compte et un jeton d’API, en authentification HTTP basique, comme le prévoit la documentation Atlassian. /rest/api/3/project/search liste les projets avec leur key, leur name et leur type projectTypeKey, qui vaut software ou business.

Les tickets viennent de /rest/api/3/search/jql. Il remplace /rest/api/3/search, qu’Atlassian a retiré de Jira Cloud, comme le rappelle cet article. Les pages se suivent avec un jeton nextPageToken, jusqu’à ce que la réponse indique isLast, et la JQL doit être bornée, c’est-à-dire contenir au moins une restriction.

Plutôt qu’une requête par projet et par métrique, le script lance les trois requêtes ci-dessous tous projets confondus, puis compte par projet de son côté. La première renvoie les tickets ouverts avec les champs utiles aux calculs, les deux autres ne demandent que le projet. Le nombre d’appels ne dépend donc pas du nombre de projets.

statusCategory != Done
created >= -7d
statusCategory = Done AND resolutiondate >= -7d

Architecture

Deux items Script alimentent tout le reste. Le premier liste les projets pour la règle de découverte, qui crée les items de chaque projet après filtrage. Le second lance les trois requêtes et renvoie un seul JSON, dont chaque item dépendant extrait sa valeur par JSONPath, par exemple :

$.metrics[?(@.key=='{#PROJECT.KEY}')].open

Le script des métriques ne s’exécute qu’une fois par cycle : tous les items dépendants lisent le même JSON.

Des items calculés additionnent les projets découverts. Cette formule donne le total des tickets ouverts et s’ajuste seule quand un projet apparaît ou sort du filtre. Le joker * remplace la clé de projet, et l’hôte est omis (//), comme dans les exemples de la documentation Zabbix.

sum(last_foreach(//jira.tickets.open[*]))

Pour l’âge moyen global, une moyenne des moyennes donnerait le même poids à un petit et à un gros projet. J’expose donc la somme des âges de chaque projet, et la moyenne devient un rapport de deux sommes.

sum(last_foreach(//jira.tickets.openagesum[*])) / sum(last_foreach(//jira.tickets.open[*]))

Zabbix prévient que les deux moitiés d’un tel rapport peuvent porter sur des valeurs différentes. Comme tous les items viennent de la même exécution du script, ce risque reste limité.

Les alertes

Le template définit 

Installation

Il faut un Zabbix 7.4 et un site Jira Cloud.

Le jeton Atlassian

Créez un jeton d’API sur id.atlassian.com/manage-profile/security/api-tokens, avec un compte qui a accès aux projets à suivre. Il expire au bout d’un an par défaut, et vous pouvez choisir une durée de 1 à 365 jours. Testez-le avant de toucher à Zabbix.

curl -s -u 'adresse@exemple.org:JETON' 'https://votre-site.atlassian.net/rest/api/3/myself'
curl -s -u 'adresse@exemple.org:JETON' 'https://votre-site.atlassian.net/rest/api/3/project/search'

Avec un identifiant erroné, j’ai constaté que la seconde commande peut répondre avec une liste de projets vide. La première signale l’erreur.

Les macros

Tout se règle par des macros d’hôte. Le jeton est de type Secret text, et la documentation Zabbix indique qu’il reste utilisable dans les paramètres d’un item Script. Les autres macros filtrent les projets : change_me ne correspond à aucun projet, donc rien n’est exclu par défaut.

Le modèle et les filtres

Importez le modèle depuis le dépôt indiqué dans les ressources, puis liez-le à un hôte. Dans la règle de découverte, choisissez le type de calcul « Et ». Le mode par défaut, « Et/Ou », relie par un OU les conditions portant sur la même macro, ce qui annulerait les exclusions, comme le précise la documentation de la découverte. Mettez par exemple ^software$ dans {$JIRA.PROJECT.TYPE.MATCHES} pour ne suivre que les projets de développement, puis lancez le bouton Tester sur l’item Script des projets : il doit renvoyer vos projets.

Bonnes pratiques

Un jeton expire : notez son échéance et faites échouer la collecte à voix haute. Le script renvoie ses erreurs dans le champ errors du JSON, et une étape de prétraitement « Check for error in JSON » sur $.errors rend l’item non supporté dès que ce champ n’est pas vide. Un déclencheur sur cet état vous prévient.

Atlassian recommande un jeton avec des scopes, plus sûr qu’un jeton classique. J’ai pris un jeton classique, car le script appelle l’adresse du site. Avec des scopes, il faut viser https://api.atlassian.com/ex/jira/{cloudId}, comme l’explique la documentation sur les jetons.

La liste des projets est triée par clé et réduite à quatre champs. Cela permet d’ajouter « Discard unchanged with heartbeat » sur l’item des projets : la valeur n’est transmise que si la liste change. Sans tri, un simple changement d’ordre ferait croire à une modification.

Réglez le délai d’exécution des items Script, de 1 à 600 secondes, selon votre volume de tickets. Je recommande une découverte toutes les heures et une collecte toutes les 10 à 15 minutes. Les noms de priorité (Highest, High) et de type (Bug) sont des constantes en tête du script. Côté alertes, commencez par un déclencheur sur les retards, du type last(/Jira/jira.tickets.overdue[{#PROJECT.KEY}])>0, puis ajustez les seuils.

Pour conclure

Zabbix ne sert pas qu’à envoyer des alertes dans Jira : il peut aussi suivre l’avancement des projets de votre équipe, avec les outils que vous utilisez déjà pour votre infrastructure. La valeur vient de l’historique : dans quelques semaines, les courbes de flux et d’âge du backlog diront si une équipe rattrape son retard. Le report de tickets d’un sprint à l’autre n’est pas encore couvert. Le modèle est disponible dans les ressources ci-dessous.

Ressources

Le modèle et son README se trouvent sur mon GitHub.

Documentation Atlassian :

• Manage API tokens for your Atlassian account
• Run JQL search query using Jira Cloud REST API
• What is advanced search in Jira Cloud?