Configurar métricas e logs locais para o gateway auto-hospedado do Gerenciamento de API do Azure

Artigo
06/20/2024

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=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"