Visão geral de v1.traces

Este documento descreve por que recomendamos que você envie seus dados de trace para o Google Cloud projeto usando a API Telemetry (OTLP), que implementa o protocolo OTLP do OpenTelemetry. Ele também fornece orientações sobre como instrumentar seus aplicativos e onde você pode visualizar os dados de trace. É possível usar a API Telemetry ao instrumentar seus aplicativos usando um dos SDKs do OpenTelemetry ou ao usar um coletor do OpenTelemetry.

Recomendamos a API Telemetry pelo seguinte motivo:

  • A API oferece compatibilidade com o ecossistema de código aberto do OpenTelemetry, e os limites dela geralmente são mais generosos do que os da API Cloud Trace, que é uma API proprietária Google Cloud .

  • Os dados de trace são armazenados em um formato geralmente consistente com os arquivos proto definidos pelo protocolo OTLP do OpenTelemetry. Alguns campos podem ser convertidos de um tipo de dados específico do OpenTelemetry para um tipo de dados JSON antes do armazenamento. Para saber mais sobre o formato de armazenamento, consulte Esquema de dados de trace.

  • A instrumentação não depende de um Google Cloudexportador específico.

  • Alguns recursos, como o Application Monitoring, dependem de informações que só estão disponíveis quando você envia dados de trace para a API Telemetry.

O OpenTelemetry é um projeto de código aberto com Google Cloudsuporte e Google Cloud engenheiros para garantir o suporte à ingestão e visualização da telemetria.

O Google Cloud Observability verifica se a API Cloud Trace está ativada no seu Google Cloud projeto antes de armazenar dados de trace. Isso significa que, se você desativar a API Cloud Trace, o Google Cloud Observability vai descartar os dados de trace enviados para a API Telemetry.

Práticas recomendadas

Ao instrumentar seus aplicativos para enviar dados de trace ao Google Cloud projeto, recomendamos que você use um exportador que grave dados formatados em OTLP em um Coletor, que envia os dados de trace 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 trace ou métricas para a API Telemetry, consulte os seguintes documentos:

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 trace 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 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 trace, consulte Configurar a autenticação. Este exemplo ilustra como configurar o exportador com as Google Cloud Credenciais Padrão do Aplicativo (ADC) e adicionar uma biblioteca de autenticação do Google específica do idioma ao aplicativo.

Cloud Trace e residência de dados

Se você estiver usando 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 trace ao projeto.

Onde visualizar os dados ingeridos

É possível visualizar os dados de trace usando as páginas Explorador de traces e Análise de observabilidade. Para mais informações, consulte: