Trabaja con la API

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

En esta página, se muestran los usos principales de los recursos nuevos de la API. Para obtener una descripción general de las estructuras utilizadas aquí, consulta Construcciones en la API. El material de referencia completo aparece en la API de Cloud Monitoring v3.

En este documento, se hace referencia de forma colectiva a estas adiciones, como la API de Service Monitoring.

Cuándo usar la API

La API de Service Monitoring se puede usar para administrar servicios y objetivos de nivel de servicio (SLO). Esta página se enfoca en los servicios personalizados y los indicadores de nivel de servicio (SLI). Los servicios que se ejecutan en App Engine, Istio en Google Kubernetes Engine y Cloud Endpoints se detectan automáticamente, y sus SLI están predefinidos:

  • A fin de definir los SLO para los servicios de Anthos Service Mesh, puedes usar la consola de Anthos Service Mesh o la API de Service Monitoring. Para obtener más información sobre cómo crear los SLO mediante el panel de la malla de servicios de Anthos, consulta la documentación de la malla de servicios de Anthos: Crea SLO.

  • Para otros servicios y servicios personalizados, debes definir los SLO con la API de Service Monitoring. Actualmente no hay asistencia disponible de Google Cloud Console.

Los ejemplos de la página se enfocan principalmente en los servicios personalizados y los SLI.

Identificadores válidos

Varios métodos de la API de Service Monitoring utilizan identificadores para diferentes elementos, en particular 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 de uso de curl

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

Los ejemplos de esta página acceden a la API de Service Monitoring mediante la herramienta curl para 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 usadas en las invocaciones.

Autenticación

  1. Crea una variable de entorno para retener el ID de tu lugar de trabajo de Cloud Monitoring. En estos ejemplos, se usa PROJECT_ID:

    PROJECT_ID=my-test-service
    
  2. Realiza la autenticación en el SDK de Cloud:

    gcloud auth login
    
  3. Para no tener que especificar tu ID del proyecto con cada comando, configúralo como predeterminado con el SDK de Cloud:

    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 curl incluye un conjunto de argumentos, seguido de la URL de un recurso de la API de Service Monitoring. 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

Esta solicitud muestra un arreglo de descripciones de servicio con entradas como las siguientes; un servicio de Istio llamado “currencyservice”:

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

Consulta Service para obtener más información sobre la estructura de un servicio.

Administrar 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.

Los servicios en App Engine, Istio en Google Kubernetes Engine y Cloud Endpoints se crean automáticamente para ti. Puedes realizar tareas, como agregar los SLO a estos servicios, mediante la consola de la malla de servicios de Anthos o la API de Service Monitoring.

Los servicios que creas manualmente se llaman servicios personalizados. Los servicios personalizados se pueden crear, borrar, recuperar y actualizar únicamente a través de la API de Service Monitoring.

Después de identificar o crear un servicio, puedes agregarle los SLO. 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}

Crea un servicio

Si no usas un entorno en el que los servicios se creen automáticamente (es decir, App Engine, Istio en Google Kubernetes Engine y Cloud Endpoints), puedes crear servicios con el método services.create.

Si creas servicios de forma manual, deberás agregar los SLO y otros artefactos de supervisión de servicios a la estructura del servicio de forma manual mediante la API de Service Monitoring. Para obtener una descripción general de estas estructuras, consulta Construcciones en la API.

Si deseas crear un servicio, deberás especificar un nombre comercial del servicio y un campo llamado custom con un objeto vacío. De forma opcional, puedes especificar el ID que quieras para tu servicio.

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 Service",
        "custom": {}
    }
    EOF
    )
    
  3. Publica el cuerpo de la solicitud en el extremo y especifica el ID del servicio como valor del parámetro de búsqueda 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}
    

Borra un servicio

Para borrar un servicio personalizado, 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

Los SLO están asociados con los servicios. Puedes crear SLO a través de la consola de la malla de servicios de Anthos para App Engine, Istio en Google Kubernetes Engine y Cloud Endpoints, o mediante la API de Service Monitoring. Debes usar la API de Service Monitoring a fin de crear SLO para servicios personalizados.

También puedes usar la API de Service Monitoring para recuperar los SLO asociados con un servicio y borrar los SLO de un 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. La sección ID del servicio describe cómo reconocer los ID del 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 a través del envío de 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

Para crear un SLO con la API de Service Monitoring, debes crear un objeto ServiceLevelObjective y pasarlo al método serviceLevelObjectives.create.

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

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

    También puedes definir los SLO con la API de Service Monitoring.

  • En el caso de los servicios personalizados, debes definir los SLO con la API de Service Monitoring. Para 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.

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 los siguientes campos:

  • Nombre comercial: 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 en la supervisión de servicios.

Para los servicios de App Engine, Istio en Google Kubernetes Engine y Cloud Endpoints, el tipo de SLI es el SLI básico.

Para los servicios personalizados, debes crear un SLI basado en solicitudes o en Windows. 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 retener el cuerpo de la solicitud; una instancia del objeto ServiceLevelObjective. En este ejemplo, se usa uno de los SLO ya descritos:

    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 utilizar 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.