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:
- Usare la raccolta Syslog con Container Insights
- Connettersi ed esplorare i log nei nodi di lavoro
Utilizzo dei log dai nodi di lavoro
È possibile usarli facilmente ottenendo l'accesso ai nodi di lavoro:
- Creare una connessione SSH al nodo (documentazione)
- 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
- Leggere le informazioni sulle funzionalità di osservabilità dei gateway di Gestione API di Azure.
- Ulteriori informazioni sul gateway self-hosted di API Management di Azure.
- Informazioni sulla configurazione e la persistenza dei log nel cloud.