Mapeamento de registro de registro OTLP para entrada de registro

Visualizar

Este produto ou 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 produtos e 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 o Google Cloud Observability determina os campos de um LogEntry do registro de log OTLP quando esse registro é enviado para Google Cloud usando a API Telemetry.

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 campos LogEntry são definidos

O Google Cloud Observability usa as seguintes regras para determinar os valores dos campos LogEntry:

Campo LogEntry (nomes da referência HTTP)	Como o sistema determina o valor do campo
logName	O sistema usa a seguinte lista priorizada de atributos de registro do OpenTelemetry para determinar o nome do registro: gcp.log_name log_name event_name Os nomes de registros precisam ser codificados para URL ou seguros para URL durante a ingestão.
resource	O sistema usa as informações definidas no campo resource ou infere o recurso. Para mais detalhes, consulte Mapeamento de atributos OTLP para tipo de recurso.
timestamp	O sistema usa a seguinte lista priorizada de campos de registro de logs do OpenTelemetry para determinar o timestamp: time_unix_nano quando diferente de zero. observed_time_unix_nano quando diferente de zero. O horário em que a entrada de registro foi ingerida. O período de armazenamento do bucket de registros que armazena os dados determina o carimbo de data/hora mais antigo que pode ser ingerido. Para mais informações, consulte cotas do Cloud Logging.
receiveTimestamp	Definido como o horário em que o LogEntry é ingerido.
severity	O sistema mapeia a gravidade do OpenTelemetry no registro de log para uma gravidade do Cloud Logging. Para mais detalhes, consulte Campo "Gravidade".
httpRequest	O sistema mapeia os atributos gcp.http_request no registro de registro para campos LogEntry equivalentes. Para mais informações, consulte o campo HttpRequest. FIXME. Há outros campos que são mapeados para esse campo.
labels	O sistema define esse campo usando os valores dos atributos do registro de log. Para mais informações, consulte Campo "Rótulos".
trace	O sistema define esse campo como o valor do campo traceId do registro de registro. O valor precisa ser uma string hexadecimal de 32 caracteres válida. Caso contrário, a entrada será rejeitada.
spanId	O sistema define esse campo como o valor do campo spanId do registro de registro. O valor precisa ser uma string hexadecimal válida de 16 caracteres. Caso contrário, a entrada será rejeitada.
traceSampled	Não definido.
sourceLocation	O sistema define esse campo com os valores dos atributos Code do registro de log. Para mais informações, consulte o campo SourceLocation.
split	Não definido.
apphub apphubDestination apphubSource	Não definido.
otel	Para campos nos dados de registros OTLP que não têm um campo equivalente em um LogEntry, o sistema converte os tipos de dados e adiciona os dados convertidos ao campo otel. Para mais informações, consulte Campo Otel.
Payload	O sistema define o payload convertendo o corpo de um registro de log em um tipo de payload adequado. Para mais informações, consulte Campo de payload.

Campo HttpRequest

O Google Cloud Observability mapeia atributos OTLP que se aplicam a solicitações HTTP para campos LogEntry. As seções a seguir descrevem como o sistema mapeia atributos simples e aninhados.

Atributos simples

A tabela a seguir descreve como o Google Cloud Observability mapeia atributos simples que se aplicam a solicitações HTTP para campos LogEntry. Por exemplo, o valor do atributo http.request.method: "GET", é definido como o valor do campo httpRequest.requestMethod em uma entrada de registro:

Par de chave-valor do OpenTelemetry LogRecord.attribute .	Valor armazenado no campo LogEntry (nomes da referência HTTP).	Tipo aceito
http.request.method	httpRequest.requestMethod	string
url.full http.url	httpRequest.requestUrl	string
http.request.body.size	httpRequest.requestSize	string, int
http.response.status_code	httpRequest.status	string, int
http.response.body.size	httpRequest.responseSize	string, int
user_agent.original http.user_agent	httpRequest.userAgent	string
client.address	remoteIp	string
server.address	serverIp	string
referrer	httpRequest.referer	string
latency	httpRequest.latency	string, int
cacheLookup	httpRequest.cacheLookup	bool
cacheHit	httpRequest.cacheHit	bool
cacheValidatedWithOriginServer	httpRequest.cacheValidatedWithOriginServer	bool
cacheFillBytes	httpRequest.cacheFillBytes	string, int
network.protocol.version protocol	httpRequest.protocol	string

Atributos aninhados

Nesta seção, descrevemos como o Google Cloud Observability mapeia atributos OTLP aninhados que se aplicam a solicitações HTTP para campos em um LogEntry. O exemplo a seguir ilustra um registro de log que contém dois atributos, cada um deles com pelo menos outro atributo:

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

Na tabela, os atributos aninhados são mostrados usando chaves. Por exemplo, gcp.http_request {requestMethod} significa que o atributo gcp.http_request contém o atributo requestMethod. O valor do atributo mais interno é atribuído ao valor do campo de entrada de registro:

Par de chave-valor do OpenTelemetry LogRecord.attribute .	Valor armazenado no campo LogEntry (nomes da referência HTTP).	Tipo aceito
gcp.http_request {requestMethod} http_request {requestMethod}	httpRequest.requestMethod	string
gcp.http_request {requestUrl} http_request {requestUrl}	httpRequest.requestUrl	string
gcp.http_request {requestSize} http_request {requestSize}	httpRequest.requestSize	string, int
gcp.http_request {status} http_request {status}	httpRequest.status	string, int
gcp.http_request {responseSize} http_request {responseSize}	httpRequest.responseSize	string, int
gcp.http_request {userAgent} http_request {userAgent}	httpRequest.userAgent	string
gcp.http_request {remoteIp} http_request {remoteIp}	httpRequest.remoteIp	string
gcp.http_request {serverIp} http_request {serverIp}	httpRequest.serverIp	string
gcp.http_request {referer} http_request {referrer}	httpRequest.referer	string
gcp.http_request {latency} http_request {latency}	httpRequest.latency	string, int
gcp.http_request {cacheLookup} http_request {cacheLookup}	httpRequest.cacheLookup	bool
gcp.http_request {cacheHit} http_request {cacheHit}	httpRequest.cacheHit	bool
gcp.http_request { cacheValidatedWithOriginServer} http_request { cacheValidatedWithOriginServer}	httpRequest.cacheValidatedWithOriginServer	bool
gcp.http_request {cacheFillBytes} http_request {cacheFillBytes}	httpRequest.cacheFillBytes	string, int
gcp.http_request {protocol} http_request {protocol}	httpRequest.protocol	string

Campo "Marcadores"

Para determinar quais rótulos anexar à entrada de registro, o sistema realiza as seguintes ações:

1. Ele remove do registro de log OTLP todos os atributos que foram mapeados para campos LogEntry específicos.

   Por exemplo, suponha que haja os atributos anexados a um registro de log:

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
       "code.file.path": "my-file.cc",
       "code.function.name: "my-func",
       "code.line.number": 123,
       "gcp.http_request": {
           "requestMethod": "GET",
           "requestUrl": "my-URL",
     },
   }
   

   Depois de remover os campos mapeados para campos LogEntry específicos, os seguintes campos permanecem:

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
   }
   

2. Se um atributo contiver uma matriz ou elementos JSON, o sistema vai converter o valor em uma string.

   Por exemplo, o seguinte ilustra como LogEntry representa os atributos anteriores:

   labels: {
       "log_array_attr": "[\"value1\",\"value2\"]",
       "log_json_attr": "{\"json_key\":\"json_value\"}",
       "log-string-attr": "string",
   }
   

   A profundidade máxima de aninhamento para atributos é cinco. Qualquer conteúdo com aninhamento mais profundo é truncado.

Campo Otel

Para campos nos dados de registros OTLP que não têm um campo equivalente em um LogEntry, o sistema converte os tipos de dados e adiciona os dados convertidos ao campo otel. Por exemplo, o campo otel armazena atributos dos campos resource, scope e entity.

O sistema usa as seguintes regras para converter os tipos de dados do OpenTelemetry em tipos Value do protobuf:

Tipo do OpenTelemetry	tipo protobuf
string	string
boolean	bool
integer	double
float	double
Array	ListValues
KeyValueList	Struct

Para evitar erros de dupla precisão, transmita números inteiros como strings.

Campo de payload

Observação: o tamanho máximo de um LogEntry é de 256 KiB. Esse limite é aproximado e se baseia em tamanhos de dados internos. Quando necessário, o sistema trunca o campo de payload.

O tipo de dados do campo logRecord.body do OTLP determina a estrutura do payload LogEntry:

• string: o sistema copia a string para o campo LogEntry.textPayload.

• Array: o sistema cria uma string dos elementos da matriz, preservando as novas linhas. Em seguida, ele copia a string para o campo LogEntry.textPayload.

• KeyValueList: o sistema converte esses pares em JSON e preenche o campo LogEntry.jsonPayload com as seguintes restrições:

  • Quando um registro OTLP contém chaves de atributo duplicadas, o sistema retém a primeira chave e descarta atributos com chaves duplicadas.
  • Quando a profundidade de aninhamento de um par JSON é maior que cinco, o sistema trunca o conteúdo para uma profundidade de cinco.

Campo "Gravidade"

Nesta seção, descrevemos como o Google Cloud Observability mapeia os campos de gravidade do OpenTelemetry para os níveis de gravidade do Cloud Logging. O OpenTelemetry define um número e um texto de gravidade. O logs.proto define os números de gravidade.

O Google Cloud Observability determina a gravidade do Logging com base no número de gravidade do OpenTelemetry, se definido. Caso contrário, ele usa o texto de gravidade. Se nenhum dos dois estiver definido, a gravidade do registro será definida como DEFAULT.

Número de gravidade do OpenTelemetry Enum (value)	Texto de gravidade do OpenTelemetry (os testes não diferenciam maiúsculas e minúsculas)	Gravidade do Cloud Logging Enum (value)
SEVERITY_NUMBER_UNSPECIFIED (0)	"default" not set	DEFAULT (0)
SEVERITY_NUMBER_TRACE (1) SEVERITY_NUMBER_TRACE2 (2) SEVERITY_NUMBER_TRACE3 (3) SEVERITY_NUMBER_TRACE4 (4)	"trace" "trace2" "trace3" "trace4"	DEBUG (100)
SEVERITY_NUMBER_DEBUG (5) SEVERITY_NUMBER_DEBUG2 (6) SEVERITY_NUMBER_DEBUG3 (7) SEVERITY_NUMBER_DEBUG4 (8)	"debug" "debug2" "debug3" "debug4"	DEBUG (100)
SEVERITY_NUMBER_INFO (9) SEVERITY_NUMBER_INFO2 (10)	"info" "info2"	INFO (200)
SEVERITY_NUMBER_INFO3 (11) SEVERITY_NUMBER_INFO4 (12)	"notice" "info3" "info4"	NOTICE (300)
SEVERITY_NUMBER_WARN (13) SEVERITY_NUMBER_WARN2 (14) SEVERITY_NUMBER_WARN3 (15) SEVERITY_NUMBER_WARN4 (16)	"warning" "warn" "warn2" "warn3" "warn4"	WARNING (400)
SEVERITY_NUMBER_ERROR (17) SEVERITY_NUMBER_ERROR2 (18) SEVERITY_NUMBER_ERROR3 (19) SEVERITY_NUMBER_ERROR4 (20)	"error" "error2" "error3" "error4"	ERROR (500)
SEVERITY_NUMBER_FATAL (21) SEVERITY_NUMBER_FATAL2 (22)	"critical" "fatal" "fatal2"	CRITICAL (600)
SEVERITY_NUMBER_FATAL3 (23)	"alert" "fatal3"	ALERT (700)
SEVERITY_NUMBER_FATAL4 (24)	"emergency" "fatal4"	EMERGENCY (800)

Campo SourceLocation

O Google Cloud Observability mapeia o seguinte código do OTLP diretamente para os campos LogEntry. Esse mapeamento é possível porque esses atributos do OpenTelemetry são semanticamente idênticos aos conceitos do Cloud Logging.

Par de chave-valor do OpenTelemetry LogRecord.attribute .	Valor armazenado no campo LogEntry (nomes da referência HTTP).	Tipo aceito
code.file.path: Value	sourceLocation.file	string
code.function.name: Value	sourceLocation.function	string
code.function.number: Value	sourceLocation.line	string, int

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.