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 pelo seu Google Cloud projeto usando a API Telemetry (OTLP) são mapeados para uma estrutura do Cloud Logging. Essa API implementa o protocolo de linha do OpenTelemetry. É possível enviar dados para essa API ao instrumentar seus aplicativos com um otlphttp exportador e um coletor do OpenTelemetry ou ao usar os SDKs do OpenTelemetry.

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

Estrutura geral dos dados de registro formatados em OTLP

Quando os dados de registro são enviados para Google Cloud usando a API Telemetry, estes dados 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 o Google Cloud Observability recebe um objeto resourceLogs, ele 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 logs.proto do OpenTelemetry.

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

Quando você envia uma estrutura resourceLogs do OTLP para a API Telemetry, o Google Cloud Observability 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 registro OTLP para entrada de registro.
   • Mapeamento de atributos OTLP para o tipo de recurso do Cloud Logging.

   Como cada LogEntry contém informações sobre o tipo de recurso do Cloud Logging correspondente, 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 ser com perdas. Ou seja, talvez não seja possível converter da estrutura LogEntry para os campos resource e logRecord originais.

2. O LogEntry é roteado para 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 Google Cloud projeto, recomendamos que você use um exportador que grave dados formatados em OTLP em um coletor, que envia os dados de rastreamento 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 necessário. 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 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 rastreamento 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 para 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 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 Google Auth específica do idioma ao 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. 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 o local de novos buckets de registro criados pelo sistema, se esses buckets de registro 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 visualizar 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. Ela 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 OTLP resourceLogs do OTLP. Limite.
Tamanho máximo de cada solicitação	5 MiB	Limite.
Tamanho máximo de um LogEntry criado a partir de um registro de registro OTLP	256 KiB	O Cloud Logging trunca ou descarta dados de um registro de registro OTLP quando necessário. Limite.
Comprimento máximo de uma chave de atributo	512 B	As chaves de rótulo muito grandes são truncadas quando o registro de registro 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 registro 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 registro 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 de gravidade e o texto de gravidade do OpenTelemetry são definidos, o sistema usa o número de gravidade para determinar o nível de gravidade do Cloud Logging. Se o registro OTLP não contiver 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 atributos anexados a um registro de registro em uma string. Para um exemplo, consulte o campo Rótulos.

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