使用 API

本文介绍了如何使用 Cloud Monitoring API 管理服务和服务等级目标 (SLO)。

Service Monitoring 可将以下资源添加到 Monitoring API 中：

本文档将这些新增项统称为 SLO API，并说明主要用途。如需大致了解 SLO API 中的结构，请参阅 API 中的构造。全面的参考资料将显示在 Cloud Monitoring API v3 下。

您可以使用 SLO API 执行以下操作：

  • 创建和管理服务。

  • 根据任何服务的自定义或预定义服务等级指标 (SLI) 创建服务等级目标 (SLO)。

有效标识符

SLO API 中的一些方法针对不同元素使用不同的标识符，尤其是项目和服务的标识符。这些 ID 遵循以下规则：

  • 长度：1-63 个字符
  • 字符：只能使用小写字母、数字和连字符
  • 首字母：小写字母
  • 尾字母：小写字母或数字，但不能是连字符

这些规则的正则表达式如下所示：[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

使用 curl 的示例

本部分介绍了使用 curl 工具调用 SLO API 所使用的惯例和设置。如果您是通过客户端库使用此 API，则可以跳过此部分。

本页面中的示例通过使用 curl 工具向 REST 端点发送 HTTP 请求来访问 SLO API。使用以下关于身份验证和调用 curl 的信息设置调用中使用的变量。

身份验证

  1. 创建一个环境变量来保存指标范围的范围项目的 ID：以下示例使用 PROJECT_ID：

    PROJECT_ID=my-test-service

  2. 向 Google Cloud CLI 进行身份验证：

    gcloud auth login

  3. 为避免必须使用每个命令指定项目 ID，请使用 gcloud CLI 将其设置为默认值：

    gcloud config set project ${PROJECT_ID}

  4. 创建授权令牌并将其存储到环境变量中。 这些示例调用变量 ACCESS_TOKEN：

    ACCESS_TOKEN=`gcloud auth print-access-token`

    您必须定期刷新访问令牌。如果命令突然报告您未通过身份验证，请重新发布此命令。

  5. 要验证您是否已获得访问令牌，请回显 ACCESS_TOKEN 变量：

    echo ${ACCESS_TOKEN}
ya29.GluiBj8o....

调用 curl

每个 curl 调用都包含一组参数，其后面是 SLO API 资源的网址。常见参数包括由 PROJECT_ID 和 ACCESS_TOKEN 环境变量指定的值。您可能还需要指定其他参数，例如，指定 HTTP 请求的类型（例如 -X DELETE）。默认请求为 GET，因此示例未指定该请求。

每个 curl 调用具有以下一般结构：

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

例如，如需列出项目中的所有服务，请发出以下 GET 请求：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services

此请求会返回一组服务说明，其中包含如下所示的条目，示例是服务 ID 为“my-test-service”的 GKE 工作负载服务：

{
  "services": [
    {
      "name": "projects/PROJECT_NUMBER/services/my-test-service",
      "displayName": "My Test GKE Workload Service",
      "basicService": {
        "serviceType": "GKE_WORKLOAD",
        "serviceLabels": {
          "cluster_name": "workload-test",
          "location": "us-central1-c",
          "namespace_name": "kube-system",
          "project_id": "lesser-weevil",
          "top_level_controller_name": "gke-metrics-controller",
          "top_level_controller_type": "DaemonSet"
        }
      },
      "gkeWorkload": {
        "projectId": "lesser-weevil",
        "location": "us-central1-c",
        "clusterName": "workload-test",
        "namespaceName": "kube-system",
        "topLevelControllerType": "DaemonSet",
        "topLevelControllerName": "gke-metrics-controller"
      },
      "source": "USER",
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller"
      }
    },
   ...
  ]
}

如需查看用于创建此服务的配置，请参阅创建服务。请注意，此清单中的 gkeWorkload 结构派生自用于创建服务的 basicService 结构。如需详细了解服务的结构，请参阅 Service。

管理服务

Service 资源充当组织服务的根元素。某个特定服务的各方面（例如其 SLO）都按照服务名称整理。 支持以下服务类型：

  • App Engine 服务：APP_ENGINE
  • Cloud Endpoints 服务：CLOUD_ENDPOINTS
  • 规范化 Istio 服务：ISTIO_CANONICAL_SERVICE
  • 集群 Istio 服务：CLUSTER_ISTIO
  • Cloud Run 服务：CLOUD_RUN
  • 一组基于 Google Kubernetes Engine 的服务：
    • GKE 服务：GKE_SERVICE
    • GKE 命名空间：GKE_NAMESPACE
    • GKE 工作负载：GKE_WORKLOAD
  • 自定义服务：CUSTOM

如需了解详情，请参阅基本服务类型或基本 GKE 服务类型。

您可以使用 API 将 SLO 添加到项目中的任何服务。 管理 SLO涵盖操纵 SLO 的命令。

服务 ID

每个服务都有一个被称为资源名称的完全限定标识符。此标识符存储在服务说明的 name 字段中，例如：

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",

资源名称中嵌入了服务的较短 ID，即资源名称中子字符串 projects/PROJECT_NUMBER/services/ 之后的部分

如果您使用资源名称 projects/PROJECT_NUMBER/services/my-test-service 创建了自己的服务，则服务 ID 为 my-test-service。

为了简洁和准确，许多 curl 示例假设服务 ID 保存在环境变量 SERVICE_ID 中，因此您可以反复参考。

列出服务

要检索项目中所有服务的相关信息，请调用 services.list 方法。要按服务 ID 检索特定服务的相关信息，请使用 services.get 方法：

协议

要使用 curl 列出有关服务的信息，请通过将 GET 请求发送给以下对象，来调用 services.list 或 services.get 方法：

  • 要列出所有服务，请发送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
  • 要获取特定服务，请发送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID

例如，以下请求会检索与环境变量 SERVICE_ID 中存储的值所标识服务相关的信息：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

创建服务

要创建服务，请指定服务类型的表示形式并将其发送到 services.create 方法。您可以创建基本服务类型和基本 GKE 服务类型中所述的服务类型结构。

这些结构各不相同，但调用 API 的过程是相同的。您必须指定服务的显示名称以及保存服务表示法的 basicService 字段。

您可以选择指定您希望服务具有的服务 ID。 以下示例展示了如何创建 {[gke_name_short}} 工作负载服务：

协议

要使用 curl 创建服务，请向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services 端点发送一条 POST 消息：

  1. 如果要提供服务 ID，请为服务 ID 创建变量：

    SERVICE_ID=my-test-service

    网址查询参数 service_id 中会提供此值。

  2. 创建变量以保存描述服务的请求正文：

    CREATE_SERVICE_POST_BODY=$(cat <<EOF
{
  "displayName": "My Test GKE Workload Service",
  "basicService": {
    "serviceType": "GKE_WORKLOAD",
    "serviceLabels": {
      "cluster_name": "workload-test",
      "location": "us-central1-c",
      "namespace_name": "kube-system",
      "project_id": "PROJECT_ID",
      "top_level_controller_name": "gke-metrics-controller",
      "top_level_controller_type": "DaemonSet"
    }
  }
}
EOF
)

  3. 将请求正文发布到端点，并指定服务 ID 作为 service_id 查询参数的值：

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}

如需查看与其他服务关联的结构示例，请参阅基本服务类型或基本 GKE 服务类型。

删除服务

如需删除您创建的服务，请调用 services.delete 方法并指定服务 ID。

协议

要使用 curl 删除服务，请向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID 端点发送 DELETE 请求：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

管理 SLO

您可以使用 SLO API 创建、删除和检索 SLO。每个服务最多可以有 500 个 SLO。

要管理服务的 SLO，您必须拥有服务 ID。SLO 根据其所属的服务进行命名。 如需了解如何识别服务 ID，请参阅服务 ID。

列出 SLO

要检索与服务关联的所有 SLO 的相关信息，请调用 services.serviceLevelObjectives.list 方法。要按名称检索特定 SLO 的相关信息，请使用 services.serviceLevelObjectives.get 方法：

协议

要使用 curl 列出有关服务的信息，请通过将 GET 请求发送给以下对象，来调用 services.serviceLevelObjectives.list 或 services.serviceLevelObjectives.get 方法：

  • 要列出所有 SLO，请发送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives
  • 要获取特定 SLO，请发送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID

例如，以下请求列出了与存储在环境变量 SERVICE_ID 中的服务 ID 相关联的所有 SLO：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

以下是从“currencyservice”服务检索到的 SLO 可用性：

{
  "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
  "displayName": "98% Availability in Calendar Week"
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.98,
  "calendarPeriod": "WEEK",
},

此 SLO 是基于 SLI 可用性构建的，它设置的目标性能目标为“98％”，并且会在日历周内衡量合规性。如需详细了解 SLI 可用性，请参阅服务等级指标。

如需详细了解 SLO 的结构，请参阅 ServiceLevelObjective。

检索特定 SLO

每个 SLO 在服务中都有一个唯一标识符，由 SLO name 字段中位于 serviceLevelObjectives 后面的字符串组成。在以下示例中：

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",

SLO ID 为字符串 3kavNVTtTMuzL7KcXAxqCQ。

要检索有关此特定 SLO 的信息，请按 ID 发出 SLO 请求。

协议

要使用 curl 获取特定 SLO，请通过向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID 发送 GET 请求来调用 services.serviceLevelObjectives.get 方法：

SLO_ID=dhefHDM4TwSRZEKIV4ZYEg

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

创建 SLO

要使用 SLO API 创建 SLO，您必须创建一个 ServiceLevelObjective 对象并将其传递给 serviceLevelObjectives.create 方法。

SLO 的结构具有许多嵌入式结构，其中便有一个关于 serviceLevelIndicator 字段的值的结构。

  • 对于 Cloud Service Mesh、Istio on Google Kubernetes Engine 和 App Engine 服务，SLI 已预定义。您可以使用 Cloud 服务网格控制台创建 SLO；您只需指定型能目标和合规期即可。

  • 对于其他服务，您必须使用 SLO API 定义 SLO。要指定 SLO，您还必须为 serviceLevelIndicator 字段创建一个值。如需了解一些技术问题，请参阅创建服务等级指标；如需查看基于各种来源的一组示例，请参阅根据指标创建 SLI。

您还可以使用 Google Cloud 控制台创建 SLI。如需了解详情，请参阅创建 SLO。

SLO 的框架

构建 SLO 的基本框架如下：

{
  "displayName": string,
  "serviceLevelIndicator": {
    object (ServiceLevelIndicator)
  },
  "goal": number,

  // Union field period can be only one of the following:
  "rollingPeriod": string,
  "calendarPeriod": enum (CalendarPeriod)
  // End of list of possible types for union field period.
}

您必须指定以下各项：

  • 显示名：SLO 的说明
  • 服务等级指标，可以是以下三种类型之一：
  • 性能目标（百分比）
  • 合规性期限，有以下两种类型：
    • 一定长度的滚动式时间段（以秒为单位）
    • 日历周期

如需详细了解 SLI、效果目标和合规性周期的详情，请参阅服务监控中的概念。

对于 Cloud Service Mesh、Istio on Google Kubernetes Engine 和 App Engine 服务，SLI 类型是基本的 SLI。

对于其他服务，您必须创建基于请求的 SLI 或基于 Windows 的 SLI。如需了解一些技术问题，请参阅创建服务等级指标。

示例

获得 SLI 后，您便可以构建 SLO。以下示例为使用基本 SLI 的服务定义了 SLO。单个 SLI 上可能有多个 SLO，例如，一个 SLO 的可用性为 95％，另一个 SLO 的可用性为 99％。以下示例是在日历周内可用性为 95％ 的 SLO：

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.95,
  "calendarPeriod": "WEEK",
  "displayName": "95% Availability in Calendar Week"
}

此示例指定了在 3 天滚动周期内可用性为 75％的 SLO： 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}

协议

要使用 curl 创建 SLO，请将 POST 条消息发送到 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives 端点：

  1. 为服务 ID 创建变量：

    SERVICE_ID=custom:my-test-service

  2. 创建一个变量来保存请求正文，即 ServiceLevelObjective 对象的实例。此示例使用前面描述的某个 SLO：

    CREATE_SLO_POST_BODY=$(cat <<EOF
{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}
EOF
)

  3. 将请求正文发布到端点：

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

    您也可以为 SLO 指定所需 ID，将其作为 service_level_objective_id 查询参数的值：

    SLO_ID=test-slo-id

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}

删除 SLO

要删除 SLO，请调用 services.serviceLevelObjectives.delete 方法，并在项目中指定 SLO 的 ID：

协议

要使用 curl 删除 SLO，请将 DELETE 请求发送到 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID 端点：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

访问 SLO 时间序列

SLO 数据按时间序列存储，因此您可以使用 timeSeries.list 方法检索这些数据。但是，此类数据并非以标准指标类型存储，因此您无法使用为 timeSeries.list 方法指定指标类型过滤条件的标准机制。

相反，您可以通过在 filter 参数中向 timeSeries.list 方法指定其他类型的过滤条件（时间序列选择器）来检索 SLO 时间序列。如需了解使用这些选择器的信息，请参阅检索 SLO 数据。

您还可以使用时间序列选择器以编程方式设置提醒政策。如需了解详情，请参阅消耗率提醒。