Configurar logs e métricas locais para gateway auto-hospedado de Gerenciamento de API do Azure
APLICA-SE A: Desenvolvedor | Premium
Este artigo fornece detalhes para configurar métricas e logs locais para o gateway auto-hospedado implantado em um cluster do Kubernetes. Para configurar as métricas e o logs na nuvem, consulte este artigo.
Métricas
O gateway auto-hospedado dá suporte ao StatsD, que se tornou um protocolo unificador para coleta e agregação de métricas. Esta seção percorre as etapas para implantar o StatsD no Kubernetes, configurar o gateway para emitir métricas por meio do StatsD e usar o Prometheus para monitorar as métricas.
Implantar StatsD e Prometheus no cluster
O exemplo de configuração do YAML a seguir implanta o StatsD e o Prometheus no cluster do Kubernetes em que um gateway auto-hospedado é implantado. Ele também cria um Serviço para cada. Em seguida, o gateway auto-hospedado publica métricas no Serviço StatsD. Acessaremos o painel do Prometheus por meio do serviço.
Observação
O exemplo a seguir efetua pull de imagens de contêiner públicas do Docker Hub. É recomendável configurar um segredo de pull para autenticar-se usando uma conta do Docker Hub em vez de fazer uma solicitação de pull anônima. Para aumentar 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 comando a seguir para verificar se os pods estão em execução. O nome do 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 os services estão em execução. Anote o CLUSTER-IP e a PORT do Serviço StatsD, que usaremos mais tarde. Você pode visitar o painel do Prometheus usando 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 foram 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 chave no telemetry.metrics.local ConfigMap da Implantação de gateway auto-hospedada com opções adicionais. A seguir estão as opções disponíveis:
| Campo | Padrão | Descrição |
|---|---|---|
| telemetry.metrics.local | none |
Habilita o registro em log por meio do StatsD. O valor pode ser none, statsd. |
| telemetry.metrics.local.statsd.endpoint | N/D | Especifica o ponto de extremidade de StatsD. |
| telemetry.metrics.local.statsd.sampling | N/D | Especifica a taxa de amostragem de métricas. O valor pode ser entre 0 e 1. Exemplo: 0.5 |
| telemetry.metrics.local.statsd.tag-format | N/D | Formato de marcaçãode exportador do StatsD. O valor pode ser none, librato, dogStatsD, influxDB. |
Veja 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 de hospedagem interna 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 de gateway usando o comando abaixo:
kubectl rollout restart deployment/<deployment-name>
Exibir as métricas
Agora que tudo está implantado e configurado, o gateway auto-hospedado deve relatar métricas por meio de StatsD. Em seguida, o Prometheus coleta as métricas do StatsD. Vá para o painel do Prometheus usando EXTERNAL-IP e PORT do serviço Prometheus.
Faça algumas chamadas à API por meio do gateway auto-hospedado, se tudo estiver configurado corretamente, você poderá exibir as métricas abaixo:
| Métrica | Descrição |
|---|---|
| requests_total | Número de solicitações de API no período |
| request_duration_seconds | Número de milissegundos do momento em que o gateway recebeu a solicitação até o momento em que a resposta foi enviada por completo |
| request_backend_duration_seconds | Número de milissegundos gastos na E/S do back-end no total (conectando, enviando e recebendo bytes) |
| request_client_duration_seconds | Número de milissegundos gastos na E/S geral do cliente (conectando, enviando e recebendo bytes) |
Logs
O gateway auto-hospedado gera logs para stdout e stderr por padrão. Você pode exibir facilmente os logs usando o seguinte comando:
kubectl logs <pod-name>
Se o seu gateway auto-hospedado for implantado no Serviço de Kubernetes do Azure, você poderá habilitar Azure monitor para contêineres coletar stdout e stderr de suas cargas de trabalho e exibir os logs na análise de logs.
O gateway auto-hospedado também dá suporte a vários protocolos, incluindo localsyslog, rfc5424 e journal. A tabela a seguir resume todas as opções com suporte.
| Campo | Padrão | Descrição |
|---|---|---|
| telemetry.logs.std | text |
Habilita o registro em log em fluxos padrão. O valor pode ser none, text, json |
| telemetry.logs.local | auto |
Habilita o registro em log local. O valor pode ser none, auto, localsyslog, rfc5424, journal, json |
| telemetry.logs.local.localsyslog.endpoint | N/D | Especifica o ponto de extremidade do syslog local. Para obter detalhes, confira Como usar logs do syslog local. |
| telemetry.logs.local.localsyslog.facility | N/D | Especifica o código de recurso do 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 de instalação por rfc5424. Exemplo: 7 |
| telemetry.logs.local.journal.endpoint | N/D | Especifica o ponto de extremidade do diário. |
| telemetry.logs.local.json.endpoint | 127.0.0.1:8888 | Especifica o ponto de extremidade UDP que aceita dados JSON: caminho do arquivo, IP:porta ou nome do host:porta. |
Este é um exemplo de configuração do 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"
Usar um ponto de extremidade JSON local
Limitações conhecidas
- Só damos suporte a até 3.072 bytes de conteúdo de solicitação/resposta para diagnósticos locais. Qualquer valor acima disso pode quebrar o formato JSON devido ao agrupamento.
Como usar logs do syslog local
Como configurar o gateway para transmitir logs
Ao usar o syslog local como destino para logs, o runtime precisa permitir logs de streaming para o destino. No caso do Kubernetes, é necessário montar um volume que corresponda ao destino.
Considerando 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 iniciar com facilidade os logs de streaming para esse ponto de extremidade do 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
Como consumir os logs do syslog local no AKS (Serviço de Kubernetes do Azure)
Ao configurar o uso do syslog local no Serviço de Kubernetes do Azure, você pode escolher duas maneiras de explorar os logs:
- Use Coleta de Syslog com Insights de Contêiner
- Conectar e explorar logs nos nós de trabalho
Consumindo logs dos nós de trabalho
Você pode consumi-los facilmente obtendo acesso aos nós de trabalho:
- Criar uma conexão SSH para o nó (docs)
- Os logs podem ser encontrados em
host/var/log/syslog
Por exemplo, você pode filtrar todos os syslogs apenas para os 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"
Observação
Se você tiver alterado a raiz com chroot, por exemplo chroot /host, o caminho acima precisará refletir essa alteração.
Próximas etapas
- Saiba mais sobre as funcionalidades de observabilidade dos gateways do Gerenciamento de API do Azure.
- Saiba mais sobre o gateway auto-hospedado do Gerenciamento de API.
- Saiba mais sobre como configurar e persistir os logs na nuvem.