Azure API Management 자체 호스팅 게이트웨이에 대한 로컬 메트릭 및 로그 구성

아티클
04/17/2024

적용 대상: 개발자 | 프리미엄

이 문서에서는 Kubernetes 클러스터에 배포된 자체 호스팅 게이트웨이의 로컬 메트릭 및 로그를 구성하는 방법에 대한 세부 정보를 제공합니다. 클라우드 메트릭과 로그를 구성하는 방법에 대해서는 이 문서를 참조하세요.

메트릭

자체 호스팅 게이트웨이는 메트릭 수집 및 집계의 통합 프로토콜이 된 StatsD를 지원합니다. 이 섹션에서는 StatsD를 Kubernetes에 배포하고, StatsD를 통해 메트릭을 내보내도록 게이트웨이를 구성하며, Prometheus를 사용하여 메트릭을 모니터링 하는 단계를 연습합니다.

클러스터에 StatsD 및 Prometheus 배포

다음 샘플 YAML 구성은 자체 호스팅 게이트웨이가 배포되는 Kubernetes 클러스터에 StatsD 및 Prometheus를 배포합니다. 또한 각각을 대상으로 한서비스도 만듭니다. 그다음 자체 호스팅 게이트웨이에서 StatsD 서비스에 메트릭을 게시합니다. 해당 서비스를 통해 Prometheus 대시보드에 액세스합니다.

참고 항목

다음 예제는 Docker Hub에서 공용 컨테이너 이미지를 가져옵니다. 익명의 끌어오기 요청을 하는 대신 Docker Hub 계정을 사용하여 인증하도록 끌어오기 비밀을 설정하는 것이 좋습니다. 공용 콘텐츠를 사용할 때 신뢰성을 향상시키려면 개인 Azure Container Registry에서 이미지를 가져오고 관리하세요. 공용 이미지 사용에 대해 자세히 알아봅니다.

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

구성을 이름이 metrics.yaml인 파일에 저장합니다. 다음 명령을 사용하여 클러스터에 모든 항목을 배포합니다.

kubectl apply -f metrics.yaml

배포가 완료되면 다음 명령을 실행하여 Pod가 실행되고 있는지 확인합니다. Pod 이름이 달라집니다.

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

아래 명령을 실행하여 services이(가) 실행 중인지 확인합니다. 나중에 사용할 StatsD 서비스의 CLUSTER-IP 및 PORT을(를) 기록해 둡니다. EXTERNAL-IP과 PORT를 사용하여 Prometheus 대시보드에 방문할 수 있습니다.

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

자체 호스팅 게이트웨이를 구성하여 메트릭 내보내기

이제 StatsD와 Prometheus가 모두 배포되었으므로, StatsD를 통해 메트릭 내보내기를 시작하도록 자체 호스팅 게이트웨이의 구성을 업데이트할 수 있습니다. 추가 옵션을 사용하여 자체 호스팅 게이트웨이 배포의 ConfigMap에서 telemetry.metrics.local 키를 사용하여 이 기능을 사용하거나 사용하지 않도록 설정할 수 있습니다. 다음은 사용 가능한 옵션입니다.

필드	기본값	설명
telemetry.metrics.local	`none`	StatsD를 통해 로깅을 사용하도록 설정합니다. 값은 `none`, `statsd`가 될 수 있습니다.
telemetry.metrics.local.statsd.endpoint	해당 없음	StatsD 엔드포인트를 지정합니다.
telemetry.metrics.local.statsd.sampling	해당 없음	메트릭 샘플링 주기를 지정합니다. 값은 0에서 1 사이여야 합니다. 예: `0.5`
telemetry.metrics.local.statsd.tag-format	해당 없음	StatsD 내보내기 태그 지정 형식. 값은 `none`, `librato`, `dogStatsD`, `influxDB`가 될 수 있습니다.

다음은 샘플 구성입니다.

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"

위의 구성을 사용하여 자체 호스팅 게이트웨이 배포의 YAML 파일을 업데이트하고 아래 명령을 사용하여 변경 내용을 적용합니다.

kubectl apply -f <file-name>.yaml

최신 구성 변경 사항을 선택하려면 다음 명령을 사용하여 게이트웨이 배포를 다시 시작합니다.

kubectl rollout restart deployment/<deployment-name>

메트릭 보기

이제 모든 항목을 배포하고 구성했으므로 자체 호스팅 게이트웨이는 StatsD를 통해 메트릭을 보고해야 합니다. 그다음 Prometheus가 StatsD에서 메트릭을 선택합니다. Prometheus 서비스의 EXTERNAL-IP과 PORT를 사용하여 Prometheus 대시보드로 이동합니다.

자체 호스팅 게이트웨이를 통해 일부 API 호출을 수행합니다. 모두 올바르게 구성된 경우 아래 메트릭을 볼 수 있습니다.

메트릭	설명
requests_total	해당 기간의 API 요청 수
request_duration_seconds	게이트웨이에서 요청을 수신한 순간부터 응답이 완전히 전송될 때까지 걸린 시간(밀리초)
request_backend_duration_seconds	전체 백 엔드 IO(바이트 연결, 송신 및 수신)에 소요된 시간(밀리초)
request_client_duration_seconds	전체 클라이언트 IO(연결, 바이트 송신 및 수신)에 소요된 시간(밀리초)

로그

자체 호스팅 게이트웨이는 기본적으로 stdout과 stderr에 로그를 출력합니다. 다음 명령을 사용하여 로그를 쉽게 볼 수 있습니다.

kubectl logs <pod-name>

자체 호스팅 게이트웨이가 Azure Kubernetes Service에 배포되는 경우, 컨테이너용 Azure Monitor를 사용하도록 설정하여 stdout과 stderr를 워크로드에서 수집하고 Log Analytics에서 로그를 볼 수 있습니다.

자체 호스팅 게이트웨이는 localsyslog, rfc5424, journal 등의 다양한 프로토콜도 지원합니다. 다음 표에는 지원되는 모든 옵션이 요약되어 있습니다.

필드	기본값	설명
telemetry.logs.std	`text`	표준 스트림에 로깅을 사용하도록 설정합니다. 값은 `none`, `text`, `json`이 될 수 있습니다.
telemetry.logs.local	`auto`	로컬 로깅을 사용합니다. 값은 `none`, `auto`, `localsyslog`, `rfc5424`, `journal` `json`이 될 수 있습니다.
telemetry.logs.local.localsyslog.endpoint	해당 없음	로컬 syslog 엔드포인트를 지정합니다. 자세한 내용은 로컬 syslog 로그 사용을 참조하세요.
telemetry.logs.local.localsyslog.facility	해당 없음	로컬 syslog 기능 코드를 지정합니다. 예: `7`
telemetry.logs.local.rfc5424.endpoint	해당 없음	rfc5424 엔드포인트를 지정합니다.
telemetry.logs.local.rfc5424.facility	해당 없음	각 rfc5424의 기능 코드를 지정합니다. 예: `7`
telemetry.logs.local.journal.endpoint	해당 없음	업무 일지 엔드포인트를 지정합니다.
telemetry.logs.local.json.endpoint	127.0.0.1:8888	파일 경로, IP:포트 또는 호스트 이름:포트와 같은 JSON 데이터를 허용하는 UDP 엔드포인트를 지정합니다.

로컬 로깅의 샘플 구성은 다음과 같습니다.

    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"

로컬 JSON 엔드포인트 사용

알려진 제한 사항

로컬 진단에는 최대 3072바이트의 요청/응답 페이로드만 지원됩니다. 위의 내용은 청크로 인해 JSON 형식이 손상될 수 있습니다.

로컬 syslog 로그 사용

로그를 스트리밍하도록 게이트웨이 구성

로컬 syslog를 로그의 대상으로 사용하는 경우 런타임에서 대상에 대한 스트리밍 로그를 허용해야 합니다. Kubernetes의 경우 대상과 일치하는 볼륨을 탑재해야 합니다.

다음 구성을 조건으로 합니다.

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

해당 로컬 syslog 엔드포인트로 로그 스트리밍을 쉽게 시작할 수 있습니다.

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

AKS(Azure Kubernetes Service)에서 로컬 syslog 로그 사용

Azure Kubernetes Service에서 로컬 syslog를 사용하도록 구성할 때 로그를 탐색하는 다음 두 가지 방법 중 하나를 선택할 수 있습니다.

Container Insights를 사용하는 Syslog 컬렉션을 사용합니다.
작업자 노드에서 로그 연결 및 탐색

작업자 노드에서 로그 사용

작업자 노드에 액세스하여 쉽게 사용할 수 있습니다.

노드에 대한 SSH 연결 만들기(설명서)
로그는 host/var/log/syslog 아래에서 찾을 수 있습니다.

예를 들어 모든 syslog를 자체 호스팅 게이트웨이의 syslog로 필터링할 수 있습니다.

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