Visão geral da API Telemetry (OTLP)

Este documento descreve a API de telemetria (OTLP), que implementa o protocolo OTLP do OpenTelemetry. Essa API foi projetada para uso com aplicativos instrumentados usando um dos SDKs do OpenTelemetry ou que usam qualquer coletor 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.

Dados de rastreamento e a API Telemetry

Esta seção fornece informações sobre a API Telemetry e os rastreamentos.

Por que usar a API Telemetry

Ao usar a API Telemetry, seus dados são armazenados em um formato geralmente consistente com os arquivos proto definidos pelo protocolo OTLP do OpenTelemetry. No entanto, os campos podem ser convertidos de um tipo de dados específico do OpenTelemetry para um tipo de dados JSON antes do armazenamento. Além disso, os limites da API Telemetry se aplicam. Esses limites geralmente são mais generosos do que os da API Cloud Trace. Por fim, sua instrumentação não depende de um exportador específico do Google Cloud.

Para saber mais sobre o formato de armazenamento, consulte Esquema para dados de rastreamento.

Quando usar a API Telemetry

Recomendamos enviar os dados de rastreamento para seu projeto Google Cloud usando a API Telemetry. Essa API oferece compatibilidade com o ecossistema de código aberto OpenTelemetry, e os limites dela costumam ser mais generosos do que os da API Cloud Trace, que é uma APIGoogle Cloud proprietária. Alguns recursos, como o Application Monitoring, dependem de informações que estão disponíveis apenas quando os dados de rastreamento são enviados à API Telemetry.

Ao instrumentar seus aplicativos para enviar dados de rastreamento ao seu projetoGoogle Cloud , recomendamos que você faça uma das seguintes ações:

• Use um exportador que grava OTLP em um coletor, que envia os dados de rastreamento para a API Telemetry.
• Use um exportador OTLP no processo compatível com uma biblioteca OpenTelemetry que envia telemetria para a API Telemetry. Não há um coletor com essa configuração.

Para informações sobre como usar a API Telemetry, consulte Migrar do exportador do Cloud Trace para o endpoint OTLP.

Autenticação

Os exportadores precisam estar autorizados a enviar dados para o projeto Google Cloud . Por exemplo, é possível configurar o exportador com suas credenciais padrão do aplicativo (ADC) Google Cloudadicionando uma biblioteca de autenticação do Google específica da linguagem ao aplicativo. Para mais informações e exemplos de código, consulte Configurar a autenticação.

Cloud Trace e residência de dados

Se você estiver usando o Assured Workloads porque tem requisitos de residência de dados ou nível de impacto 4 (IL4), não use a API Telemetry para enviar intervalos de rastreamento.

Dados de métricas e a API Telemetry

Esta seção descreve como o Cloud Monitoring processa métricas ingeridas usando o exportador otlphttp e um coletor do OpenTelemetry ou por aplicativos instrumentados usando um dos SDKs do OpenTelemetry.

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 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 valores 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 valores 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
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, 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.

Onde visualizar os dados ingeridos

Os dados de rastreamento ingeridos pela API Telemetry podem ser visualizados usando a página Explorador de rastreamento. Para informações sobre como visualizar os dados de trace, consulte:

• Encontrar e analisar traces.
• Consultar e analisar traces.

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.

Suporte do VPC Service Controls

O serviço da API Telemetry, cujo nome é telemetry.googleapis.com, é compatível com o VPC Service Controls. Todas as restrições do VPC Service Controls criadas para o serviço da API Telemetry se aplicam somente a esse serviço. Essas restrições não se aplicam a outros serviços, incluindo o cloudtrace.googleapis.com, que também pode ingerir dados de rastreamento.

Para ver mais informações, consulte os seguintes tópicos:

• Documentação do VPC Service Controls.
• Produtos e limitações compatíveis.