Visão geral de v1.metrics

Este documento descreve como os dados de métricas enviados ao seu Google Cloud projeto usando a API Telemetry (OTLP) são mapeados para as estruturas do Cloud Monitoring. Essa API implementa o protocolo de linha 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 com Google Cloudsuporte e Google Cloud engenheiros dedicados para garantir o suporte à ingestão e visualização da sua telemetria.

Práticas recomendadas

Ao instrumentar seus aplicativos para enviar dados de rastreamento ao seu Google Cloud projeto, recomendamos que você use um exportador que grave dados formatados em OTLP em um Coletor, que envia os dados de rastreamento para a API Telemetry. No 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 dos exemplos de instrumentação baseados em coletores.
• Visão geral da ingestão de métricas OTLP.

Quando não for 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

É necessário configurar os exportadores com as credenciais necessárias para enviar dados ao seu Google Cloud projeto. Por exemplo, ao usar coletores, normalmente você também usa a extensão googleclientauth para autenticar com as 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 métricas 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 rótulos a seguir no tipo de recurso prometheus_target são usados para esquematizar e armazenar dados com eficiência no Monarch. Quanto mais precisamente você especificar valores para esses atributos, melhor será a capacidade de consulta e 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 fallback 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" + "/" + service.namespace atributo 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 das métricas não podem ter domínio ou 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 target_info métrica 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 DOUBLE tipo de valor 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 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 para as métricas INT64 target_info. Para excluir este descritor do escopo de métricas, use este script do Golang.

Mapeamento de métricas do Prometheus

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

• O medidor OTLP é mapeado para o medidor do Cloud Monitoring gauge.
• A soma OTLP é mapeada da seguinte maneira:
  • Para o medidor do Cloud Monitoring quando is_monotonic está definido como false.
  • Para o cumulativo do Cloud Monitoring quando aggregation_temporality está definido como AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Para o delta do Cloud Monitoring quando aggregation_temporality está 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 sua própria 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 OTLP	Tipo de métrica do Monitoring	Tipo de valor do Monitoring	Sufixo	Observações
GAUGE	GAUGE	DOUBLE	/gauge
MEDIDOR (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	Os desconhecidos do Prometheus são divididos em um contador e um medidor pelo coletor do OpenTelemetry.
SUM (monotônico, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SUM (monotônico, 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ônico, DELTA)	DELTA	DOUBLE	/delta
SUM (não monotônico, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUM (não monotônico, DELTA)	indisponível			UpDownCounters de temporalidade delta não são compatíveis.
HISTOGRAMA (CUMULATIVE)	CUMULATIVE	DISTRIBUTION com buckets explícitos	/histogram
HISTOGRAMA EXPONENCIAL (CUMULATIVE)	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
RESUMO (soma, contagem, quantil)	CUMULATIVE CUMULATIVE MEDIDOR	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 quantile rótulo.

Diferenças entre o exportador googlemanagedprometheus e a API Telemetry

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

• A API Telemetry permite os caracteres de ponto (.) e barra (/) em nomes de métricas. O exportador googlemanagedprometheus converte todas as instâncias desses caracteres para o 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 os caracteres de ponto (.) e barra (/) são processados pelos caminhos de ingestão significa que os descritores de métricas resultantes diferem entre as métricas ingeridas usando o exportador googlemanagedprometheus e aquelas ingeridas usando o otlphttp exportador. 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 e não 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 do Cloud Monitoring.

Onde visualizar os dados ingeridos

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