Visão geral da API Telemetry (OTLP)

Este documento descreve a API Telemetry (OTLP), que implementa o protocolo de linha do OpenTelemetry. Essa API foi projetada para uso com aplicativos instrumentados usando um dos os SDKs do OpenTelemetry ou que usam qualquer coletor do OpenTelemetry.

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

Para saber mais sobre essa API, consulte os seguintes documentos de referência:

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 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 trace, 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 aplicativo.

Suporte do VPC Service Controls

O serviço da API Telemetry, cujo nome é telemetry.googleapis.com, é um serviço com suporte do VPC Service Controls. Todas as restrições do VPC Service Controls criadas para o serviço da API Telemetry se aplicam apenas a esse serviço. Essas restrições não se aplicam a outros serviços, incluindo aqueles como o serviço cloudtrace.googleapis.com, que também podem ingerir dados de trace.

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

Endpoints de Serviço

Um endpoint de serviço é um URL de base que especifica o endereço de rede de um serviço de API. A API Telemetry oferece suporte a um endpoint global e endpoints regionais:

  • Endpoint global: telemetry.googleapis.com. Para esse endpoint, depois que o Google Cloud Observability concluir todas as etapas de validação, ele enviará os dados para um serviço de back-end para armazenamento.

  • Endpoints regionais: telemetry.REGION.rep.googleapis.com, em que REGION é uma região com suporte. Para esses endpoints, depois que o Google Cloud Observability concluir todas as etapas de validação, ele enviará os dados para um serviço de back-end. Esse serviço armazena ou descarta os dados:

    • Os dados de registro e trace são armazenados. O serviço de back-end move automaticamente os dados entre regiões quando necessário.
    • Os dados de métricas são armazenados apenas quando o rótulo de local anexado aos dados corresponde à região do endpoint ou a uma zona dentro dessa região.

    Para uma lista de endpoints regionais com suporte, consulte as páginas de referência da API.

A ingestão de dados de trace pode acionar a criação de um bucket de observabilidade. No entanto, o uso de um endpoint regional não afeta o local em que o sistema cria o bucket de observabilidade. O sistema determina o local de um bucket de observabilidade usando configurações padrão, políticas da organização e o conjunto de locais de bucket com suporte.