doc-locale/fr-fr/operations/incident_management/integrations.md
{{< details >}}
{{< /details >}}
GitLab peut accepter des alertes de n'importe quelle source via un récepteur de webhook. Les notifications d'alerte peuvent déclencher des appels pour les rotations d'astreinte ou être utilisées pour créer des incidents.
Avec le rôle Maintainer ou Owner, vous pouvez consulter la liste des intégrations d'alertes configurées en accédant à Paramètres > Supervision dans le menu latéral de votre projet, et en développant la section Alertes. La liste affiche le nom, le type et le statut de l'intégration (activée ou désactivée) :
GitLab peut recevoir des alertes via un point de terminaison HTTP que vous configurez.
L'activation d'un point de terminaison d'alerte dans un projet GitLab lui permet de recevoir des charges utiles d'alerte au format JSON. Vous pouvez toujours personnaliser la charge utile selon vos besoins.
{{< details >}}
{{< /details >}}
Avec GitLab Premium, vous pouvez créer plusieurs points de terminaison d'alerte uniques pour recevoir des alertes de n'importe quelle source externe au format JSON, et vous pouvez personnaliser la charge utile.
Connectez-vous à GitLab en tant qu'utilisateur disposant du rôle Maintainer pour un projet.
Accédez à Paramètres > Supervision dans votre projet.
Développez la section Alertes.
Pour chaque point de terminaison que vous souhaitez créer :
Sélectionnez Ajouter une nouvelle intégration.
Dans la liste déroulante Sélectionnez le type d'intégration, sélectionnez Prometheus pour les alertes Prometheus, ou Point de terminaison HTTP pour tout autre outil de supervision. Voir les détails
Nommez l'intégration.
Activez le paramètre d'alerte Actif. L'URL et la Authorization Key pour la configuration du webhook sont disponibles dans l'onglet Afficher les identifiants après avoir enregistré l'intégration. Vous devez également saisir l'URL et la clé d'autorisation dans votre service externe.
facultatif. Pour mapper les champs de l'alerte de votre outil de supervision avec les champs GitLab, saisissez un exemple de charge utile et sélectionnez Parse payload for custom mapping. Un JSON valide est requis. Si vous mettez à jour un exemple de charge utile, vous devez également remapper les champs. Pour les intégrations Prometheus, saisissez une seule alerte à partir de la clé alerts de la charge utile au lieu de la charge utile entière.
facultatif. Si vous avez fourni un exemple de charge utile valide, sélectionnez chaque valeur dans Clé d'alerte de la charge utile pour mapper vers une Clé d'alerte GitLab.
Pour enregistrer votre intégration, sélectionnez Save Integration. Si vous le souhaitez, vous pouvez envoyer une alerte de test depuis l'onglet Envoyer une alerte de test de votre intégration après la création de celle-ci.
Le nouveau point de terminaison HTTP s'affiche dans la liste des intégrations. Vous pouvez modifier l'intégration en sélectionnant l'icône des paramètres {{< icon name="settings" >}} sur le côté droit de la liste des intégrations.
Vous pouvez intégrer le format d'alerte de votre outil de supervision avec les alertes GitLab. Pour afficher les informations correctes dans la liste des alertes et la page des détails de l'alerte, mappez les champs de votre alerte avec les champs GitLab lorsque vous créez un point de terminaison HTTP :
Pour envoyer des notifications d'alerte Prometheus à GitLab, copiez l'URL et la clé d'autorisation depuis votre intégration Prometheus dans la section webhook_configs de la configuration Prometheus Alertmanager :
receivers:
- name: gitlab
webhook_configs:
- http_config:
authorization:
type: Bearer
credentials: 1234567890abdcdefg
send_resolved: true
url: http://IP_ADDRESS:PORT/root/manual_prometheus/prometheus/alerts/notify.json
# Rest of configuration omitted
# ...
Pour les points de terminaison HTTP sans mappages personnalisés, vous pouvez personnaliser la charge utile en envoyant les paramètres suivants. Tous les champs sont facultatifs. Si l'alerte entrante ne contient pas de valeur pour le champ Title, une valeur par défaut de New: Alert est appliquée.
| Propriété | Type | Description |
|---|---|---|
title | Chaîne | Le titre de l'alerte. |
description | Chaîne | Un résumé général du problème. |
start_time | DateHeure | L'heure de l'alerte. Si aucune valeur n'est fournie, l'heure actuelle est utilisée. |
end_time | DateHeure | L'heure de résolution de l'alerte. Si cette valeur est fournie, l'alerte est résolue. |
service | Chaîne | Le service affecté. |
monitoring_tool | Chaîne | Le nom de l'outil de supervision associé. |
hosts | Chaîne ou tableau | Un ou plusieurs hôtes indiquant où cet incident s'est produit. |
severity | Chaîne | La gravité de l'alerte. Non sensible à la casse. Peut être l'une des valeurs suivantes : critical, high, medium, low, info, unknown. La valeur par défaut est critical si la valeur est manquante ou absente de cette liste. |
fingerprint | Chaîne ou tableau | L'identifiant unique de l'alerte. Cet identifiant peut être utilisé pour regrouper les occurrences d'une même alerte. Lorsque la fonctionnalité generic_alert_fingerprinting est activée, l'empreinte est générée automatiquement à partir de la charge utile (en excluant les paramètres start_time, end_time et hosts). |
gitlab_environment_name | Chaîne | Le nom de l'environnement GitLab associé. Requis pour afficher les alertes sur un tableau de bord. |
Vous pouvez également ajouter des champs personnalisés à la charge utile de l'alerte. Les valeurs des paramètres supplémentaires ne sont pas limitées aux types primitifs (tels que les chaînes ou les nombres), mais peuvent être un objet JSON imbriqué. Par exemple :
{ "foo": { "bar": { "baz": 42 } } }
[!note] Assurez-vous que vos requêtes sont inférieures aux limites d'application de charge utile.
Exemple de charge utile :
{
"title": "Incident title",
"description": "Short description of the incident",
"start_time": "2019-09-12T06:00:55Z",
"service": "service affected",
"monitoring_tool": "value",
"hosts": "value",
"severity": "high",
"fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
"foo": {
"bar": {
"baz": 42
}
}
}
Les alertes doivent être formatées pour un récepteur de webhook Prometheus.
Attributs requis de premier niveau :
alertscommonAnnotationscommonLabelsexternalURLgroupKeygroupLabelsreceiverstatusversionÀ partir de alerts dans la charge utile Prometheus, une alerte GitLab est créée pour chaque élément du tableau. Vous pouvez modifier les paramètres imbriqués listés ci-dessous pour configurer l'alerte GitLab.
| Attribut | Type | Obligatoire | Description |
|---|---|---|---|
L'un des attributs suivants : annotations/title, annotations/summary ou labels/alertname | Chaîne | Oui | Le titre de l'alerte. |
startsAt | DateHeure | Oui | L'heure de début de l'alerte. |
annotations/description | Chaîne | Non | Un résumé général du problème. |
annotations/gitlab_incident_markdown | Chaîne | Non | GitLab Flavored Markdown à ajouter à tout incident créé à partir de l'alerte. |
annotations/runbook | Chaîne | Non | Lien vers la documentation ou les instructions pour gérer cette alerte. |
endsAt | DateHeure | Non | L'heure de résolution de l'alerte. |
Paramètre de requête g0.expr dans generatorUrl | Chaîne | Non | Requête de la métrique associée. |
labels/gitlab_environment_name | Chaîne | Non | Le nom de l'environnement GitLab associé. Requis pour afficher les alertes sur un tableau de bord. |
labels/severity | Chaîne | Non | La gravité de l'alerte. Doit correspondre à l'une des options de gravité Prometheus. La valeur par défaut est critical si la valeur est manquante ou absente de cette liste. |
status | Chaîne | Non | Statut de l'alerte dans Prometheus. Si la valeur est « resolved », l'alerte est résolue. |
L'un des attributs suivants : annotations/gitlab_y_label, annotations/title, annotations/summary ou labels/alertname | Chaîne | Non | Le label de l'axe Y à utiliser lors de l'intégration des métriques de cette alerte dans GitLab Flavored Markdown. |
Les attributs supplémentaires inclus dans annotations sont disponibles sur la page des détails de l'alerte. Tous les autres attributs sont ignorés.
Les attributs ne sont pas limités aux types primitifs (tels que les chaînes ou les nombres), mais peuvent être un objet JSON imbriqué. Par exemple :
{
"target": {
"user": {
"id": 42
}
}
}
[!note] Assurez-vous que vos requêtes sont inférieures aux limites d'application de charge utile.
Les alertes Prometheus peuvent fournir l'une des valeurs suivantes (non sensibles à la casse) pour la gravité d'alerte :
critical, s1, p1, emergency, fatalhigh, s2, p2, major, pagemedium, s3, p3, error, alertlow, s4, p4, warn, warninginfo, s5, p5, debug, information, noticeLa gravité est définie par défaut sur critical si la valeur est manquante ou absente de cette liste.
Exemple de règle d'alerte :
groups:
- name: example
rules:
- alert: ServiceDown
expr: up == 0
for: 5m
labels:
severity: high
annotations:
title: "Example title"
runbook: "http://example.com/my-alert-runbook"
description: "Service has been down for more than 5 minutes."
gitlab_y_label: "y-axis label"
foo:
bar:
baz: 42
Exemple de charge utile de requête :
{
"version" : "4",
"groupKey": null,
"status": "firing",
"receiver": "",
"groupLabels": {},
"commonLabels": {},
"commonAnnotations": {},
"externalURL": "",
"alerts": [{
"startsAt": "2022-010-30T11:22:40Z",
"generatorURL": "http://host?g0.expr=up",
"endsAt": null,
"status": "firing",
"labels": {
"gitlab_environment_name": "production",
"severity": "high"
},
"annotations": {
"title": "Example title",
"runbook": "http://example.com/my-alert-runbook",
"description": "Service has been down for more than 5 minutes.",
"gitlab_y_label": "y-axis label",
"foo": {
"bar": {
"baz": 42
}
}
}
}]
}
[!note] Lorsque vous déclenchez une alerte de test, saisissez la charge utile entière telle qu'indiquée dans l'exemple. Lorsque vous configurez des mappages personnalisés, saisissez uniquement le premier élément du tableau
alertscomme exemple de charge utile.
Les méthodes d'autorisation suivantes sont acceptées :
Les valeurs <authorization_key> et <url> peuvent être trouvées lors de la configuration d'une intégration d'alerte.
La clé d'autorisation peut être utilisée comme jeton Bearer :
curl --request POST \
--data '{"title": "Incident title"}' \
--header "Authorization: Bearer <authorization_key>" \
--header "Content-Type: application/json" \
<url>
La clé d'autorisation peut être utilisée comme password. Le champ username est laissé vide :
<blank><authorization_key>curl --request POST \
--data '{"title": "Incident title"}' \
--header "Authorization: Basic <base_64_encoded_credentials>" \
--header "Content-Type: application/json" \
<url>
L'authentification basique peut également être utilisée avec des identifiants directement dans l'URL :
curl --request POST \
--data '{"title": "Incident title"}' \
--header "Content-Type: application/json" \
<username:password@url>
[!warning] L'utilisation de votre clé d'autorisation dans l'URL est risquée, car elle est visible dans les journaux du serveur. Nous recommandons d'utiliser l'une des options d'en-tête décrites précédemment si votre outil le prend en charge.
Le corps de réponse JSON contient la liste des alertes créées dans la requête :
[
{
"iid": 1,
"title": "Incident title"
},
{
"iid": 2,
"title": "Second Incident title"
}
]
Les réponses réussies renvoient un code de réponse 200.
Après qu'un responsable de maintenance ou propriétaire du projet configure une intégration, vous pouvez déclencher une alerte de test pour confirmer que votre intégration fonctionne correctement.
GitLab affiche un message d'erreur ou de succès selon le résultat de votre test.
{{< details >}}
{{< /details >}}
GitLab regroupe les alertes en fonction de leur charge utile. Lorsqu'une alerte entrante contient la même charge utile qu'une autre alerte (à l'exclusion des attributs start_time et hosts), GitLab regroupe ces alertes et affiche un compteur sur la liste de gestion des alertes et les pages de détails.
Si l'alerte existante est déjà resolved, GitLab crée une nouvelle alerte à la place.
L'alerte dans GitLab est automatiquement résolue lorsqu'un point de terminaison HTTP reçoit une charge utile avec l'heure de fin de l'alerte définie. Pour les points de terminaison HTTP sans mappages personnalisés, le champ attendu est end_time. Avec les mappages personnalisés, vous pouvez sélectionner le champ attendu.
GitLab détermine l'alerte à résoudre en fonction de la valeur fingerprint qui peut être fournie dans la charge utile. Pour plus d'informations sur les propriétés et les mappages des alertes, consultez Personnaliser la charge utile d'alerte en dehors de GitLab.
Vous pouvez également configurer l'incident associé pour qu'il soit fermé automatiquement lorsque l'alerte est résolue.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
[!warning] Nous développons une intégration plus poussée avec Opsgenie et d'autres outils d'alerte via les intégrations de points de terminaison HTTP afin que vous puissiez consulter les alertes dans l'interface GitLab.
Vous pouvez surveiller les alertes en utilisant une intégration GitLab avec Opsgenie.
Si vous activez l'intégration Opsgenie, vous ne pouvez pas avoir d'autres services d'alerte GitLab actifs en même temps.
Pour activer l'intégration Opsgenie :
https://app.opsgenie.com/alert/list.Après avoir activé l'intégration, accédez à la page Alertes via Supervision > Alertes, puis sélectionnez View alerts in Opsgenie.