Construcciones en la API

En este documento, se presentan las estructuras usadas para representar servicios y SLO en la API del SLO, además de mapearlos a los conceptos descritos en general en Conceptos de la supervisión de servicios.

La API del SLO se usa para configurar objetivos de nivel de servicio (SLO) y se puede usar a fin de supervisar el estado de tus servicios.

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

Para obtener información sobre cómo invocar la API, consulta Trabaja con la API.

Servicios

Un servicio se representa con un objeto Service. En este objeto, se incluyen los siguientes campos:

  • Un nombre: Es un nombre de recurso completamente calificado para este servicio
  • Un nombre visible: Es una etiqueta que se usa en los componentes de la consola
  • Una estructura para uno de los tipos BasicService.
  • Un objeto de configuración de telemetría que proporciona el sistema

Para definir un servicio básico, especifica el tipo de servicio y proporciona un conjunto de etiquetas específicas del servicio que describen el servicio:

{
   "serviceType": string,
   "serviceLabels": {
      string: string,
      ...
   }
}

En las siguientes secciones, se proporcionan ejemplos para cada tipo de servicio.

Tipos de servicios básicos

En esta sección, se proporcionan ejemplos de definiciones de servicios compiladas en el tipo BasicService, en el que el valor del campo serviceType es uno de los siguientes:

  • APP_ENGINE
  • CLOUD_ENDPOINTS
  • CLUSTER_ISTIO
  • ISTIO_CANONICAL_SERVICE
  • CLOUD_RUN

Cada uno de estos tipos de servicios usa el indicador de nivel de servicio BasicSli.

App Engine 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "APP_ENGINE",
          "serviceLabels": {
            "module_id": "MODULE_ID"
          },
      },
    }

Cloud Endpoints 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_ENDPOINTS",
          "serviceLabels": {
            "service": "SERVICE"
          },
      },
    }

Clúster de Istio 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLUSTER_ISTIO",
          "serviceLabels": {
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "service_namespace": "SERVICE_NAMESPACE",
            "service_name": "SERVICE_NAME"
          },
      },
    }

Servicio canónico de Istio 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "ISTIO_CANONICAL_SERVICE",
          "serviceLabels": {
            "mesh_uid": "MESH_UID",
            "canonical_service_namespace": "CANONICAL_SERVICE_NAMESPACE",
            "canonical_service": "CANONICAL_SERVICE"
          },
      },
    }

Cloud Run 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_RUN",
          "serviceLabels": {
            "service_name": "SERVICE_NAME",
            "location": "LOCATION"
          },
      },
    }

Tipos de servicios básicos de GKE

En esta sección, se incluyen ejemplos de definiciones de servicios de GKE compiladas en el tipo BasicService, en el que el valor del campo serviceType es uno de los siguientes:

  • GKE_NAMESPACE
  • GKE_WORKLOAD
  • GKE_SERVICE

Debes definir los SLI para estos tipos de servicios. No pueden usar indicadores de nivel de servicio BasicSli. Para obtener más información, consulta Indicadores de nivel de servicio.

Espacio de nombres de GKE 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_NAMESPACE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME"
          }
      },
    }

Carga de trabajo de GKE 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_WORKLOAD",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "top_level_controller_type": "TOPLEVEL_CONTROLLER_TYPE",
            "top_level_controller_name": "TOPLEVEL_CONTROLLER_NAME",
          }
      },
    }

Servicio de GKE 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_SERVICE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "service_name": "SERVICE_NAME"
          }
      },
    }

Servicios personalizados

Si ninguno de los tipos de servicios básicos es adecuado puedes crear servicios personalizados. Un servicio personalizado se ve de la siguiente manera:

    {
      "displayName": "DISPLAY_NAME",
      "custom": {}
    }

Debes definir los SLI para estos tipos de servicios. No pueden usar indicadores de nivel de servicio BasicSli. Para obtener más información, consulta Indicadores de nivel de servicio.

Indicadores de nivel de servicio

Un indicador de nivel de servicio (SLI) proporciona una medida del rendimiento de un servicio. Un SLI se basa en la métrica que capturó el servicio. La forma exacta en la que se define el SLI depende del tipo de métrica que se use como métrica del indicador, pero, por lo general, es una comparación entre los resultados aceptables y los totales.

Un SLI se representa con el objeto ServiceLevelIndicator. Este objeto es una forma colectiva de hacer referencia a los tres tipos compatibles de SLI:

  • Un SLI básico, que se crea automáticamente para las instancias del tipo de servicio BasicService. Este tipo de SLI se describe en Objetivos de nivel de servicio; se representa con un objeto BasicSli y mide la disponibilidad o la latencia

  • Un SLI basado en solicitudes, que puedes usar para registrar eventos que representan un servicio aceptable. El uso de este tipo de SLI se describe en SLO basados en solicitudes; se representa con un objeto RequestBasedSli

  • Un SLI basado en una ventana, que puedes usar para contar los períodos de tiempo que cumplen con algún criterio de calidad. El uso de este tipo de SLI se describe en  SLO basados en Windows; se representa con un objeto WindowsBasedSli

Por ejemplo, a continuación se muestra un SLI de disponibilidad básica:

{
  "basicSli": {
    "availability": {},
    "location": [
      "us-central1-c"
    ]
  }
}

Estructuras para SLI basados en solicitudes

Un SLI basado en solicitudes se basa en una métrica que cuenta las unidades de servicio como una proporción entre un resultado específico y el total. Por ejemplo, si usas una métrica que cuenta solicitudes, puedes crear la proporción entre la cantidad de solicitudes correctas y la cantidad total de solicitudes.

Existen dos maneras de crear un SLI basado en solicitudes:

  • Como TimeSeriesRatio, cuando la proporción entre servicio de calidad y servicio total se calcula a partir de dos series temporales cuyos valores tienen un tipo de métrica de DELTA o CUMULATIVE
  • Como DistributionCut, cuando la serie temporal tiene el tipo de valor DISTRIBUTION y cuyos valores tienen un tipo de métrica de DELTA o CUMULATIVE El valor de servicio de calidad es el recuento de los elementos que pertenecen a los depósitos de histogramas en un rango especificado, y el total es el recuento de todos los valores en la distribución.

A continuación, se muestra la representación JSON de un SLI que usa una proporción de serie temporal:

{
  "requestBased": {
    "goodTotalRatio": {
      "totalServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count"",
      "goodServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count" metric.label.response_code_class=200",
    }
  }
}

Las series temporales en esta proporción se identifican por el par de tipo de recurso supervisado y tipo de métrica:

  • Recurso: https_lb_rule
  • Tipo de métrica: loadbalancing.googleapis.com/https/request_count

El valor de totalServiceFilter se representa mediante el par del tipo de métrica y de recurso. El valor de goodServiceFilter se representa mediante el mismo par, pero en el que una etiqueta tiene un valor particular. En este caso, cuando el valor de la etiqueta response_code_class es 200.

La proporción entre los filtros mide la cantidad de solicitudes que muestran un estado HTTP 2xx en función de la cantidad total de solicitudes.

A continuación, se muestra la representación JSON de un SLI que usa un corte de distribución:

{
  "requestBased": {
    "distribution_cut": {
      "distribution_filter": "resource.type=https_lb_rule  metric.type="loadbalancing.googleapis.com/https/backend_latencies" metric.label.response_code_class=200",
      "range": {
        "min": "-Infinity",
        "max": 500.0
      }
    }
  }
}

La serie temporal se identifica por el tipo de recurso supervisado, el tipo de métrica y el valor de una etiqueta de métrica:

  • Recurso: https_lb_rule
  • Tipo de métrica: loadbalancing.googleapis.com/https/backend_latencies
  • Par de valor de etiqueta: response_code_class = 200

El rango de latencias que se considera de calidad se designa mediante el campo range. Este SLI calcula la proporción entre latencias de respuestas de clase 2xx por debajo de 500 y las latencias de todas las respuestas de clase 200.

Estructuras para SLI basados en ventanas

Un SLI basado en ventanas cuenta los períodos en los que el servicio proporcionado se considera de calidad. El criterio para determinar qué tan bueno es el servicio es parte de la definición del SLI.

Todos los SLI basados en ventanas incluyen un período de ventana, entre 60 y 86,400 segundos (1 día).

Existen dos maneras de especificar un criterio de un servicio de calidad para un SLI basado en ventanas:

  • Crea una string de filtro, descrita en Filtros de supervisión, que muestra una serie temporal con valores booleanos. Una ventana es de calidad si su valor es de true. A este filtro se lo denomina goodBadMetricFilter.

  • Crea un objeto PerformanceThreshold que represente un límite de rendimiento aceptable. Este objeto se especifica como el valor de goodTotalRatioThreshold.

    Un objeto PerformanceThreshold especifica un valor de límite y un SLI de rendimiento. Si el valor del SLI de rendimiento alcanza o supera el valor de límite, el período se considera de calidad.

    Existen dos formas de especificar el SLI de rendimiento:

A continuación, se muestra la representación JSON de un SLI basado en ventanas según el límite de rendimiento de un SLI de disponibilidad básico:

{
  "windowsBased": {
     "goodTotalRatioThreshold": {
       "threshold": 0.9,
       "basicSliPerformance": {
         "availability": {},
         "location": [
           "us-central1-c"
         ]
       }
     },
     "windowPeriod": "300s"
   }
}

Este SLI especifica un buen rendimiento como una ventana de 5 minutos en la que la disponibilidad alcanza el 90% o más. La estructura de un SLI básico se muestra en Indicadores de nivel de servicio.

También puedes incorporar un SLI basado en solicitudes en el SLI basado en ventanas. A fin de obtener más información sobre las estructuras incorporadas, consulta Estructuras para los SLI basados en solicitudes.

Objetivos de nivel de servicio

Un objetivo de nivel de servicio (SLO) se representa con un objeto ServiceLevelObjective. Este objeto incluye los siguientes campos:

  • Un nombre
  • Un nombre visible
  • El SLI objetivo; un objeto ServiceLevelIndicator incorporado
  • El objetivo de rendimiento del SLI
  • El período de cumplimiento del SLI

A continuación, se muestra la representación JSON de un SLO que usa un SLI de disponibilidad básico como el valor del campo serviceLevelIndicator:

{
   "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
   "serviceLevelIndicator": {
     "basicSli": {
       "availability": {},
       "location": [
         "us-central1-c"
       ]
     }
   },
   "goal": 0.98,
   "calendarPeriod": "WEEK",
   "displayName": "98% Availability in Calendar Week"
}

Mediante este SLO, se configura el objetivo de rendimiento con una disponibilidad del 98% durante un período de una semana.