Condividi tramite


Configurare metriche locali e log locali per il gateway self-hosted di Gestione API di Azure

SI APPLICA A: Sviluppatore | Premium

Questo articolo fornisce informazioni dettagliate sulla configurazione delle metriche e dei log locali per il gateway self-hosted in un cluster Kubernetes. Per la configurazione di metriche e log del cloud, vedere questo articolo.

Metrica

Il gateway self-hosted supporta StatsD, che è diventato un protocollo unificatore per la raccolta e l'aggregazione delle metriche. Questa sezione illustra i passaggi per la distribuzione di StatsD in Kubernetes, la configurazione del gateway per generare metriche tramite StatsD e l'uso di Prometheus per monitorare le metriche.

Distribuire StatsD e Prometheus nel cluster

Di seguito è riportata una configurazione YAML di esempio per la distribuzione di StatsD e Prometheus nel cluster Kubernetes in cui viene distribuito un gateway self-hosted. Crea anche un Servizio per ognuno di essi. Il gateway self-hosted pubblica poi le metriche nel servizio StatsD. Si accederà al dashboard di Prometheus tramite il relativo servizio.

Nota

L'esempio seguente esegue il pull delle immagini del contenitore pubblico da Docker Hub. È consigliabile configurare un segreto pull per l'autenticazione usando un account di Docker Hub anziché effettuare una richiesta pull anonima. Per migliorare l'affidabilità quando si lavora con contenuto pubblico, importare e gestire l'immagine in un registro Azure Container privato. Altre informazioni sull'uso delle immagini pubbliche.

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

Salvare le configurazioni in un file denominato metrics.yaml. Usare il comando seguente per distribuire tutto nel cluster:

kubectl apply -f metrics.yaml

Al termine della distribuzione, eseguire il comando seguente per verificare che i pod siano in esecuzione. Il nome del pod sarà diverso.

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

Eseguire il comando seguente per verificare che services siano in esecuzione. Prendere nota di CLUSTER-IP e PORT del servizio StatsD, che saranno necessari in un secondo momento. È possibile visitare il dashboard di Prometheus usando i relativi EXTERNAL-IP e 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

Configurare il gateway self-hosted per generare le metriche

Ora che StatsD e Prometheus sono stati distribuiti, è possibile aggiornare le configurazioni del gateway self-hosted per iniziare a generare metriche tramite StatsD. La funzionalità può essere abilitata o disabilitata usando la chiave telemetry.metrics.local in ConfigMap della distribuzione del gateway self-hosted con opzioni aggiuntive. Di seguito sono riportate le opzioni disponibili.

Campo Default Descrizione
telemetry.metrics.local none Abilita la registrazione tramite StatsD. Il valore può essere none, statsd.
telemetry.metrics.local.statsd.endpoint n/d Specifica l'endpoint StatsD.
telemetry.metrics.local.statsd.sampling n/d Specifica la frequenza di campionamento delle metriche. Il valore può essere compreso tra 0 e 1. Esempio: 0.5
telemetry.metrics.local.statsd.tag-format n/d L'utilità di esportazione StatsD formato di assegnazione di tag. Il valore può essere none, librato, dogStatsD, influxDB.

Ecco una configurazione di esempio:

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"

Aggiornare il file YAML della distribuzione del gateway self-hosted con le configurazioni precedenti e applicare le modifiche usando il comando seguente:

kubectl apply -f <file-name>.yaml

Per selezionare le modifiche di configurazione più recenti, riavviare la distribuzione del gateway usando il comando seguente:

kubectl rollout restart deployment/<deployment-name>

Visualizzare le metriche

Ora che sono stati distribuiti e configurati tutti gli elementi, il gateway self-hosted deve segnalare le metriche tramite StatsD. Prometheus rileva quindi le metriche da StatsD. Passare al dashboard di Prometheus usando il EXTERNAL-IP e PORT del servizio Prometheus.

Effettuare alcune chiamate API tramite il gateway self-hosted, se tutto è configurato correttamente, dovrebbe essere possibile visualizzare le metriche seguenti:

Metrico Descrizione
requests_total Numero di richieste API nel periodo
request_duration_seconds Numero di millisecondi dal momento in cui il gateway ha ricevuto la richiesta al momento dell'invio della risposta completa
request_backend_duration_seconds Numero di millisecondi impiegati complessivamente per le operazioni di I/O del back-end (connessione, invio e ricezione byte)
request_client_duration_seconds Numero di millisecondi impiegati complessivamente per l'I/O del client (connessione, invio e ricezione byte)

Registri

Il gateway self-hosted restituisce i log per stdout e stderr per impostazione predefinita. È possibile visualizzare facilmente i log usando il comando seguente:

kubectl logs <pod-name>

Se il gateway self-hosted viene distribuito nel servizio Azure Kubernetes, è possibile abilitare Monitoraggio di Azure per contenitori per raccogliere stdout e stderr dai carichi di lavoro e visualizzare i log in Log Analytics.

Il gateway self-hosted supporta anche diversi protocolli, tra cui localsyslog, rfc5424 e journal. La tabella seguente riepiloga tutte le opzioni supportate.

Campo Default Descrizione
telemetry.logs.std text Consente la registrazione a flussi standard. Il valore può essere none, text, json
telemetry.logs.local auto Abilita la registrazione locale. Il valore può essere none, auto, localsyslog, rfc5424, journal, json
telemetry.logs.local.localsyslog.endpoint n/d Specifica l'endpoint syslog locale. Per informazioni dettagliate, vedere usare i log syslog locali.
telemetry.logs.local.localsyslog.facility n/d Specifica il codice della struttura syslog locale. Esempio: 7
telemetry.logs.local.rfc5424.endpoint n/d Specifica l'endpoint rfc5424.
telemetry.logs.local.rfc5424.facility n/d Specifica il codice della struttura per rfc5424. Esempio: 7
telemetry.logs.local.journal.endpoint n/d Specifica l'endpoint del journal.
telemetry.logs.local.json.endpoint 127.0.0.1:8888 Specifica l'endpoint UDP che accetta i dati JSON: percorso del file, IP:porta o nome host:port.

Ecco una configurazione di esempio della registrazione 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"

Uso dell'endpoint JSON locale

Limitazioni note

  • Sono supportati solo un massimo di 3072 byte di payload di richiesta/risposta per la diagnostica locale. Un numero superiore di byte potrebbe causare l'interruzione del formato JSON a causa della suddivisione in blocchi.

Uso dei log syslog locali

Configurazione del gateway per lo streaming dei log

Quando si usa syslog locale come destinazione per i log, il runtime deve consentire i log di streaming alla destinazione. Per Kubernetes, è necessario montare un volume che corrisponde alla destinazione.

Data la seguente configurazione:

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

È possibile avviare facilmente lo streaming dei log in tale endpoint syslog locale:

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

Consumo dei log syslog locali nel servizio Azure Kubernetes (AKS)

Quando si configura l'uso di syslog locale nel servizio Azure Kubernetes, è possibile scegliere due modi per esplorare i log:

Utilizzo dei log dai nodi di lavoro

È possibile usarli facilmente ottenendo l'accesso ai nodi di lavoro:

  1. Creare una connessione SSH al nodo (documentazione)
  2. I log sono disponibili in host/var/log/syslog

Ad esempio, è possibile filtrare tutti i syslog in base a quelli dal gateway self-hosted:

$ 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=b28565ec-73e0-41e6-9312-efcdd6841846, 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=ab4d7464-acee-40ae-af95-a521cc57c759, 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"

Nota

Se la radice è stata modificata con chroot, ad esempio chroot /host, il percorso precedente deve riflettere tale modifica.

Passaggi successivi