Configuration de la supervision externe avec OpenTelemetry

Approches de supervision externe

La supervision externe avec OpenTelemetry vous permet d’intégrer votre instance GitHub Enterprise Server à l’infrastructure et aux outils de supervision existants. GitHub Enterprise Server propose deux approches principales pour la surveillance externe :

1.        **Point de terminaison Prometheus** : Exposer les métriques au format Prometheus pour que les outils externes puissent les récupérer
   

2.        **Pipelines OpenTelemetry personnalisés** : configurer le collecteur OpenTelemetry pour envoyer des métriques à des systèmes de supervision externes
   

Prerequisites

• GitHub Enterprise Server 3.18 ou version ultérieure avec les métriques OpenTelemetry activées
• Connectivité réseau entre vos GitHub Enterprise Server instance et systèmes de supervision externes
• Accès administratif à la fois à votre instance GitHub Enterprise Server et aux systèmes de surveillance

Choix de votre approche de supervision

Choisissez l’approche de supervision qui convient le mieux à votre infrastructure et à vos besoins.

Point de terminaison Prometheus (recommandé pour la plupart des utilisateurs)

Utilisez le point de terminaison Prometheus quand :

• Vous disposez d’une infrastructure de supervision basée sur Prometheus existante
• Vous préférez un modèle de surveillance basé sur l'extraction (pull)
• Vous souhaitez utiliser des outils externes pour extraire des métriques de GitHub Enterprise Server.
• Vous avez besoin d’une intégration simple avec une configuration minimale

Pipelines OpenTelemetry personnalisés

Utilisez des pipelines OpenTelemetry personnalisés quand :

• Vous devez envoyer des métriques à plusieurs systèmes de surveillance simultanément
• Vous souhaitez transformer, filtrer ou agréger des métriques avant de les envoyer en externe
• Vous utilisez des solutions de surveillance natifs du cloud qui préfèrent OTLP
• Vous avez besoin de fonctionnalités avancées de traitement des métriques

Option 1 : Utilisation du point de terminaison Prometheus

La pile de surveillance OpenTelemetry inclut un point de terminaison compatible Prometheus qui expose toutes les métriques collectées au format Prometheus, ce qui permet l’intégration à des outils de supervision externes. Consultez le format textuel dans la documentation relative à Prometheus.

Activation du point de terminaison Prometheus

Vous pouvez activer le point de terminaison Prometheus à l'aide soit du Management Console, soit de l'interface en ligne de commande.

Utilisation de la console de gestion

1. À partir d’un compte d’administration sur GitHub Enterprise Server, cliquez sur en haut à droite de n’importe quelle page.

2. Si vous ne figurez pas déjà sur la page « Administrateur du site », dans le coin supérieur gauche, cliquez sur Administrateur du site.

3. Dans la barre latérale « Site admin », cliquez sur Management Console.

4. Dans les paramètres de surveillance, sélectionnez Activer OpenTelemetry.

5. Si vous le souhaitez, ajustez les champs de rétention des métriques et d’intervalle de collecte pour optimiser les performances.

6. Sélectionnez Activer le point de terminaison compatible Prometheus (/metrics).

7. Dans le champ Mot de passe du point de terminaison , entrez un mot de passe fort pour contrôler l’accès au point de terminaison.

8. Si vous le souhaitez, dans les adresses IPv4/IPv6 approuvées ou les blocs CIDR dans un champ de liste séparés par des virgules , entrez les adresses IP ou les blocs CIDR autorisés à accéder au point de terminaison.

9. Sous la barre latérale « Paramètres », cliquez sur Enregistrer les paramètres.

   Remarque

   L’enregistrement des paramètres dans la Management Console redémarre les services système, ce qui peut entraîner un temps d’arrêt visible pour l’utilisateur.

10. Attendez la fin de l’exécution de la configuration.

Utilisation de l’interface de ligne de commande

1. Connectez-vous via SSH à votre instance GitHub Enterprise Server.

2. Activez le point de terminaison Prometheus :

   ghe-config observability.metrics.prometheus-endpoint-enabled true
   ghe-config-apply
   

3. Configurer l’authentification pour le point de terminaison (fortement recommandé) :

   ghe-config observability.metrics.prometheus-endpoint-password your-secure-password
   ghe-config-apply
   

Accès au point de terminaison Prometheus

Le point de terminaison Prometheus sera disponible à l’adresse suivante :

https://[hostname]:8010/metrics

L’authentification utilise :

•         **Nom d'utilisateur** : `ghes-metrics`
  

•         **Mot de passe** : valeur définie dans votre configuration
  

Configuration d’outils externes pour supprimer des métriques

Vous pouvez configurer différents outils de supervision externe pour récupérer des métriques à partir du point de terminaison Prometheus.

Prometheus

Ajoutez la configuration de travail suivante à votre fichier de configuration Prometheus :

scrape_configs:
  - job_name: 'github-enterprise-server'
    static_configs:
      - targets: ['your-ghes-hostname:8010']
    basic_auth:
      username: 'ghes-metrics'
      password: 'your-secure-password'
    scrape_interval: 30s
    metrics_path: '/metrics'
    scheme: https
    tls_config:
      # Set `true` only when testing with self-signed certificates
      insecure_skip_verify: false

Autres outils de supervision

Le point de terminaison Prometheus est compatible avec n’importe quel outil de surveillance qui peut récupérer les métriques au format Prometheus, notamment :

• Grafana (à l’aide de la source de données Prometheus)
• Datadog (à l’aide de prometheus check)
• New Relic (à l’aide de l’intégration Prometheus)
• Métriques Victoria
• InfluxDB (à l’aide du plug-in d’entrée Prometheus)

Considérations relatives à la sécurité pour le point de terminaison Prometheus

Des mesures de sécurité supplémentaires peuvent être implémentées pour protéger votre point de terminaison de métriques.

Protection par mot de passe

Le point de terminaison Prometheus prend en charge l’utilisation d’un mot de passe pour limiter l’accès. Vous pouvez configurer cela soit via le Management Console, soit via l'interface en ligne de commande.

•         **Utilisation de la console de gestion** :
  

  Dans les paramètres de surveillance, utilisez le champ Mot de passe du point de terminaison pour entrer un mot de passe fort pour contrôler l’accès au point de terminaison.

•         **Utilisation de l’interface de ligne de commande** :
  

  ghe-config observability.metrics.prometheus-endpoint-password your-secure-password
  ghe-config-apply
  

Liste d'adresses IP autorisées

Le point de terminaison Prometheus prend en charge la liste d’autorisation IP pour une sécurité renforcée. Vous pouvez configurer cela soit via le Management Console, soit via l'interface en ligne de commande.

•         **Utilisation de la console de gestion** :
  

  Dans les paramètres de surveillance, utilisez les adresses IPv4/IPv6 approuvées ou les blocs CIDR dans un champ de liste séparés par des virgules pour entrer des adresses IP ou des blocs CIDR qui doivent avoir accès au point de terminaison.

•         **Utilisation de l’interface de ligne de commande** :
  

  ghe-config observability.metrics.prometheus-endpoint-trusted-ips "10.0.0.0/8,192.168.0.0/16"
  ghe-config-apply
  

Test de l'endpoint

Vérifiez que les métriques sont exportées :

# Test the Prometheus endpoint
curl -u ghes-metrics:your-password https://your-ghes-hostname:8010/metrics

Option 2 : Utilisation de pipelines OpenTelemetry personnalisés

GitHub Enterprise Server prend en charge les configurations de collecteur OpenTelemetry personnalisées, ce qui vous permet d’étendre les fonctionnalités de surveillance en ajoutant des pipelines personnalisés, des exportateurs et des processeurs. Cela vous permet d’expédier des métriques à des systèmes de surveillance externes tout en conservant la pile d’observabilité GitHub Enterprise Server par défaut.

Considérations importantes relatives aux configurations personnalisées

• Les configurations personnalisées sont additionnelles à la configuration par défaut GitHub Enterprise Server OpenTelemetry.

•         **Chemins réservés : les chemins** d’accès `/ghes` et `/internal` sont réservés à GitHub Enterprise Server utilisation interne et ne doivent pas être utilisés dans les fichiers de configuration personnalisés
  

•         `otlp/ghes` et `prometheus/ghes` les récepteurs sont les sources intégrées de GitHub Enterprise Server métriques que vous pouvez utiliser dans vos pipelines personnalisés
  

• Testez soigneusement votre configuration dans un environnement hors production avant de l’appliquer à la production
• Surveiller l’utilisation des ressources après l’activation des configurations personnalisées, car des pipelines supplémentaires peuvent augmenter la consommation du processeur et de la mémoire

Activation de la configuration OpenTelemetry personnalisée

Vous pouvez activer une configuration OpenTelemetry personnalisée à l'aide soit de la Management Console, soit de l'interface en ligne de commande.

Utilisation de la console de gestion

1. À partir d’un compte d’administration sur GitHub Enterprise Server, cliquez sur en haut à droite de n’importe quelle page.

2. Si vous ne figurez pas déjà sur la page « Administrateur du site », dans le coin supérieur gauche, cliquez sur Administrateur du site.

3. Dans la barre latérale « Site admin », cliquez sur Management Console.

4. Dans les paramètres de surveillance, sélectionnez d’abord Activer OpenTelemetry.

5. Sélectionnez Activer les pipelines de collecteur OpenTelemetry personnalisés.

6. Utilisez le bouton Parcourir... pour charger votre fichier de configuration du collecteur OpenTelemetry personnalisé (*.yml), consultez Exemples de configurations pour les systèmes de surveillance populaires.

7. Sous la barre latérale « Paramètres », cliquez sur Enregistrer les paramètres.

   Remarque

   L’enregistrement des paramètres dans la Management Console redémarre les services système, ce qui peut entraîner un temps d’arrêt visible pour l’utilisateur.

8. Attendez la fin de l’exécution de la configuration.

À partir de la ligne de commande

1. Connectez-vous via SSH à votre instance GitHub Enterprise Server et exécutez la commande suivante.

   ghe-config observability.metrics.custom-config-enabled true
   

2. Créez votre fichier de configuration OpenTelemetry personnalisé à l’adresse /data/user/common/otelcol.yamlsuivante :

   sudo nano /data/user/common/otelcol.yaml
   

3. Ajoutez votre configuration personnalisée (consultez Exemples de configurations pour les systèmes de surveillance populaires).

4. Appliquez la configuration :

   ghe-config-apply
   

Exemples de configurations pour les systèmes de surveillance populaires

Les exemples suivants montrent comment configurer des pipelines OpenTelemetry personnalisés pour les plateformes de surveillance populaires. Pour plus d’informations sur d’autres exportateurs ou pour créer votre propre fichier, consultez le référentiel des collecteurs OpenTelemetry.

Cloud Grafana

---
exporters:
  prometheusremotewrite:
    endpoint: "https://prometheus-us-central1.grafana.net/api/prom/push"
    headers:
      Authorization: "Bearer your-grafana-cloud-token"

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [prometheusremotewrite]

Datadog

---
exporters:
  datadog:
    api:
      site: datadoghq.com
      key: your-datadog-api-key
    host_metadata:
      enabled: true

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [datadog]

New Relic

---
exporters:
  otlp:
    endpoint: "https://otlp.nr-data.net:4317"
    headers:
      api-key: "your-new-relic-license-key"

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [otlp]

Point de terminaison OTLP générique

---
exporters:
  otlp:
    endpoint: "https://your-otel-collector:4317"
    headers:
      api-key: "your-api-key"
    tls:
      insecure: false

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [otlp]

Considérations relatives au réseau et à la sécurité

Configurez vos paramètres de réseau et de sécurité en fonction de votre approche de supervision choisie.

TLS et certificats

Pour des connexions sécurisées à des systèmes de supervision externes :

• Utiliser des certificats TLS valides lorsque cela est possible
• Configurer les paramètres appropriés tls_config dans votre système de surveillance
• Envisagez d’utiliser le protocole TLS mutuel (mTLS) pour renforcer la sécurité

Étapes suivantes

• Pour configurer les paramètres OpenTelemetry, consultez Configuration d’OpenTelemetry pour votre instance.
• Pour en savoir plus sur les métriques disponibles, consultez À propos des métriques OpenTelemetry.