使用 API

Beta 版

此产品或功能目前处于预发布状态，可能会更改或仅提供有限支持。如需了解详情，请参阅产品发布阶段。

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

• services
• services.serviceLevelObjectives

本页面介绍了新 API 资源的主要用途。如需了解此处所用结构的一般概览，请参阅 API 中的构造。全面的参考资料将显示在 Cloud Monitoring API v3 下。

本文档将这些新增内容统称为 Service Monitoring API。

何时使用 API

Service Monitoring API 可用于管理服务和服务等级目标 (SLO)。本页面重点介绍自定义服务和服务等级指标 (SLI)。系统会自动检测 App Engine、Istio on Google Kubernetes Engine 和 Cloud Endpoints 上运行的服务，并为其预定义 SLI。要定义 SLO，您可以使用 Anthos 服务网格控制台或 Service Monitoring API。如需详细了解如何使用 Anthos 服务网格信息中心创建 SLO，请参阅 Anthos 服务网格文档：创建 SLO。

您还可以定义自己的服务及其 SLO，但必须使用 Service Monitoring API。没有可用的 Google Cloud Console 支持。

此页面上的示例主要介绍自定义服务和 SLI。

有效标识符

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

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

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

使用 curl 的示例

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

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

身份验证

1. 创建一个环境变量来保存 Cloud Monitoring 工作区的 ID。这些示例使用 PROJECT_ID：

   PROJECT_ID=my-test-service
       

2. 向 Cloud SDK 验证身份：

   gcloud auth login
       

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

   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 调用都包含一组参数，其后面是 Service Monitoring 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
    

此请求会返回一组服务说明，其中包含如下所示的条目，示例是名为“currencyservice”的 Istio 服务：

    {
      "services": [
        {
          "name": "projects/[PROJECT_NUMBER]/services/[PROJECT_ID]-zone-us-central1-c-csm-main-default-currencyservice",
          "displayName": "[PROJECT_ID]/us-central1-c/csm-main/default/currencyservice",
          "clusterIstio": {
            "location": "us-central1-c",
            "clusterName": "csm-main",
            "serviceNamespace": "default",
            "serviceName": "currencyservice"
          },
          "telemetry": {
            "resourceName": "//container.googleapis.com/projects/[PROJECT_ID]/zones/us-central1-c/clusters/csm-main/k8s/namespaces/default/services/currencyservice"
          }
        },
       ...
      ]
    }
    

如需详细了解服务的结构，请参阅 Service。

管理服务

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

系统会自动为您在 App Engine、Istio on Google Kubernetes Engine 和 Cloud Endpoints 上创建服务。您可以使用 Anthos 服务网格控制台或 Service Monitoring API 执行操作，例如将 SLO 添加到这些服务中。

您手动创建的服务称为自定义服务。只能使用 Service Monitoring 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}
    

创建服务

如果您没有使用自动创建服务的环境（即 App Engine、Istio on Google Kubernetes Engine 和 Cloud Endpoints），则可以使用 services.create 方法创建服务。

如果您手动创建服务，则必须使用 Service Monitoring API 手动将 SLO 和其他服务监控工件添加到服务结构中。如需了解这些结构的概述，请参阅 API 中的构造。

要创建服务，您必须指定服务的显示名以及名为 custom 的字段（对象为空）。您可以选择指定您希望服务具有的服务 ID。

协议

要使用 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 Service",
           "custom": {}
       }
       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}
       

删除服务

要删除自定义服务，请调用 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 与服务关联。您可以使用适用于 App Engine 的 Anthos 服务网格控制台、Istio on Google Kubernetes Engine、Cloud Endpoints 或使用 Service Monitoring API 创建 SLO。您必须使用 Service Monitoring API 为自定义服务创建 SLO。

您还可以使用 Service Monitoring API 检索与服务关联的 SLO，以及从服务中删除 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

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

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

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

  您还可以使用 Service Monitoring API 来定义 SLO。

• 对于自定义服务，您必须使用 Service Monitoring API 来定义 SLO。要指定 SLO，您还必须为 serviceLevelIndicator 字段创建一个值。如需了解一些技术问题，请参阅创建服务等级指标。

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 的说明
• 服务等级指标，可以是以下三种类型之一：
  • BasicSli
  • RequestBasedSli
  • WindowsBasedSli
• 性能目标（百分比）
• 合规性期限，有以下两种类型：
  • 一定长度的滚动周期（以秒为单位）
  • 日历周期

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

对于 App Engine、Istio on Google Kubernetes Engine 和 Cloud Endpoints 服务，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 数据。

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