設定 Azure APIM 自我裝載閘道的本機計量和記錄

發行項
06/25/2024

適用於：開發人員 | 進階

本文將為 Kubernetes 叢集上部署的自我裝載閘道提供設定本機計量和記錄的詳細資料。如需設定雲端計量和記錄的資訊，請參閱這篇文章。

計量

自我裝載閘道支援 StatsD，其已成為計量集合和彙總的統一通訊協定。本節將逐步解說如何將 StatsD 部署至 Kubernetes、設定閘道以透過 StatsD 發出計量，以及使用 Prometheus 來監視計量。

將 StatsD 和 Prometheus 部署至叢集

以下範例 YAML 組態會將 StatsD 和 Prometheus 部署至自我裝載閘道部署所在的 Kubernetes 叢集。其也會為每個項目建立服務。自我裝載閘道接著會將計量發佈至 StatsD 服務。我們將透過 Prometheus 的服務存取其儀表板。

注意

下列範例會從 Docker Hub 提取公用容器映像。建議您設定提取祕密，以使用 Docker Hub 帳戶進行驗證，而不是發出匿名提取要求。若要改善使用公用內容時的可靠性，請在私人 Azure 容器登錄中匯入和管理映像。深入了解使用公用映像。

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，我們稍後會用到此資訊。您可以使用 Prometheus 的 EXTERNAL-IP 和 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

設定自我裝載閘道以發出計量

現在 StatsD 和 Prometheus 都已部署完畢，接著我們可以更新自我裝載閘道的設定，以開始透過 StatsD 發出計量。您可以在自我裝載閘道部署的 ConfigMap 中使用 telemetry.metrics.local 金鑰搭配其他選項來啟用或停用此功能。以下是可用的選項：

欄位	預設	描述
telemetry.metrics.local	`none`	透過 StatsD 啟用記錄。值可以是 `none`、`statsd`。
telemetry.metrics.local.statsd.endpoint	n/a	指定 StatsD 端點。
telemetry.metrics.local.statsd.sampling	n/a	指定計量取樣率。值可介於 0 到 1 之間。範例: `0.5`
telemetry.metrics.local.statsd.tag-format	n/a	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 監視器，從工作負載收集 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	n/a	指定本機 syslog 端點。如需詳細資訊，請參閱使用本機 syslog 記錄。
telemetry.logs.local.localsyslog.facility	n/a	指定本機 syslog 設備代碼。範例: `7`
telemetry.logs.local.rfc5424.endpoint	n/a	指定 rfc5424 端點。
telemetry.logs.local.rfc5424.facility	n/a	指定每個 rfc5424 的設施代碼。範例: `7`
telemetry.logs.local.journal.endpoint	n/a	指定日誌端點。
telemetry.logs.local.json.endpoint	127.0.0.1:8888	指定接受 JSON 資料的 UDP 端點：檔案路徑、IP：連接埠或主機名稱：連接埠。

以下是本機記錄的範例設定：

    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

在 Azure Kubernetes Service (AKS) 上取用本機 syslog 記錄

在 Azure Kubernetes Service 上設定為使用本機 syslog 時，您可以選擇兩種方式來探索記錄：

使用搭配容器深入解析的 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"

注意

如果已使用 chroot 變更根目錄 (例如 chroot /host)，則上述路徑必須反映該變更。

共用方式為