Configurar métricas e logs locais para o gateway auto-hospedado do Gerenciamento de API do Azure
APLICA-SE A: Developer | Prémio
Este artigo fornece detalhes para configurar métricas e logs locais para o gateway auto-hospedado implantado em um cluster Kubernetes. Para configurar métricas e logs na nuvem, consulte este artigo.
Métricas
O gateway auto-hospedado suporta StatsD, que se tornou um protocolo unificador para coleta e agregação de métricas. Esta seção apresenta as etapas para implantar o StatsD no Kubernetes, configurar o gateway para emitir métricas via StatsD e usar o Prometheus para monitorar as métricas.
Implantar o StatsD e o Prometheus no cluster
O exemplo de configuração YAML a seguir implanta o StatsD e o Prometheus no cluster do Kubernetes onde um gateway auto-hospedado é implantado. Também cria um Serviço para cada um. Em seguida, o gateway auto-hospedado publica métricas no Serviço StatsD. Acedemos ao painel Prometheus através do seu Serviço.
Nota
O exemplo a seguir extrai imagens de contêiner público do Docker Hub. Recomendamos que você configure um segredo de pull para autenticar usando uma conta do Docker Hub em vez de fazer uma solicitação pull anônima. Para melhorar a confiabilidade ao trabalhar com conteúdo público, importe e gerencie as imagens em um registro de contêiner privado do Azure. Saiba mais sobre como trabalhar com imagens públicas.
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
Salve as configurações em um arquivo chamado metrics.yaml. Use o seguinte comando para implantar tudo no cluster:
kubectl apply -f metrics.yaml
Quando a implantação terminar, execute o seguinte comando para verificar se os Pods estão em execução. O nome do seu pod será diferente.
kubectl get pods
NAME READY STATUS RESTARTS AGE
sputnik-metrics-f6d97548f-4xnb7 2/2 Running 0 1m
Execute o comando abaixo para verificar se estão services em execução. Tome nota do CLUSTER-IP e PORT do Serviço StatsD, que usamos mais tarde. Pode visitar o painel Prometheus utilizando o seu 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
Configurar o gateway auto-hospedado para emitir métricas
Agora que o StatsD e o Prometheus estão implantados, podemos atualizar as configurações do gateway auto-hospedado para começar a emitir métricas por meio do StatsD. O recurso pode ser habilitado ou desabilitado usando a telemetry.metrics.local chave no ConfigMap da implantação do gateway auto-hospedado com opções adicionais. A seguir estão as opções disponíveis:
| Campo | Predefinido | Description |
|---|---|---|
| telemetry.metrics.local | none |
Permite o registo através de StatsD. O valor pode ser none, statsd. |
| telemetry.metrics.local.statsd.endpoint | n/d | Especifica o ponto de extremidade StatsD. |
| telemetry.metrics.local.statsd.sampling | n/d | Especifica a taxa de amostragem de métricas. O valor pode estar entre 0 e 1. Exemplo: 0.5 |
| telemetry.metrics.local.statsd.tag-format | n/d | Formato de etiquetagem do exportador StatsD. O valor pode ser none, librato, dogStatsD, influxDB. |
Aqui está um exemplo de configuração:
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"
Atualize o arquivo YAML da implantação de gateway auto-hospedado com as configurações acima e aplique as alterações usando o comando abaixo:
kubectl apply -f <file-name>.yaml
Para obter as alterações de configuração mais recentes, reinicie a implantação do gateway usando o comando abaixo:
kubectl rollout restart deployment/<deployment-name>
Veja as métricas
Agora que temos tudo implantado e configurado, o gateway auto-hospedado deve relatar métricas via StatsD. Prometheus então pega as métricas do StatsD. Vá para o painel do Prometheus usando o EXTERNAL-IP e PORT do Serviço Prometheus.
Faça algumas chamadas de API através do gateway auto-hospedado, se tudo estiver configurado corretamente, você poderá visualizar as métricas abaixo:
| Métrico | Description |
|---|---|
| requests_total | Número de solicitações de API no período |
| request_duration_seconds | Número de milissegundos a partir do momento em que o gateway recebeu o pedido até ao momento em que a resposta é enviada integralmente |
| request_backend_duration_seconds | Número de milissegundos gastos em E/S de back-end geral (conexão, envio e recebimento de bytes) |
| request_client_duration_seconds | Número de milissegundos gastos na E/S geral do cliente (conexão, envio e recebimento de bytes) |
Registos
O gateway auto-hospedado gera logs de saída para stdout e stderr por padrão. Você pode visualizar facilmente os logs usando o seguinte comando:
kubectl logs <pod-name>
Se seu gateway auto-hospedado for implantado no Serviço Kubernetes do Azure, você poderá habilitar o Azure Monitor para contêineres para coletar stdout e stderr de suas cargas de trabalho e exibir os logs no Log Analytics.
O gateway auto-hospedado também suporta muitos protocolos, incluindo localsyslog, rfc5424e journal. A tabela a seguir resume todas as opções suportadas.
| Campo | Predefinido | Description |
|---|---|---|
| telemetria.logs.std | text |
Permite o registro em fluxos padrão. O valor pode ser none, text, json |
| telemetry.logs.local | auto |
Permite o registro em log local. O valor pode ser none, auto, , localsyslog, rfc5424journal,json |
| telemetry.logs.local.localsyslog.endpoint | n/d | Especifica o ponto de extremidade syslog local. Para obter detalhes, consulte Usando logs syslog locais. |
| telemetry.logs.local.localsyslog.facility | n/d | Especifica o código do recurso syslog local. Exemplo: 7 |
| telemetry.logs.local.rfc5424.endpoint | n/d | Especifica o ponto de extremidade rfc5424. |
| telemetry.logs.local.rfc5424.facility | n/d | Especifica o código do recurso por rfc5424. Exemplo: 7 |
| telemetry.logs.local.journal.endpoint | n/d | Especifica o ponto de extremidade do diário. |
| telemetry.logs.local.json.Ponto final | 127.0.0.1:8888 | Especifica o ponto de extremidade UDP que aceita dados JSON: caminho do arquivo, IP:port ou hostname:port. |
Aqui está um exemplo de configuração de log local:
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"
Usando o ponto de extremidade JSON local
Limitações conhecidas
- Suportamos apenas até 3072 bytes de carga útil de solicitação/resposta para diagnósticos locais. Qualquer coisa acima, pode quebrar o formato JSON devido ao chunking.
Usando logs syslog locais
Configurando o gateway para transmitir logs
Ao usar syslog local como destino para logs, o tempo de execução precisa permitir o streaming de logs para o destino. Para o Kubernetes, é necessário montar um volume que corresponda ao destino.
Dada a seguinte configuração:
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
Você pode facilmente começar a transmitir logs para esse ponto de extremidade 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
Consumindo logs de syslog locais no Serviço Kubernetes do Azure (AKS)
Ao configurar para usar syslog local no Serviço Kubernetes do Azure, você pode escolher duas maneiras de explorar os logs:
- Usar a coleção Syslog com o Container Insights
- Conectar & explorar logs nos nós de trabalho
Consumindo logs de nós de trabalho
Você pode consumi-los facilmente obtendo acesso aos nós de trabalho:
- Criar uma conexão SSH com o nó (docs)
- Os logs podem ser encontrados em
host/var/log/syslog
Por exemplo, você pode filtrar todos os syslogs apenas para aqueles do gateway auto-hospedado:
$ 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"
Nota
Se você alterou a raiz com chroot, por exemplo chroot /host, então o caminho acima precisa refletir essa mudança.
Próximos passos
- Saiba mais sobre os recursos de observabilidade dos gateways de Gerenciamento de API do Azure.
- Saiba mais sobre o gateway auto-hospedado do Azure API Management.
- Saiba mais sobre como configurar e persistir logs na nuvem.