Trabajar con la API

En este documento, se describe cómo administrar servicios y objetivos de nivel de servicio (SLO) con la API de Cloud Monitoring.

Service Monitoring agrega los siguientes recursos a la API de Monitoring:

En este documento, se hace referencia a estas adiciones en forma colectiva como la API de SLO y se ilustran los usos principales. Para obtener una descripción general de las estructuras en la API de SLO, consulta Construcciones en la API. El material de referencia completo aparece en API de Cloud Monitoring v3.

Puedes usar la API de SLO para hacer lo siguiente:

  • Crea y administra servicios.

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

Identificadores válidos

Varios métodos de la API de SLO usan identificadores para diferentes elementos, en particular los identificadores de proyectos y servicios. Estos ID cumplen con las siguientes reglas:

  • Longitud: de 1 a 63 caracteres
  • Caracteres: solo letras minúsculas, números y guiones
  • Carácter inicial: letra minúscula
  • Carácter final: una letra minúscula o un 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 en los que se usa curl

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

En los ejemplos de esta página, se accede a la API de SLO mediante la herramienta de curl a fin de enviar solicitudes HTTP a los extremos de REST. Usa la siguiente información sobre la autenticación y la invocación de curl para establecer las variables que se usan en las invocaciones.

Autenticación

  1. Crea una variable de entorno para guardar ID del proyecto de permiso de un permiso de métricas. En estos ejemplos, se usa PROJECT_ID:

    PROJECT_ID=my-test-service

  2. Autentica en la CLI de Google Cloud:

    gcloud auth login

  3. Para no tener que especificar tu ID del proyecto con cada comando, configúralo como predeterminado con la CLI de gcloud:

    gcloud config set project ${PROJECT_ID}

  4. Crea un token de autorización y captúralo en una variable de entorno. Estos ejemplos llaman a la variable ACCESS_TOKEN:

    ACCESS_TOKEN=`gcloud auth print-access-token`

    Deberás actualizar el token de acceso de forma periódica. Si los comandos que funcionaban de repente informan que no estás autenticado, vuelve a emitir este comando.

  5. Para verificar que cuentas con un token de acceso, reproduce la variable ACCESS_TOKEN:

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

Invoca curl

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

Cada invocación 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, envía la siguiente solicitud GET:

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

En esta solicitud, se muestra un array de descripciones de servicio con entradas como las siguientes; 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 usa con el objetivo de crear este servicio, consulta Crea un servicio. Ten en cuenta que la estructura gkeWorkload de esta ficha deriva de la estructura basicService que se usa para crear el servicio. Consulta Service para obtener más información sobre la estructura de un servicio.

Administra servicios

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

  • Servicio de App Engine: APP_ENGINE
  • Servicio de Cloud Endpoints: CLOUD_ENDPOINTS
  • Servicio canónico de Istio: ISTIO_CANONICAL_SERVICE
  • Servicio de Istio de 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.

Puedes agregar SLO a cualquier servicio de tu proyecto mediante la API. La sección Administra SLO abarca los comandos para manipular los SLO.

ID del servicio

Cada servicio tiene un identificador completamente calificado llamado nombre del 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",

Existe un ID más corto del servicio incorporado en el nombre del recurso; en la sección que se encuentra después de la substring projects/PROJECT_NUMBER/services/.

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

Por motivos de brevedad y precisión, muchos ejemplos de curl suponen que el ID del servicio se retiene en la variable de entorno SERVICE_ID para que puedas consultarlo varias veces.

Genera una lista de servicios

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

Protocolo

Para mostrar información sobre los servicios con curl, invoca el método services.list o services.get a través del envío de una solicitud GET a las siguientes direcciones URL:

  • 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 recupera 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, especifica una representación del tipo de servicio y envíala al método services.create. Puedes tener las estructuras de tipo de servicio descritas en Tipos de servicios básicos y Tipos de servicios de GKE básicos.

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.

De forma opcional, puedes especificar el ID que quieras para tu servicio. En el siguiente ejemplo, se muestra la creación de un servicio de carga de trabajo {[gke_name_short}}:

Protocolo

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

  1. Si deseas proporcionar un ID del servicio, crea una variable para ese ID:

    SERVICE_ID=my-test-service

    Este valor se proporciona en el parámetro de búsqueda de URL service_id.

  2. Crea una variable para retener 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 extremo y especifica el ID del 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 con otros servicios, consulta Tipos de servicios básicos o Tipos de servicios básicos de GKE.

Borra un servicio

Para borrar un servicio que creaste, invoca el método services.delete y especifica el ID del servicio.

Protocolo

Para borrar un servicio mediante curl, envía una solicitud DELETE al extremo 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}

Administra los SLO

Puedes crear, borrar y recuperar SLO mediante la API de SLO. Puedes tener hasta 500 SLO por cada servicio.

Para administrar los SLO de un servicio, debes tener el ID del servicio. Los SLO se nombran según el servicio al que pertenecen. Para obtener información sobre la identificación de ID de servicio, consulta ID de servicio.

Genera una lista de SLO

Para recuperar información sobre todos los SLO asociados con un servicio, invoca el método services.serviceLevelObjectives.list. Para recuperar información sobre un SLO específico por nombre, usa el método services.serviceLevelObjectives.get:

Protocolo

Para mostrar información sobre los servicios con curl, invoca el método services.serviceLevelObjectives.list o services.serviceLevelObjectives.get enviando una solicitud GET a las siguientes direcciones URL:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives para enumerar todos los SLO
  • 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 enumera todos los SLO asociados con el ID del 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 recuperado 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 SLO se compila en un SLI de disponibilidad, configura un objetivo de rendimiento del 98% y mide el cumplimiento durante una semana calendario. Para obtener más información sobre los SLI de disponibilidad, consulta Indicadores de nivel de servicio.

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

Recupera un SLO específico

Cada SLO tiene un identificador único dentro del servicio, que se compone de la string que sigue a serviceLevelObjectives en el campo name del SLO. Observa 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 string 3kavNVTtTMuzL7KcXAxqCQ.

Para recuperar información sobre este SLO en particular, solicita el SLO por ID.

Protocolo

Para obtener un SLO específico con curl, invoca el método services.serviceLevelObjectives.get mediante el envío de 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}

Crea un SLO

Debes crear un objeto ServiceLevelObjective y pasarlo al método serviceLevelObjectives.create para crear un SLO mediante la API de SLO.

La estructura de un SLO tiene muchas estructuras incorporadas, entre las que se incluye una para el valor del campo serviceLevelIndicator.

  • Los SLI están predefinidos para Cloud Service Mesh, Istio en Google Kubernetes Engine y App Engine. Puedes usar la consola de Cloud Service Mesh para crear los SLO. Lo único que tienes que hacer es especificar los objetivos de rendimiento y los períodos de cumplimiento.

  • Para otros servicios, debes definir los SLO con la API de SLO. Si deseas especificar un SLO, también debes crear un valor para el campo serviceLevelIndicator. Consulta Crea un indicador de nivel de servicio para conocer algunas técnicas y Crea SLI a partir de métricas si quieres obtener un conjunto de ejemplos basados en varias fuentes.

También puedes crear SLI con la consola de Google Cloud. Para obtener más información, consulta Crea un SLO.

Esquema básico de un SLO

El esquema básico para crear el SLO es el 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.
}

Debes especificar lo siguiente:

  • Nombre visible: una descripción del SLO
  • Un indicador de nivel de servicio, que puede ser de tres tipos:
  • El objetivo de rendimiento (un porcentaje)
  • El período de cumplimiento, que puede ser de dos tipos:
    • Un período progresivo de cierta duración (en segundos)
    • Un período calendario

Para obtener más información sobre los SLI, los objetivos de rendimiento y los períodos de cumplimiento, consulta Conceptos de la supervisión de servicios.

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

Para otros servicios, debes crear un SLI basado en solicitudes o basado en ventanas. Consulta Crea un indicador de nivel de servicio para conocer algunas técnicas.

Ejemplo

Una vez que tengas el SLI, puedes compilar el SLO. En el siguiente ejemplo, se define un SLO para un servicio que usa un SLI básico. Es posible que tengas varios SLO en un solo SLI, por ejemplo, uno para una disponibilidad del 95% y otro correspondiente a una disponibilidad del 99%. El siguiente ejemplo es un SLO con una disponibilidad del 95% durante una semana calendario: 

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

En este ejemplo, se muestra un SLO con una disponibilidad del 75% durante un período progresivo de 3 días:

{
  "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 extremo https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives:

  1. Crea una variable para el ID del 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 SLO descritos antes:

    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 extremo:

    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

    De manera opcional, también puedes especificar un ID deseado para el SLO como valor del parámetro de búsqueda 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}

Borra un SLO

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

Protocolo

Para borrar un SLO mediante curl, envía una solicitud DELETE al https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID extremo:

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

Accede a series temporales de SLO

Los datos de SLO se almacenan en series temporales, por lo que puedes usar el método timeSeries.list para recuperarlos. Sin embargo, estos datos no se almacenan en tipos de métricas estándar; por lo tanto, no podrás usar el mecanismo estándar que consiste en especificar un filtro de tipo métrico al método timeSeries.list.

En su lugar, las series temporales de SLO se recuperan mediante la especificación de otro tipo de filtro, un selector de series temporales, en el método timeSeries.list del parámetro filter. Consulta Recupera los datos de SLO para obtener información sobre el uso de estos selectores.

También puedes usar selectores de series temporales para configurar políticas de alertas de manera programática. Para obtener más información, consulta Alertas sobre el ritmo de consumo.