为 Azure API 管理自承载网关配置本地指标和日志Configure local metrics and logs for Azure API Management self-hosted gateway

本文详细介绍如何为自承载网关配置本地指标和日志。This article provides details for configuring local metrics and logs for the self-hosted gateway. 若要配置云指标和日志，请参阅本文。For configuring cloud metrics and logs, see this article.

指标Metrics

自承载网关支持 StatsD，它已成为指标收集和聚合的统一协议。The self-hosted gateway supports StatsD, which has become a unifying protocol for metrics collection and aggregation. 本部分介绍将 StatsD 部署到 Kubernetes 的完整步骤，包含配置网关以通过 StatsD 发出指标，以及使用 Prometheus 监视指标。This section walks through the steps for deploying StatsD to Kubernetes, configuring the gateway to emit metrics via StatsD, and using Prometheus to monitor the metrics.

将 StatsD 和 Prometheus 部署到群集Deploy StatsD and Prometheus to the cluster

下面是一个示例 YAML 配置，用于将 StatsD 和 Prometheus 部署到已部署自承载网关的 Kubernetes 群集。Below is a sample YAML configuration for deploying StatsD and Prometheus to the Kubernetes cluster where a self-hosted gateway is deployed. 它还会为每个群集创建一个服务。It also creates a Service for each. 自承载网关会将指标发布到 StatsD 服务。The self-hosted gateway will publish metrics to the StatsD Service. 我们将通过 Prometheus 的服务访问其仪表板。We will access the Prometheus dashboard via its Service.

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 的文件中，并使用以下命令将所有内容部署到群集：Save the configurations to a file named metrics.yaml and use the below command to deploy everything to the cluster:

kubectl apply -f metrics.yaml

部署完成后，运行以下命令以检查 Pod 是否正在运行。Once the deployment finishes, run the below command to check the Pods are running. 请注意，你的 pod 名称与此不同。Note that your pod name will be different.

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

运行以下命令来检查服务是否正在运行。Run the below command to check the Services are running. 记下 StatsD 服务的 CLUSTER-IP 和 PORT，稍后需要用到。Take a note of the CLUSTER-IP and PORT of the StatsD Service, we would need it later. 可以使用 Prometheus 的 EXTERNAL-IP 和 PORT 访问其仪表板。You can visit the Prometheus dashboard using its EXTERNAL-IP and 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

配置自承载网关以发出指标Configure the self-hosted gateway to emit metrics

部署了 StatsD 和 Prometheus 后，便可以更新自承载网关的配置，以开始通过 StatsD 发出指标。Now that both StatsD and Prometheus have been deployed, we can update the configurations of the self-hosted gateway to start emitting metrics through StatsD. 可以通过其他选项使用自承载网关部署的 ConfigMap 中的 telemetry.metrics.local 密钥来启用或禁用此功能。The feature can be enabled or disabled using the telemetry.metrics.local key in the ConfigMap of the self-hosted gateway Deployment with additional options. 下面是可用选项的详细信息：Below is a breakdown of the available options:

字段Field 默认Default 说明Description
telemetry.metrics.localtelemetry.metrics.local none 通过 StatsD 启用日志记录。Enables logging through StatsD. 值可以是 none、statsd。Value can be none, statsd.
telemetry.metrics.local.statsd.endpointtelemetry.metrics.local.statsd.endpoint 不适用n/a 指定 StatsD 终结点。Specifies StatsD endpoint.
telemetry.metrics.local.statsd.samplingtelemetry.metrics.local.statsd.sampling 不适用n/a 指定指标采样率。Specifies metrics sampling rate. 值可以介于 0 和 1。Value can be between 0 and 1. 例如，0.5e.g., 0.5
telemetry.metrics.local.statsd.tag-formattelemetry.metrics.local.statsd.tag-format 不适用n/a StatsD 导出程序标记格式。StatsD exporter tagging format. 值可以是 none、librato、dogStatsD、influxDB。Value can be none, librato, dogStatsD, influxDB.

下面是示例配置：Here is a sample configuration:

    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 文件，并使用以下命令应用更改：Update the YAML file of the self-hosted gateway deployment with the above configurations and apply the changes using the below command:

kubectl apply -f <file-name>.yaml

若要选取最新的配置更改，请使用以下命令重启网关部署：To pick up the latest configuration changes, restart the gateway deployment using the below command:

kubectl rollout restart deployment/<deployment-name>

查看指标View the metrics

现在，我们已部署并配置了所有内容，自承载网关应通过 StatsD 报告指标。Now we have everything deployed and configured, the self-hosted gateway should report metrics via StatsD. Prometheus 将从 StatsD 中选取指标。Prometheus will pick up the metrics from StatsD. 使用 Prometheus 服务的 EXTERNAL-IP 和 PORT 转到 Prometheus 仪表板。Go to the Prometheus dashboard using the EXTERNAL-IP and PORT of the Prometheus Service.

通过自承载网关进行一些 API 调用，如果所有内容都已正确配置，则应该能够查看以下指标：Make some API calls through the self-hosted gateway, if everything is configured correctly, you should be able to view below metrics:

指标Metric 说明Description
请求Requests 期间内的 API 请求数Number of API requests in the period
DurationInMSDurationInMS 从网关收到请求到响应全部发送出去经过的时间（毫秒）Number of milliseconds from the moment gateway received request until the moment response sent in full
BackendDurationInMSBackendDurationInMS 花在整个后端 IO（连接、发送和接收字节）上的时间（毫秒）Number of milliseconds spent on overall backend IO (connecting, sending and receiving bytes)
ClientDurationInMSClientDurationInMS 花在整个客户端 IO（连接、发送和接收字节）上的时间（毫秒）Number of milliseconds spent on overall client IO (connecting, sending and receiving bytes)

日志Logs

默认情况下，自承载网关会将日志输出到 stdout 和 stderr。The self-hosted gateway outputs logs to stdout and stderr by default. 可以使用以下命令轻松查看日志：You can easily view the logs using the following command:

kubectl logs <pod-name>

如果自承载网关部署在 Azure Kubernetes 服务中，则可以启用适用于容器的 Azure Monitor，以便从工作负载收集 stdout 和 stderr 并查看 Log Analytics 中的日志。If your self-hosted gateway is deployed in Azure Kubernetes Service, you can enable Azure Monitor for containers to collect stdout and stderr from your workloads and view the logs in Log Analytics.

自承载网关还支持多种协议，包括 localsyslog、rfc5424 和 journal。The self-hosted gateway also supports a number of protocols including localsyslog, rfc5424, and journal. 下表汇总了所有支持的选项。The below table summarizes all the options supported.

字段Field 默认Default 说明Description
telemetry.logs.stdtelemetry.logs.std text 启用到标准流的日志记录。Enables logging to standard streams. 值可以是 none、text、jsonValue can be none, text, json
telemetry.logs.localtelemetry.logs.local none 启用本地日志记录。Enables local logging. 值可以是 none、auto、localsyslog、rfc5424、journalValue can be none, auto, localsyslog, rfc5424, journal
telemetry.logs.local.localsyslog.endpointtelemetry.logs.local.localsyslog.endpoint 不适用n/a 指定 localsyslog 终结点。Specifies localsyslog endpoint.
telemetry.logs.local.localsyslog.facilitytelemetry.logs.local.localsyslog.facility 不适用n/a 指定 localsyslog 设备代码。Specifies localsyslog facility code. 例如，7e.g., 7
telemetry.logs.local.rfc5424.endpointtelemetry.logs.local.rfc5424.endpoint 不适用n/a 指定 rfc5424 终结点。Specifies rfc5424 endpoint.
telemetry.logs.local.rfc5424.facilitytelemetry.logs.local.rfc5424.facility 不适用n/a 指定每个 rfc5424 的设备代码。Specifies facility code per rfc5424. 例如，7e.g., 7
telemetry.logs.local.journal.endpointtelemetry.logs.local.journal.endpoint 不适用n/a 指定日志终结点。Specifies journal endpoint.

下面是本地日志记录的示例配置：Here is a sample configuration of local logging:

    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"

后续步骤Next steps