本文介绍了如何使用 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
的信息设置调用中使用的变量。
身份验证
创建一个环境变量来保存指标范围的范围项目的 ID:以下示例使用
PROJECT_ID
:PROJECT_ID=my-test-service
向 Google Cloud CLI 进行身份验证:
gcloud auth login
为避免必须使用每个命令指定项目 ID,请使用 gcloud CLI 将其设置为默认值:
gcloud config set project ${PROJECT_ID}
创建授权令牌并将其存储到环境变量中。 这些示例调用变量
ACCESS_TOKEN
:ACCESS_TOKEN=`gcloud auth print-access-token`
您必须定期刷新访问令牌。如果命令突然报告您未通过身份验证,请重新发布此命令。
要验证您是否已获得访问令牌,请回显
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
- GKE 服务:
- 自定义服务:
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
消息:
如果要提供服务 ID,请为服务 ID 创建变量:
SERVICE_ID=my-test-service
网址查询参数
service_id
中会提供此值。创建变量以保存描述服务的请求正文:
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 )
将请求正文发布到端点,并指定服务 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
端点:
为服务 ID 创建变量:
SERVICE_ID=custom:my-test-service
创建一个变量来保存请求正文,即
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 )
将请求正文发布到端点:
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 数据。
您还可以使用时间序列选择器以编程方式设置提醒政策。如需了解详情,请参阅消耗率提醒。