Configurer des métriques et journaux locaux pour la passerelle auto-hébergée de Gestion des API Azure

Article
04/17/2024

S’APPLIQUE À : Développeur | Premium

Cet article fournit des informations détaillées sur la configuration des métriques et journaux locaux pour la passerelle auto-hébergée déployée sur un cluster Kubernetes. Pour configurer les journaux et métriques cloud, consultez cet article.

Métriques

La passerelle auto-hébergée prend en charge StatsD, qui est devenu un protocole unifiant pour la collecte et l’agrégation des métriques. Cette section décrit les étapes de déploiement de StatsD sur Kubernetes, de configuration de la passerelle pour émettre des métriques via StatsD, et d’utilisation de Prometheus pour surveiller les métriques.

Déployer StatsD et Prometheus sur le cluster

L’exemple de configuration YAML suivant déploie StatsD et Prometheus sur le cluster Kubernetes sur lequel une passerelle auto-hébergée est déployée. Il crée également un Service pour chaque service. La passerelle auto-hébergée publie ensuite des métriques sur le service StatsD. Nous allons accéder au tableau de bord de Prometheus via son service.

Remarque

L’exemple suivant tire (pull) des images conteneurs publiques à partir de Docker Hub. Nous vous recommandons de configurer un secret d’extraction pour l’authentification à l’aide d’un compte Docker Hub au lieu de créer une demande de tirage anonyme. Pour une plus grande fiabilité lors de l’utilisation de contenu public, importez et gérez les images dans un registre de conteneurs Azure privé. En savoir plus sur l’utilisation des images publiques.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sputnik-metrics-config
data:
  statsd.yaml: ""
  prometheus.yaml: |
    global:
      scrape_interval:     3s
      evaluation_interval: 3s
    scrape_configs:
      - job_name: 'prometheus'
        static_configs:
          - targets: ['localhost:9090']
      - job_name: 'test_metrics'
        static_configs:
          - targets: ['localhost:9102']
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sputnik-metrics
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sputnik-metrics
  template:
    metadata:
      labels:
        app: sputnik-metrics
    spec:
      containers:
      - name: sputnik-metrics-statsd
        image: prom/statsd-exporter
        ports:
        - name: tcp
          containerPort: 9102
        - name: udp
          containerPort: 8125
          protocol: UDP
        args:
          - --statsd.mapping-config=/tmp/statsd.yaml
          - --statsd.listen-udp=:8125
          - --web.listen-address=:9102
        volumeMounts:
          - mountPath: /tmp
            name: sputnik-metrics-config-files
      - name: sputnik-metrics-prometheus
        image: prom/prometheus
        ports:
        - name: tcp
          containerPort: 9090
        args:
          - --config.file=/tmp/prometheus.yaml
        volumeMounts:
          - mountPath: /tmp
            name: sputnik-metrics-config-files
      volumes:
        - name: sputnik-metrics-config-files
          configMap:
            name: sputnik-metrics-config
---
apiVersion: v1
kind: Service
metadata:
  name: sputnik-metrics-statsd
spec:
  type: NodePort
  ports:
  - name: udp
    port: 8125
    targetPort: 8125
    protocol: UDP
  selector:
    app: sputnik-metrics
---
apiVersion: v1
kind: Service
metadata:
  name: sputnik-metrics-prometheus
spec:
  type: LoadBalancer
  ports:
  - name: http
    port: 9090
    targetPort: 9090
  selector:
    app: sputnik-metrics

Enregistrez les configurations dans un fichier nommé metrics.yaml. Utilisez la commande suivante pour tout déployer sur le cluster :

kubectl apply -f metrics.yaml

Une fois le déploiement terminé, exécutez la commande suivante pour vérifier que les pods sont en cours d’exécution. Le nom de votre pod sera différent.

kubectl get pods
NAME                                   READY   STATUS    RESTARTS   AGE
sputnik-metrics-f6d97548f-4xnb7        2/2     Running   0          1m

Exécutez la commande ci-dessous pour vérifier que les services sont en cours d’exécution. Prenez note du CLUSTER-IP et du PORT du service StatsD, car nous les utiliserons plus tard. Vous pouvez visiter le tableau de bord Prometheus en utilisant son EXTERNAL-IP et son PORT.

kubectl get services
NAME                         TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                      AGE
sputnik-metrics-prometheus   LoadBalancer   10.0.252.72   13.89.141.90    9090:32663/TCP               18h
sputnik-metrics-statsd       NodePort       10.0.41.179   <none>          8125:32733/UDP               18h

Configurer la passerelle auto-hébergée pour émettre des métriques

Maintenant que StatsD et Prometheus sont déployés, nous pouvons mettre à jour les configurations de la passerelle auto-hébergée pour commencer à émettre des métriques via StatsD. Vous pouvez activer ou désactiver la fonctionnalité en utilisant la clé telemetry.metrics.local dans le fichier Configmap du déploiement de la passerelle auto-hébergée avec des options supplémentaires. Les options disponibles sont les suivantes :

Champ	Default	Description
telemetry.metrics.local	`none`	Active la journalisation via StatsD. La valeur peut être `none` ou `statsd`.
telemetry.metrics.local.statsd.endpoint	n/a	Spécifie le point de terminaison de StatsD.
telemetry.metrics.local.statsd.sampling	n/a	Spécifie le taux d’échantillonnage des métriques. La valeur peut être comprise entre 0 et 1. Exemple : `0.5`
telemetry.metrics.local.statsd.tag-format	n/a	Format d’étiquetage de l’exportateur StatsD. La valeur peut être `none`, `librato`, `dogStatsD` ou `influxDB`.

Voici un exemple de configuration :

apiVersion: v1
kind: ConfigMap
metadata:
    name: contoso-gateway-environment
data:
    config.service.endpoint: "<self-hosted-gateway-management-endpoint>"
    telemetry.metrics.local: "statsd"
    telemetry.metrics.local.statsd.endpoint: "10.0.41.179:8125"
    telemetry.metrics.local.statsd.sampling: "1"
    telemetry.metrics.local.statsd.tag-format: "dogStatsD"

Mettez à jour le fichier YAML du déploiement de la passerelle auto-hébergée avec les configurations ci-dessus, et appliquez les modifications à l’aide de la commande ci-dessous :

kubectl apply -f <file-name>.yaml

Pour prélever les dernières modifications de configuration, redémarrez le déploiement de la passerelle à l’aide de la commande ci-dessous :

kubectl rollout restart deployment/<deployment-name>

Afficher les métriques

À présent que tout est déployé et configuré, la passerelle auto-hébergée doit signaler les métriques via StatsD. Prometheus récupère ensuite les métriques de StatsD. Accédez au tableau de bord Prometheus en utilisant les valeurs EXTERNAL-IP et PORT du service Prometheus.

Effectuez quelques appels d’API via la passerelle auto-hébergée. Si tout est bien configuré, vous devez être en mesure d’afficher les métriques ci-dessous :

Métrique	Description
requests_total	Nombre de demandes API au cours de la période
request_duration_seconds	Nombre de millisecondes entre le moment où la passerelle a reçu la requête et celui où la réponse complète a été envoyée
request_backend_duration_seconds	Nombre de millisecondes consacrées à l’ensemble des E/S du back-end (connexion, envoi et réception d’octets)
request_client_duration_seconds	Nombre de millisecondes consacrées à l’ensemble des E/S du client (connexion, envoi et réception d’octets)

Journaux d’activité

La passerelle auto-hébergée génère des journaux dans stdout et stderr par défaut. Vous pouvez facilement afficher les journaux à l’aide de la commande suivante :

kubectl logs <pod-name>

Si votre passerelle auto-hébergée est déployée dans Azure Kubernetes Service, vous pouvez activer Azure Monitor pour conteneurs afin de collecter stdout et stderr à partir de vos charges de travail et d’afficher les journaux dans Log Analytics.

La passerelle auto-hébergée prend également en charge de nombreux protocoles, notamment localsyslog, rfc5424 et journal. Le tableau suivant récapitule toutes les options prises en charge.

Champ	Default	Description
telemetry.logs.std	`text`	Active la journalisation dans des flux standard. La valeur peut être `none`, `text` ou `json`.
telemetry.logs.local	`auto`	Active la journalisation locale. La valeur peut être `none`, `auto`, `localsyslog`, `rfc5424`, `journal`, `json`
telemetry.logs.local.localsyslog.endpoint	n/a	Spécifie le point de terminaison du syslog local. Pour plus de détails, consultez la section Utilisation des journaux syslog locaux.
telemetry.logs.local.localsyslog.facility	n/a	Spécifie le code de catégorie du syslog local. Exemple : `7`
telemetry.logs.local.rfc5424.endpoint	n/a	Spécifie le point de terminaison de rfc5424.
telemetry.logs.local.rfc5424.facility	n/a	Spécifie le code de facilité par rfc5424. Exemple : `7`
telemetry.logs.local.journal.endpoint	n/a	Spécifie le point de terminaison du journal.
telemetry.logs.local.json.endpoint	127.0.0.1:8888	Spécifie le point de terminaison UDP qui accepte les données JSON : chemin de fichier, adresse IP : port ou nom d’hôte : port.

Voici un exemple de configuration de journalisation locale :

    apiVersion: v1
    kind: ConfigMap
    metadata:
        name: contoso-gateway-environment
    data:
        config.service.endpoint: "<self-hosted-gateway-management-endpoint>"
        telemetry.logs.std: "text"
        telemetry.logs.local.localsyslog.endpoint: "/dev/log"
        telemetry.logs.local.localsyslog.facility: "7"

Utilisation du point de terminaison JSON local

Limitations connues

Nous prenons uniquement en charge jusqu’à 3072 octets de charge utile de requête/réponse pour les diagnostics locaux. Tout ce qui précède peut interrompre le format JSON en raison d’une segmentation.

Utilisation des journaux syslog locaux

Configuration de la passerelle pour diffuser en continu les journaux

Lorsque vous utilisez le syslog local comme destination pour les journaux, le runtime doit autoriser la diffusion en continu des journaux vers la destination. Pour Kubernetes, un volume correspondant à la destination doit être monté.

Étant donné la configuration suivante :

apiVersion: v1
kind: ConfigMap
metadata:
    name: contoso-gateway-environment
data:
    config.service.endpoint: "<self-hosted-gateway-management-endpoint>"
    telemetry.logs.local: localsyslog
    telemetry.logs.local.localsyslog.endpoint: /dev/log

Vous pouvez facilement commencer à diffuser en continu les journaux vers ce point de terminaison syslog local :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: contoso-deployment
  labels:
    app: contoso
spec:
  replicas: 1
  selector:
    matchLabels:
      app: contoso
  template:
    metadata:
      labels:
        app: contoso
    spec:
      containers:
        name: azure-api-management-gateway
        image: mcr.microsoft.com/azure-api-management/gateway:2.5.0
        imagePullPolicy: IfNotPresent
        envFrom:
        - configMapRef:
            name: contoso-gateway-environment
        # ... redacted ...
+       volumeMounts:
+       - mountPath: /dev/log
+         name: logs
+     volumes:
+     - hostPath:
+         path: /dev/log
+         type: Socket
+       name: logs

Consommation des journaux syslog locaux sur Azure Kubernetes Service (AKS)

Lorsque vous configurez l’utilisation du syslog local sur Azure Kubernetes Service, vous pouvez explorer les journaux de deux façons :

Utiliser la Collecte de Syslog avec Container Insights
Connecter et explorer les journaux d’activité sur les nœuds Worker

Consommation des journaux d’activité à partir des nœuds Worker

Vous pouvez facilement les consommer en accédant aux nœuds Worker :

Créer une connexion SSH au nœud (docs)
Les journaux sont accessibles sous host/var/log/syslog

Par exemple, vous pouvez filtrer tous les syslogs pour ne retenir que ceux provenant de la passerelle autohébergée :

$ cat host/var/log/syslog | grep "apimuser"
May 15 05:54:20 aks-agentpool-43853532-vmss000000 apimuser[8]: Timestamp=2023-05-15T05:54:20.0445178Z, isRequestSuccess=True, totalTime=290, category=GatewayLogs, callerIpAddress=141.134.132.243, timeGenerated=2023-05-15T05:54:20.0445178Z, region=Repro, correlationId=aaaa0000-bb11-2222-33cc-444444dddddd, method=GET, url="http://20.126.242.200/echo/resource?param1\=sample", backendResponseCode=200, responseCode=200, responseSize=628, cache=none, backendTime=287, apiId=echo-api, operationId=retrieve-resource, apimSubscriptionId=master, clientProtocol=HTTP/1.1, backendProtocol=HTTP/1.1, apiRevision=1, backendMethod=GET, backendUrl="http://echoapi.cloudapp.net/api/resource?param1\=sample"
May 15 05:54:21 aks-agentpool-43853532-vmss000000 apimuser[8]: Timestamp=2023-05-15T05:54:21.1189171Z, isRequestSuccess=True, totalTime=150, category=GatewayLogs, callerIpAddress=141.134.132.243, timeGenerated=2023-05-15T05:54:21.1189171Z, region=Repro, correlationId=bbbb1111-cc22-3333-44dd-555555eeeeee, method=GET, url="http://20.126.242.200/echo/resource?param1\=sample", backendResponseCode=200, responseCode=200, responseSize=628, cache=none, backendTime=148, apiId=echo-api, operationId=retrieve-resource, apimSubscriptionId=master, clientProtocol=HTTP/1.1, backendProtocol=HTTP/1.1, apiRevision=1, backendMethod=GET, backendUrl="http://echoapi.cloudapp.net/api/resource?param1\=sample"

Notes

Si vous avez modifié la racine avec chroot, par exemple chroot /host, le chemin d’accès ci-dessus doit refléter cette modification.

Étapes suivantes

Apprenez-en davantage sur les fonctionnalités d’observabilité des passerelles de Gestion des API Azure.
Obtenez plus d’informations sur la passerelle auto-hébergée de Gestion des API Azure.
Découvrez la configuration et la persistance des journaux dans le cloud.

Partager via