Trabajar con la API

En este documento se describe cómo gestionar servicios y objetivos de nivel de servicio (SLOs) mediante la API Cloud Monitoring.

Service Monitoring añade los siguientes recursos a la API Monitoring:

En este documento, nos referimos a estas adiciones en conjunto como la API SLO y se ilustran los usos principales. Para obtener una descripción general de las estructuras de la API SLO, consulta Estructuras de la API. El material de referencia completo se encuentra en API de Cloud Monitoring v3.

Puedes usar la API SLO para hacer lo siguiente:

  • Crear y gestionar servicios.

  • Crea objetivos de nivel de servicio basados en indicadores de nivel de servicio personalizados o predefinidos para cualquiera de tus servicios.

Identificadores válidos

Varios métodos de la API SLO usan identificadores de diferentes elementos, especialmente identificadores de proyectos y servicios. Estos IDs cumplen las siguientes reglas:

  • Longitud: entre 1 y 63 caracteres
  • Caracteres: solo letras minúsculas, números y guiones
  • Carácter inicial: letra minúscula
  • Carácter final: letra minúscula o número, pero no un guion

La expresión regular de estas reglas es la siguiente: [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

Ejemplos de uso de curl

En esta sección se describen las convenciones y la configuración que se usan para invocar la API SLO con la herramienta curl. Si usas esta API a través de una biblioteca de cliente, puedes saltarte esta sección.

En los ejemplos de esta página se accede a la API SLO mediante la herramienta curl para enviar solicitudes HTTP a endpoints REST. Usa la siguiente información sobre la autenticación y sobre cómo invocar curl para definir las variables que se usan en las invocaciones.

Autenticación

  1. Crea una variable de entorno para almacenar el ID del proyecto de cobertura de tu cobertura de métricas. En estos ejemplos se usa PROJECT_ID:

    PROJECT_ID=my-test-service

  2. Autentícate en Google Cloud CLI:

    gcloud auth login

  3. Para no tener que especificar el ID de tu proyecto en cada comando, puedes definirlo como predeterminado mediante la CLI de gcloud:

    gcloud config set project ${PROJECT_ID}

  4. Crea un token de autorización y guárdalo en una variable de entorno. En estos ejemplos se llama a la variable ACCESS_TOKEN:

    ACCESS_TOKEN=`gcloud auth print-access-token`

    Debes actualizar periódicamente el token de acceso. Si los comandos que funcionaban de repente informan de que no tienes autenticación, vuelve a emitir este comando.

  5. Para verificar que has obtenido un token de acceso, muestra la variable ACCESS_TOKEN:

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

Invocando curl

Cada invocación de curl incluye un conjunto de argumentos, seguido de la URL de un recurso de la API SLO. Los argumentos habituales incluyen los valores especificados por las variables de entorno PROJECT_ID y ACCESS_TOKEN. También es posible que tengas que especificar otros argumentos, como el tipo de solicitud HTTP (por ejemplo, -X DELETE). La solicitud predeterminada es GET, por lo que no se especifica en los ejemplos.

Cada invocación de curl tiene esta estructura general:

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

Por ejemplo, para enumerar todos los servicios de tu proyecto, emite la siguiente solicitud GET:

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

Esta solicitud devuelve una matriz de descripciones de servicios, con entradas como la siguiente, un servicio de carga de trabajo de GKE con el ID de servicio "my-test-service":

{
  "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"
      }
    },
   ...
  ]
}

Para ver la configuración que se ha usado para crear este servicio, consulta Crear un servicio. Ten en cuenta que la estructura gkeWorkload de esta lista se deriva de la estructura basicService utilizada para crear el servicio. Consulta Service para obtener más información sobre la estructura de un servicio.

Gestionar servicios

El recurso Service actúa como elemento raíz para organizar tus servicios. Los aspectos de un servicio concreto, como sus SLOs, se organizan por el nombre del servicio. Se admiten los siguientes tipos de servicios:

  • Servicio de App Engine: APP_ENGINE
  • Servicio de Cloud Endpoints: CLOUD_ENDPOINTS
  • Servicio de Istio canónico: ISTIO_CANONICAL_SERVICE
  • Servicio Istio del clúster: CLUSTER_ISTIO
  • Servicio de Cloud Run: CLOUD_RUN
  • Un conjunto de servicios basados en Google Kubernetes Engine:
    • Servicio de GKE: GKE_SERVICE
    • Espacio de nombres de GKE: GKE_NAMESPACE
    • Carga de trabajo de GKE: GKE_WORKLOAD
  • Servicios personalizados: CUSTOM

Para obtener más información, consulta Tipos de servicios básicos o Tipos de servicios básicos de GKE.

Puede añadir SLOs a cualquier servicio de su proyecto mediante la API. En Gestionar SLOs se explican los comandos para manipular SLOs.

IDs de servicio

Cada servicio tiene un identificador completo llamado nombre de recurso. Este identificador se almacena en el campo name de la descripción del servicio. Por ejemplo:

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

El nombre de recurso incluye un ID más corto del servicio, que es la parte del nombre de recurso que se encuentra después de la subcadena projects/PROJECT_NUMBER/services/

Si has creado tu propio servicio con el nombre de recurso projects/PROJECT_NUMBER/services/my-test-service, el ID de servicio es my-test-service.

Para que los ejemplos de curl sean breves y precisos, se presupone que el ID de servicio se encuentra en la variable de entorno SERVICE_ID, de modo que puedas hacer referencia a él varias veces.

Mostrar servicios

Para obtener información sobre todos los servicios de tu proyecto, invoca el método services.list. Para obtener información sobre un servicio específico por su ID, utiliza el método services.get:

Protocolo

Para obtener información sobre los servicios mediante curl, invoca el método services.list o services.get enviando una solicitud GET a:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services para enumerar todos los servicios
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID para obtener un servicio específico

Por ejemplo, la siguiente solicitud obtiene información sobre el servicio identificado por el valor almacenado en la variable de entorno SERVICE_ID:

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

Crear un servicio

Para crear un servicio, debes especificar una representación del tipo de servicio y enviarla al método services.create. Puedes usar las estructuras de tipo de servicio que se describen en Tipos de servicio básicos y Tipos de servicio básicos de GKE.

Las estructuras varían, pero el proceso para llamar a la API es el mismo. Debes especificar un nombre visible para el servicio y un campo basicService que contenga la representación del servicio.

También puedes especificar el ID que quieres que tenga el servicio. En el siguiente ejemplo se muestra la creación de un servicio de carga de trabajo de {[gke_name_short}}:

Protocolo

Para crear el servicio mediante curl, envía un mensaje POST al punto final https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

  1. Si quieres proporcionar un ID para el servicio, crea una variable para el ID de servicio:

    SERVICE_ID=my-test-service

    Este valor se proporciona en el parámetro de consulta de la URL service_id.

  2. Crea una variable para almacenar el cuerpo de la solicitud que describe el servicio:

    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. Publica el cuerpo de la solicitud en el endpoint y especifica el ID de servicio como valor del parámetro de consulta 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}

Para ver ejemplos de las estructuras asociadas a otros servicios, consulta Tipos de servicios básicos o Tipos de servicios básicos de GKE.

Eliminar un servicio

Para eliminar un servicio que hayas creado, invoca el método services.delete y especifica el ID del servicio.

Protocolo

Para eliminar un servicio mediante curl, envía una solicitud DELETE al punto de conexión https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID:

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

Gestionar objetivos de nivel de servicio

Puedes crear, eliminar y recuperar SLOs mediante la API SLO. Puedes tener hasta 500 SLOs por servicio.

Para gestionar los SLOs de un servicio, debes tener el ID del servicio. Los SLOs se denominan en función del servicio al que pertenecen. Para obtener información sobre cómo identificar los IDs de servicio, consulta IDs de servicio.

Mostrar objetivos de nivel de servicio

Para obtener información sobre todos los SLOs asociados a un servicio, invoca el método services.serviceLevelObjectives.list. Para obtener información sobre un SLO específico por su nombre, utiliza el método services.serviceLevelObjectives.get:

Protocolo

Para obtener información sobre los servicios mediante curl, invoca el método services.serviceLevelObjectives.list o services.serviceLevelObjectives.get enviando una solicitud GET a:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives para listar todos los SLOs
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID para obtener un SLO específico

Por ejemplo, la siguiente solicitud muestra todos los SLOs asociados al ID de servicio almacenado en la variable de entorno SERVICE_ID:

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

A continuación, se muestra un SLO de disponibilidad obtenido del servicio "currencyservice": 

{
  "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",
},

Este objetivo de nivel de servicio se basa en un indicador de nivel de servicio de disponibilidad, establece un objetivo de rendimiento del 98 % y mide el cumplimiento durante una semana natural. Para obtener más información sobre los SLIs de disponibilidad, consulta Indicadores de nivel de servicio.

Consulta ServiceLevelObjective para obtener más información sobre la estructura de los SLOs.

Recuperar un SLO específico

Cada SLO tiene un identificador único en el servicio, que es la cadena que sigue a serviceLevelObjectives en el campo name del SLO. En el siguiente ejemplo:

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

El ID del SLO es la cadena 3kavNVTtTMuzL7KcXAxqCQ.

Para obtener información sobre este SLO concreto, solicítalo por su ID.

Protocolo

Para obtener un SLO específico mediante curl, invoca el método services.serviceLevelObjectives.get enviando una solicitud GET a https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

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}

Crear un acuerdo de nivel de servicio

Para crear un SLO mediante la API SLO, debes crear un objeto ServiceLevelObjective y pasarlo al método serviceLevelObjectives.create.

La estructura de un SLO tiene muchas estructuras insertadas, incluida una para el valor del campo serviceLevelIndicator.

  • En el caso de los servicios de Cloud Service Mesh, Istio en Google Kubernetes Engine y App Engine, los SLIs están predefinidos. Puedes usar la consola de Cloud Service Mesh para crear SLOs. Solo tienes que especificar los objetivos de rendimiento y los periodos de cumplimiento.

  • En el caso de otros servicios, debes definir los SLOs mediante la API SLO. Para especificar un SLO, también debe crear un valor para el campo serviceLevelIndicator. Consulta Crear un indicador de nivel de servicio para ver algunas técnicas y Crear indicadores de nivel de servicio a partir de métricas para ver una serie de ejemplos basados en varias fuentes.

También puedes crear SLIs mediante la Google Cloud consola. Para obtener más información, consulta Crear un SLO.

Estructura de un SLO

La estructura básica para crear el SLO es la siguiente:

{
  "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.
}

Deberás especificar lo siguiente:

  • Nombre visible: una descripción del SLO
  • Un indicador de nivel de servicio, que es uno de los tres tipos:
  • El objetivo de rendimiento (un porcentaje)
  • El periodo de cumplimiento, que puede ser de dos tipos:
    • Un periodo acumulativo de una duración determinada (en segundos).
    • Un periodo del calendario

Para obtener más información sobre los SLIs, los objetivos de rendimiento y los periodos de cumplimiento, consulta Conceptos de la monitorización de servicios.

En el caso de Cloud Service Mesh, Istio en Google Kubernetes Engine y los servicios de App Engine, el tipo de SLI es el SLI básico.

En el caso de otros servicios, debes crear un indicador de nivel de servicio basado en solicitudes o un indicador de nivel de servicio basado en ventanas. Consulta Crear un indicador de nivel de servicio para ver algunas técnicas.

Ejemplo

Una vez que tengas el SLI, podrás crear el SLO. En el siguiente ejemplo se define un SLO para un servicio que usa un SLI básico. Puede que tengas varios SLOs en un solo SLI. Por ejemplo, uno para una disponibilidad del 95% y otro para una disponibilidad del 99 %. En el siguiente ejemplo se muestra un SLO con una disponibilidad del 95% durante una semana natural: 

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

En este ejemplo, se especifica un SLO de disponibilidad del 75% en un periodo de 3 días consecutivos: 

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

Protocolo

Para crear un SLO mediante curl, envía un mensaje POST al https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives endpoint:

  1. Crea una variable para el ID de servicio:

    SERVICE_ID=custom:my-test-service

  2. Crea una variable para contener el cuerpo de la solicitud, una instancia del objeto ServiceLevelObjective. En este ejemplo se usa uno de los SLOs descritos anteriormente:

    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. Publica el cuerpo de la solicitud en el endpoint:

    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

    También puede especificar un ID para el SLO como valor del parámetro de consulta 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}

Eliminar un SLO

Para eliminar un SLO, invoca el método services.serviceLevelObjectives.delete y especifica el ID del SLO en tu proyecto:

Protocolo

Para eliminar un SLO mediante curl, envía una solicitud DELETE al punto de conexión 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}

Acceder a series temporales de SLO

Los datos de SLO se almacenan en series temporales, por lo que puede usar el método timeSeries.list para obtenerlos. Sin embargo, estos datos no se almacenan en tipos de métricas estándar, por lo que no puede usar el mecanismo estándar para especificar un filtro de tipo de métrica en el método timeSeries.list.

En su lugar, las series temporales de SLO se obtienen especificando otro tipo de filtro, un selector de series temporales, en el método timeSeries.list del parámetro filter. Para obtener información sobre cómo usar estos selectores, consulta Extraer datos sobre el objetivo de nivel de servicio.

También puedes usar selectores de series temporales para configurar políticas de alertas mediante programación. Consulta Alertas sobre el ritmo de consumo para obtener más información.