Visão geral de v1.metrics

Neste documento, descrevemos como os dados de métricas enviados do seu projeto Google Cloud usando a API Telemetry (OTLP) são mapeados para as estruturas do Cloud Monitoring. Essa API implementa o protocolo OTLP do OpenTelemetry. É possível enviar dados para essa API ao instrumentar seus aplicativos com um exportador otlphttp e um coletor do OpenTelemetry, ou ao usar os SDKs do OpenTelemetry.

O OpenTelemetry é um projeto de código aberto compatível com o Google Cloude com engenheiros do Google Cloudpara garantir o suporte à ingestão e visualização da sua telemetria.

Métricas OTLP no Cloud Monitoring

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Quando as métricas são ingeridas no Cloud Monitoring usando um coletor do OpenTelemetry e o exportador otlphttp ou enviadas diretamente usando um SDK do OpenTelemetry, as métricas OTLP são mapeadas para estruturas de métricas do Cloud Monitoring. Esta seção descreve:

• O mapeamento entre recursos OTLP e recursos monitorados do Cloud Monitoring.
• O mapeamento entre métricas OTLP e do Cloud Monitoring.

Mapeamento de recursos monitorados

Todos os pontos de métrica são gravados como estão para o Google Cloud Managed Service para Prometheus usando o mapeamento do Prometheus.

Mapeamento do Prometheus

As métricas do Prometheus exigem o uso do tipo de recurso monitorado prometheus_target.

Os seguintes rótulos no tipo de recurso prometheus_target são usados para esquematizar e armazenar dados com eficiência no Monarch. Quanto mais precisos forem os valores especificados para esses atributos, melhor será a capacidade de consulta e a escalonabilidade.

Recomendamos que você seja o mais explícito possível ao definir valores para esses rótulos, embora tenhamos implementado uma lógica de substituição para uso na ausência de valores explícitos.

A tabela a seguir mostra as fontes de valores para rótulos, em ordem de prioridade:

Rótulo prometheus-target	Valor usado (em ordem de prioridade)
location (obrigatório)	Atributo location Atributo cloud.availability_zone Atributo cloud.region
cluster	Atributo cluster Atributo k8s.cluster.name __gce__, se o atributo cloud.platform for gcp_compute_engine __run__, se o atributo cloud.platform for gcp_cloud_run String em branco
namespace	Atributo namespace Atributo k8s.namespace.name Atributo service.namespace String em branco
job	Atributo job "service.namespace" + "/" + atributo service.namespace Atributo service.name Atributo service.name, se não for unknown_service:foo Atributo faas.name Atributo k8s.deployment.name Atributo k8s.statefulset.name Atributo k8s.job.name Atributo k8s.cronjob.name Atributo service.name, se unknown_service:foo String em branco
instance Rejeitar o ponto se estiver vazio	Atributo instance Atributo service.instance.id Atributo faas.instance Atributo k8s.pod.name:k8s.container.name Atributo k8s.pod.name, se nenhum nome de contêiner estiver presente Atributo host.id

Mapeamento de métricas

As métricas são convertidas para o formato de série temporal do Prometheus. Os nomes de métricas não podem ter domínio ou precisam ter o domínio prometheus.googleapis.com. Após a conversão, o nome da métrica vai incluir o prefixo prometheus.googleapis.com e um sufixo adicional, com base no tipo de ponto OTLP. A métrica resultante do Cloud Monitoring tem a seguinte estrutura:

prometheus.googleapis.com/{metric_name}/{suffix}

Além disso, para cada recurso exclusivo do OpenTelemetry, a conversão adiciona uma métrica target_info que contém todos os atributos de recurso, exceto service.name, service.instance.id e service.namespace.

Todas as métricas INT64 do OTLP são traduzidas para o tipo de valor DOUBLE no Cloud Monitoring, mesmo que o coletor especifique o tipo de valor como INT64. Essa mudança é feita porque, depois que uma série temporal está no Monarch, não é possível mudar o tipo de valor. A consequência mais comum de oferecer suporte a valores de INT64 é que você acaba tendo colisões que só podem ser resolvidas excluindo uma métrica.

Observação: esperamos que haja possíveis colisões de tipo de valor, principalmente se você já tiver enviado métricas INT64 target_info. Se você encontrar colisões, a melhor solução de longo prazo é excluir o descritor de métrica das métricas INT64 target_info. Para excluir esse descritor do escopo de métricas, use este script Golang.

Mapeamento de métricas do Prometheus

Os tipos de métricas são mapeados da seguinte forma:

• O medidor OTLP é mapeado para o medidor do Cloud Monitoring.
• O OTLP Sum é mapeado da seguinte forma:
  • Para o medidor do Cloud Monitoring quando is_monotonic é definido como false.
  • Para o Cloud Monitoring cumulativo quando aggregation_temporality é definido como AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Para delta do Cloud Monitoring quando aggregation_temporality é definido como AGGREGATION_TEMPORALITY_DELTA.
• O histograma OTLP é mapeado para a distribuição do Cloud Monitoring com um tipo de métrica cumulativo ou delta, dependendo do valor de aggregation_temporality.
• As métricas de resumo do OTLP são expandidas em série temporal individuais para cada componente: count, sum e cada quantile.
  • Os nomes das métricas de contagem e soma são sufixados com _count ou _sum, respectivamente, e são gravados como métricas cumulativas do Cloud Monitoring do tipo DOUBLE.
  • Cada quantil se torna uma série temporal de medidor do tipo DOUBLE, com um rótulo quantile.

A tabela a seguir resume o mapeamento de métricas:

Tipo de ponto do OTLP	Tipo de métrica do Monitoring	Tipo de valor do Monitoring	Sufixo	Observações
MEDIDOR	MEDIDOR	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	MEDIDOR	DOUBLE	/unknown	Os valores desconhecidos do Prometheus são divididos em um contador e um medidor pelo Coletor do OpenTelemetry.
SUM (monotonic, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE	DOUBLE	/unknown:counter	Os valores desconhecidos do Prometheus são divididos em um contador e um medidor pelo Coletor do OpenTelemetry.
SOMA (monotônica, DELTA)	DELTA	DOUBLE	/delta
SUM (não monotônica, CUMULATIVE)	MEDIDOR	DOUBLE	/gauge
HISTOGRAMA (CUMULATIVO)	CUMULATIVE	DISTRIBUTION com buckets explícitos	/histogram
HISTOGRAMA EXPONENCIAL (CUMULATIVO)	CUMULATIVE	DISTRIBUTION com buckets exponenciais	/histogram
HISTOGRAMA (DELTA)	DELTA	DISTRIBUTION com buckets explícitos	/histogram:delta
HISTOGRAMA EXPONENCIAL (DELTA)	DELTA	DISTRIBUTION com buckets exponenciais	/histogram:delta
SUMMARY (sum, count, quantile)	CUMULATIVE CUMULATIVE GAUGE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	Os pontos de dados de resumo são gravados como várias série temporal, uma para contagem, soma e cada quantil calculado. As métricas de quantil também são geradas com um rótulo quantile.

Diferenças entre o exportador googlemanagedprometheus e a API Telemetry

A API Telemetry (telemetry.googleapis.com) processa as métricas de maneira diferente do exportador googlemanagedprometheus:

• A API Telemetry permite o uso de ponto (.) e barra (/) em nomes de métricas. O exportador googlemanagedprometheus converte todas as instâncias desses caracteres no caractere de sublinhado (_). Por exemplo, uma métrica OTLP chamada prometheus.googleapis.com/foo.bar/gauge é exportada literalmente pelo exportador OTLP, mas é exportada como prometheus.googleapis.com/foo_bar/gauge pelo exportador googlemanagedprometheus.

  Quando as métricas são ingeridas, o Cloud Monitoring cria descritores de métricas com base nos nomes. A diferença na forma como o ponto (.) e a barra (/) são processados pelos caminhos de ingestão significa que os descritores de métricas resultantes são diferentes entre as métricas ingeridas usando o exportador googlemanagedprometheus e aquelas ingeridas usando o exportador otlphttp. Se você usar os dois caminhos de ingestão, terá dois conjuntos de métricas. Para receber resultados completos ao consultar, é necessário unir manualmente os resultados das versões do Prometheus e do OTLP das métricas.

• A API Telemetry não anexa uma unidade a um nome de métrica quando uma unidade está presente, nem anexa um sufixo _total aos contadores. Portanto, uma métrica exportada como prometheus.googleapis.com/foo/counter ao usar a API Telemetry é exportada como prometheus.googleapis.com/foo_seconds_total/counter pelo exportador googlemanagedprometheus. Essa diferença também se aplica aos sufixos _total e _ratio.

• A API sintetiza o valor sum_of_squared_deviation para valores de distribuição derivados de histogramas exponenciais. O exportador googlemanagedprometheus não define esse campo para histogramas exponenciais.

• A API converte todos os valores de ponto inteiro em valores de ponto duplo para métricas do Prometheus.

• A API não define os rótulos scope_version ou scope_name se eles tiverem valores vazios.

Onde conferir os dados ingeridos

Os dados de métricas ingeridos pela API Telemetry podem ser visualizados na página Metrics Explorer. Para informações sobre como visualizar e criar gráficos com seus dados de métricas, consulte Criar gráficos com o Metrics Explorer.