Visão geral de v1.metrics

Neste documento, descrevemos como os dados de métricas enviados pelo 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.

Práticas recomendadas

Ao instrumentar seus aplicativos para enviar dados de rastreamento ao projetoGoogle Cloud , recomendamos usar um exportador que grava dados formatados em OTLP em um coletor, que envia os dados de rastreamento à API Telemetry. No seu coletor, especifique apenas o URL raiz:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

O OpenTelemetry detecta o tipo de dados e anexa automaticamente /v1/traces, /v1/metrics ou /v1/logs, conforme apropriado. Para mais informações, consulte Solicitação OTLP/HTTP.

Para exemplos que exportam dados de rastreamento ou métricas para a API Telemetry, consulte os seguintes documentos:

• Visão geral das amostras de instrumentação baseadas em coletores.
• Visão geral da ingestão de métricas OTLP.

Quando não é possível usar um coletor, use uma biblioteca do OpenTelemetry que contenha um exportador OTLP no processo para enviar telemetria à API Telemetry. Para saber como exportar dados de rastreamento diretamente, consulte Exportador do Cloud Trace para o endpoint OTLP.

Autenticação

Configure os exportadores com as credenciais necessárias para enviar dados ao seu projeto Google Cloud . Por exemplo, ao usar coletores, normalmente você também usa a extensão googleclientauth para autenticar com credenciais do Google.

Para um exemplo de autenticação ao usar a exportação direta de dados de rastreamento, consulte Configurar a autenticação. Este exemplo ilustra como configurar o exportador com suas Google Cloud Application Default Credentials (ADC) e adicionar uma biblioteca de autenticação do Google específica do idioma ao seu aplicativo.

Métricas OTLP no Cloud Monitoring

Este recurso está sujeito aos Termos das Soluções 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 suporte limitado. Para mais informações, consulte as descrições da fase 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 Rejeitar o ponto se estiver vazio
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 (obrigatório)	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 Rejeitar o ponto se estiver vazio

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 a 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 o 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 desconhecidos do Prometheus são divididos em um contador e um medidor pelo Coletor do OpenTelemetry.
SUM (monotônica, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE	DOUBLE	/unknown:counter	Os desconhecidos do Prometheus são divididos em um contador e um medidor pelo Coletor do OpenTelemetry.
SUM (monotônica, DELTA)	DELTA	DOUBLE	/delta
SUM (não monotônica, CUMULATIVE)	MEDIDOR	DOUBLE	/gauge
SUM (não monotônica, DELTA)	incompatível			UpDownCounters de temporalidade delta não são compatíveis.
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 duplos para métricas do Prometheus.

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

Cloud Monitoring e residência de dados

Para saber como os dados de métricas são armazenados, consulte Regionalidade de dados para o Cloud Monitoring.

Onde visualizar 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.