Visão geral de v1.traces

Este documento descreve por que recomendamos que você envie seus dados de trace para o seu Google Cloud projeto usando a API Telemetry (OTLP), que implementa o protocolo 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 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 costumam ser 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 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 Google Cloudcom Google Cloud suporte de engenheiros para garantir a ingestão e visualização da telemetria.

O Cloud Observability do Google Cloud 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 Cloud Observability do Google Cloud 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ê usa a extensão googleclientauth para fazer a autenticação 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, na sigla em inglês) e adicionar uma biblioteca de autenticação do Google específica do idioma ao aplicativo.

Para enviar dados de telemetria ao seu Google Cloud projeto usando a API Telemetry, você também precisa fazer o seguinte:

  • Configurar um projeto de cota. Para saber mais, consulte Definir o projeto de cota.

  • Conceda os seguintes papéis do Identity and Access Management (IAM, na sigla em inglês) ao usuário ou à conta de serviço usada pelo 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:

Cotas

Para informações sobre cotas associadas à API Telemetry, consulte Limites da API Telemetry.