Azure API Management のセルフホステッドゲートウェイにローカルメトリックとログを構成する

[アーティクル]
04/18/2024

適用対象: Developer | Premium

この記事では、Kubernetes クラスターに展開されたセルフホステッドゲートウェイに、ローカルメトリックとログを構成する方法について詳しく説明します。クラウドメトリックとログを構成する方法については、この記事を参照してください。

メトリック

セルフホステッドゲートウェイでは、メトリックの収集と集計のための統一プロトコルとなっている、StatsD がサポートされています。このセクションでは、StatsD を Kubernetes にデプロイし、StatsD を使用してメトリックを出力するようにゲートウェイを構成し、Prometheus を使用してメトリックを監視する手順について説明します。

StatsD と Prometheus をクラスターにデプロイする

次の YAML 構成のサンプルでは、セルフホステッドゲートウェイがデプロイされている Kubernetes クラスターに StatsD と Prometheus をデプロイします。また、それぞれに対してサービスも作成します。その後、セルフホステッドゲートウェイにより、StatsD サービスにメトリックが公開されます。そのサービスを介して Prometheus ダッシュボードにアクセスします。

Note

次の例では、パブリックコンテナーイメージを Docker Hub からプルします。匿名の pull request を行うのではなく、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

デプロイが完了したら、次のコマンドを実行してポッドが実行されていることを確認します。使用するポッド名は別のものになります。

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 キーを使用して有効または無効にすることができます。使用可能なオプションを次に示します。

フィールド	Default	説明
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 などの多数のプロトコルもサポートされています。次の表に、サポートされているすべてのオプションの概要を示します。

フィールド	Default	説明
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	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

Azure Kubernetes Service (AKS) でのローカル syslog ログの使用

Azure Kubernetes Service でローカル syslog を使用するよう構成する場合は、ログを検索する 2 つの方法を選択できます。

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"

注意

たとえば chroot /host のように、chroot でルートを変更した場合、上記のパスはその変更を反映する必要があります。

次のステップ

Azure API Management ゲートウェイの監視機能について理解します。
API Management のセルフホステッドゲートウェイの詳細について確認します。
クラウドでログを構成して永続化することについて学習します。

次の方法で共有

Azure API Management のセルフホステッドゲートウェイにローカルメトリックとログを構成する

メトリック

StatsD と Prometheus をクラスターにデプロイする

メトリックを出力するようにセルフホステッドゲートウェイを構成する

メトリックを表示する

ログ

ローカル JSON エンドポイントの使用

既知の制限事項

ローカル syslog ログの使用

ログをストリーミングするためのゲートウェイの構成

Azure Kubernetes Service (AKS) でのローカル syslog ログの使用

ワーカーノードからのログの使用

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure API Management のセルフホステッド ゲートウェイにローカル メトリックとログを構成する

メトリック

StatsD と Prometheus をクラスターにデプロイする

メトリックを出力するようにセルフホステッド ゲートウェイを構成する

メトリックを表示する

ログ

ローカル JSON エンドポイントの使用

既知の制限事項

ローカル syslog ログの使用

ログをストリーミングするためのゲートウェイの構成

Azure Kubernetes Service (AKS) でのローカル syslog ログの使用

ワーカー ノードからのログの使用

次のステップ

フィードバック

その他のリソース

Azure API Management のセルフホステッドゲートウェイにローカルメトリックとログを構成する

メトリックを出力するようにセルフホステッドゲートウェイを構成する

ワーカーノードからのログの使用