Visão geral de v1.logs

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.

Este documento descreve como os dados de registro enviados ao seu projeto Google Cloud usando a API Telemetry (OTLP) são mapeados para uma estrutura do Cloud Logging. Essa API implementa o protocolo OTLP 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 compatível com o Google Cloude com engenheiros do Google Cloudpara garantir o suporte à ingestão e visualização da sua telemetria.

Estrutura geral dos dados de registro formatados em OTLP

Quando os dados de registro são enviados para Google Cloud usando a API Telemetry, eles precisam estar em um formato consistente com o OTLP. A estrutura geral desses dados é mostrada abaixo:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

O OpenTelemetry agrupa registros individuais, cada um representado por uma estrutura logRecord, com informações sobre a origem desses registros, que é representada pela estrutura resource.

Quando a Observabilidade do Google Cloud recebe um objeto resourceLogs, ela cria um LogEntry para cada logRecord. Ao contrário do OTLP, que agrupa informações de origem com uma coleção de registros individuais, cada estrutura LogEntry contém informações sobre a origem do registro e o registro em si.

Para saber mais sobre a estrutura dos dados de registro formatados em OTLP, consulte o logs.proto do OpenTelemetry.

Como os dados de registro formatados em OTLP são tratados

Quando você envia uma estrutura OTLP resourceLogs para a API Telemetry, a Observabilidade do Google Cloud realiza as seguintes ações:

1. Para cada logRecord, o sistema cria um LogEntry.

   Os documentos a seguir descrevem como o sistema preenche o LogEntry com os dados de registro do OTLP:

   • Mapeamento de registro de log OTLP para entrada de registro.
   • Mapeamento de atributos OTLP para tipo de recurso do Cloud Logging.

   Como cada LogEntry contém informações sobre o tipo de recurso correspondente do Cloud Logging, cada LogEntry pode ser maior que o logRecord do OTLP correspondente.

   A conversão da estrutura resourceLogs do OTLP em uma série de estruturas LogEntry pode ter perdas. Ou seja, talvez não seja possível converter da estrutura LogEntry para os campos resource e logRecord originais.

2. O LogEntry é roteado por coletores agregados na hierarquia do projeto e por coletores no projeto, exatamente da mesma maneira que se a entrada de registro fosse enviada ao projeto usando a API Cloud Logging.

Práticas recomendadas

Ao instrumentar seus aplicativos para enviar dados de rastreamento ao projetoGoogle Cloud , recomendamos usar um exportador que grava dados formatados em OTLP em um coletor, que envia os dados de rastreamento à API Telemetry. No seu 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 das amostras de instrumentação baseadas em coletores.
• Visão geral da ingestão de métricas OTLP.

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

Configure os exportadores com as credenciais necessárias para enviar dados ao seu projeto Google Cloud . Por exemplo, ao usar coletores, normalmente você também usa a extensão googleclientauth para autenticar com 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.

Cloud Logging e residência de dados

Por padrão, o Cloud Logging encaminha entradas de registro originadas em um projeto para buckets de registro criados pelo sistema. Os buckets de registro são recursos regionais. É possível atualizar o coletor de registros padrão para enviar entradas de registro a um bucket de registros personalizado que esteja em um local de sua escolha. Para saber mais, consulte Regionalizar seus registros.

O Cloud Logging oferece configurações que podem ser definidas para organizações e pastas. Essas configurações especificam a localização dos novos buckets de registros criados pelo sistema, se eles usam chaves de criptografia gerenciadas pelo cliente (CMEK) e a configuração do coletor de registros padrão. Para saber mais, consulte Suporte para organizações e pastas.

Onde visualizar os dados ingeridos

É possível conferir os dados de registro usando as páginas Análise de registros e Análise de observabilidade. Para mais informações, consulte:

• Visualizar e analisar registros.
• Consultar e analisar registros com SQL.

Limitações

Esta seção descreve os limites. Ele também descreve como o Google Cloud Observability processa determinados tipos de dados.

Limites

Descrição	Valor	Observações
Número máximo de registros por solicitação OTLP	8192	Refere-se ao número máximo de logRecords em uma estrutura resourceLogs do OTLP. Limite.
Tamanho máximo de cada solicitação	5 MiB	Limite.
Tamanho máximo de um LogEntry criado com um registro de log OTLP	256 KiB	O Cloud Logging trunca ou descarta dados de um registro de log OTLP quando necessário. Limite.
Tamanho máximo de uma chave de atributo	512 B	Chaves de rótulo muito grandes são truncadas quando o registro de log OTLP é convertido em um LogEntry. Limite.
Comprimento máximo de um valor de atributo	64 KiB	Valores de rótulo muito grandes quando o registro de log do OTLP é convertido em um LogEntry. Limite.
Profundidade máxima do aninhamento de atributos	5	Os atributos que excedem esse limite são truncados quando o registro de log OTLP é convertido em um LogEntry.
Número máximo de bytes de ingestão de registros por minuto	2,4 GB para as seguintes regiões: asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1. 300 MB para todas as outras regiões.	Cota.

Comportamento

• Quando o número e o texto de gravidade do OpenTelemetry são definidos, o sistema usa o número para determinar o nível de gravidade do Cloud Logging. Se o registro OTLP não tiver informações de gravidade, o nível de gravidade do Cloud Logging será definido como DEFAULT.

• Quando um registro OTLP contém chaves de atributo duplicadas, o sistema retém a primeira chave e descarta os atributos com chaves duplicadas.

• O sistema converte em uma string os atributos anexados a um registro de log. Para ver um exemplo, consulte Campo "Rótulos".

• Os nomes de registros precisam ser codificados para URL ou seguros para URL durante a ingestão. Para informações sobre como os nomes de registros são definidos, consulte Como os campos LogEntry são definidos.