Notas sobre la terminología

Distinguir entre términos superpuestos, como nombre, tipo, clase, métrica y recurso, te ayuda a interpretar la documentación de Cloud Monitoring y proporcionar los campos correctos en las solicitudes a la API de Cloud Monitoring. El uso casual suele difuminar la diferencia entre los tipos de métricas, los tipos de recursos supervisados, los tipos de valores, los tipos de métricas y los nombres de recursos de la API.

Términos comunes que se superponen

En los siguientes ejemplos, se ilustra cómo los términos y los identificadores de Monitoring suelen usarse indistintamente según el contexto:

  • El término métrica se puede usar, en diferentes contextos, para referirse a alguno de estos puntos:

    • Un "algo" general que se debe medir
    • Un tipo de métrica
    • Una serie temporal
    • Un conjunto de series temporales asociadas con un tipo de métrica
    • La estructura Metric incorporada en una estructura TimeSeries

  • Una string como storage.googleapis.com/api/request_count podría referirse a cualquiera de las siguientes opciones:

    • Una métrica
    • Un nombre de métrica
    • Un tipo de métrica
    • Un nombre del tipo de métrica

  • Una cadena como gcs_bucket se puede denominar de las siguientes maneras:

    • Un nombre de recurso1
    • Un recurso supervisado
    • Un tipo de recurso supervisado
    • Un nombre de recurso supervisado

1 El material de referencia de la API de REST también usa con frecuencia el término nombre del recurso, que, por lo general, no tiene nada que ver con los recursos supervisados. Este término se describe con más detalle en Nombres de recursos.

En el resto de este documento, se proporciona orientación sobre la terminología que puede resultar confusa.

Tipos y nombres

Los descriptores de tipos de métricas y recursos supervisados tienen nombres y tipos. Es común que el uso ocasional se utilicen los términos de forma indistinta.

Por ejemplo, la string storage.googleapis.com/api/request_count es un tipo de métrica, aunque también se conoce como nombre o tipo de nombre.

Si observas el descriptor de este tipo de métrica, verás estos dos pares clave-valor, name y type:

{
  "name": "projects/[PROJECT_ID]/metricDescriptors/storage.googleapis.com/api/request_count",
  ...
  "type": "storage.googleapis.com/api/request_count",
}

El type en un descriptor de métricas es una string que codifica información sobre el servicio que genera los datos (por ejemplo, storage.googleapis.com) y lo que se mide (api/request_count).

En un descriptor de métrica, el valor del campo name es la versión completamente calificada del tipo de métrica; el valor name es el valor type con el prefijo de esta cadena:

projects/[PROJECT_ID]/metricDescriptors/

Un patrón similar contiene los recursos supervisados. type es una etiqueta para alguna categoría de recurso, y name consiste en el valor del prefijo type con la siguiente string:

projects/[PROJECT_ID]/monitoredResourceDescriptors/

En el siguiente ejemplo, se corresponde a la entrada api en la lista de recursos supervisados:

{
  "type": "api",
  ...
  "name": "projects/[PROJECT_ID]/monitoredResourceDescriptors/api"
}

El valor de name dentro de un proyecto es completamente predecible respecto del valor de type, pero no son exactamente lo mismo. Sin embargo, los términos a menudo se usan de forma imprecisa en un debate informal.

Similares de métrica y tipo de valor

Existen otros dos términos que se pueden confundir con el “tipo de métrica”:

  • Tipo de valor
  • Categoría de métrica

Estos términos no son alternativos para “tipo de métrica”.

En “Tipo de valor” y “tipo de métrica”, se describen los datos recopilados. Ambos se relacionan con el concepto de programación “tipo de datos”.

  • El tipo de valor describe los valores individuales.
  • La categoría de métrica describe cómo se relacionan los valores entre sí.

Consulta Tipos de valores y clases de métricas para obtener más detalles.

Nombres de recursos

El patrón de creación de un valor name con el prefijo de una cadena para un valor type (u otro) se extiende mucho más allá de los tipos de métricas y recursos supervisados. Aparece con casi todo lo que crea datos de identificación única. Por ejemplo, tanto MetricDescriptor como AlertPolicy siguen este patrón.

El valor del campo name se suele describir en la documentación de referencia como un “nombre de recurso”:

Nombre del recurso en la referencia de la API

Estos son algunos ejemplos de algunas estructuras que tienen nombres de recursos y cómo se derivan:

  • Descriptores de métrica: une los valores del prefijo y del campo type:
    • Prefijo: projects/[PROJECT_ID]/metricDescriptors
    • type (muestra): storage.googleapis.com/api/request_count
    • name: projects/[PROJECT_ID]/metricDescriptors/storage.googleapis.com/api/request_count
  • Descriptores de recursos supervisados: une los valores del prefijo y del campo type:
    • Prefijo: projects/[PROJECT_ID]/monitoredResourceDescriptors
    • type (muestra): api
    • name: projects/[PROJECT_ID]/monitoredResourceDescriptors/api
  • Políticas de alertas: une los valores del prefijo y un ID generado:
    • Prefijo: projects/[PROJECT_ID]/alertPolicies
    • ID de política de alertas: un número generado cuando se creó la política
    • name: projects/[PROJECT_ID]/alertPolicies/[ALERT_POLICY_ID]

El término “nombre del recurso” hace referencia a un recurso en la jerarquía de la API de un servicio y no se relaciona con el concepto de recursos supervisados de ninguna manera. Para obtener más información sobre los nombres de recursos en el diseño de una API, consulta Nombres de recursos.