O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Mapeamento de registro de registro OTLP para entrada de registro

Neste documento, descrevemos como o Google Cloud Observability determina os campos de um LogEntry do registro de registro do OTLP, quando esse registro é enviado para Google Cloud usando a API Telemetry.

Os exportadores do Google Cloud para o Cloud Logging convertem dados de registro formatados em OTLP em objetos LogEntry. Em seguida, eles enviam esses dados para o projeto do Google Cloud usando a API Cloud Logging. No entanto, as regras padrão que o Google Cloud Observability e os exportadores usam para criar entradas de registro são diferentes. Para mais informações, consulte Configurar o Google Cloud Observability para usar os mapeamentos do exportador.

Estrutura geral dos dados de registro formatados em OTLP

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

"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 próprio registro.

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 o valor do campo `event_name` no `LogRecord` do OTLP. Se esse campo não existir ou não estiver definido, o sistema usará a seguinte lista priorizada de atributos de registro de registros do OpenTelemetry para determinar o nome do registro: `log.name` `gcp.log.name` `log_name` `gcp.log_name` `logging.googleapis.com/logName` `service.name` `gcp.service.name` `service_name` `gcp.service_name` `event.name` `gcp.event.name` `event_name` `gcp.event_name` Os nomes de registro precisam ser seguros para URL ou codificados 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 do OTLP para o tipo de recurso.
`timestamp`	O sistema usa a seguinte lista priorizada de campos de registro de log do OpenTelemetry para determinar o `timestamp`: `time_unix_nano` quando não for zero. `observed_time_unix_nano` quando não for zero. A hora 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`	Defina como o horário em que o `LogEntry` é ingerido.
`severity`	O sistema mapeia a gravidade do OpenTelemetry no registro para uma gravidade do Cloud Logging. Para mais detalhes, consulte Campo de gravidade.
`httpRequest`	O sistema mapeia os atributos `gcp.http_request` no registro de registro para campos `LogEntry` equivalentes. O sistema aceita esses atributos como estruturados ou como uma string JSON. Para mais informações, consulte o campo HttpRequest.
`labels`	O sistema define esse campo usando os valores dos atributos do registro. Para mais informações, consulte o campo Rótulos.
`trace`	O sistema define esse campo como o valor do campo `traceId` do registro. O valor precisa ser uma string hexadecimal válida de 32 caracteres, ou a entrada será rejeitada.
`spanId`	O sistema define esse campo como o valor do campo `spanId` do registro. O valor precisa ser uma string hexadecimal válida de 16 caracteres, ou a entrada será rejeitada.
`traceSampled`	O sistema define esse campo com base no bit menos significativo do campo `flags` do registro. Se o bit menos significativo for igual a `1`, esse campo será definido como `true`. Caso contrário, ele permanecerá indefinido.
`sourceLocation`	O sistema define esse campo com os valores dos atributos Code do registro de registro. Para mais informações, consulte o campo SourceLocation.
`split`	Não definido.
`apphub` `apphubDestination` `apphubSource`	Não definido.
`otel`	Para campos em dados de registro do 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.
`operation`	O sistema mapeia os atributos `gcp.operation` no registro de registro para campos `LogEntry` equivalentes. Para mais informações, consulte Campo de operação.
Payload	O sistema define o payload convertendo o corpo de um registro de registro em um tipo de payload apropriado. 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 `LogRecord.attribute` do OpenTelemetry.	Valor armazenado no seguinte campo `LogEntry` campo (Nomes do referenciador de 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 registro que contém dois atributos, cada um com pelo menos um outro atributo:

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

O formato do campo gcp.http_request pode ser de atributos aninhados estruturados ou uma string JSON de atributos estruturados.

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

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 da entrada de registro:

Par de chave-valor `LogRecord.attribute` do OpenTelemetry.	Valor armazenado no seguinte campo `LogEntry` campo (Nomes do referenciador de 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 de rótulos

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

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

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

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 específicos do LogEntry, os seguintes campos permanecem:

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

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

Por exemplo, o exemplo a seguir ilustra como o 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 de operação

O Google Cloud Observability mapeia os atributos do OTLP que se aplicam à operação para o campo operation de um LogEntry. As seções a seguir descrevem como o sistema mapeia os atributos aninhados.

O atributo gcp.operation precisa conter tipos de chave-valor. Nomes de atributos nivelados não são aceitos. O exemplo a seguir ilustra um registro de registro em que o atributo gcp.operation contém quatro pares de chave-valor:

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

A tabela a seguir descreve como o Google Cloud Observability mapeia o gcp.operation para o LogEntry:

Par de chave-valor `LogRecord.attribute.operation` do OpenTelemetry.	Valor armazenado no seguinte campo de operação `LogEntry`	Tipo aceito
`id`	`id`	string
`producer`	`httpRequest.requestUrl`	string
`first`	`first`	bool
`last`	`last`	bool

Campo Otel

Para campos em dados de registro do 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 de protobuf
`string`	`string`
`boolean`	`bool`
`integer`	`double`
`float`	`double`
`Array`	`ListValues`
`KeyValueList`	`Struct`

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

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, ela 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 os 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 de 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 deles estiver definido, a gravidade do Logging será definida como DEFAULT.

Número de gravidade do OpenTelemetry Tipo enumerado (valor)	Texto de gravidade do OpenTelemetry (os testes não diferenciam maiúsculas de minúsculas)	Gravidade do Cloud Logging Tipo enumerado (valor)
`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 Code 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 `LogRecord.attribute` do OpenTelemetry.	Valor armazenado no seguinte campo `LogEntry` campo (Nomes do referenciador de 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 lida com determinados tipos de dados.

Limites

Descrição	Valor	Observações
Número máximo de registros por solicitação do OTLP	8192	Refere-se ao número máximo de `logRecords` em uma estrutura `resourceLogs` do OTLP. Limit.
Tamanho máximo de cada solicitação	5 MiB	Limit.
Tamanho máximo de um `LogEntry` criado com base em um registro de OTLP	256 KiB	O Cloud Logging trunca ou descarta dados de um registro de OTLP quando necessário. Limit.
Comprimento máximo de uma chave de atributo	512 B	As chaves de rótulo muito grandes são truncadas quando o registro de OTLP é convertido em um `LogEntry`. Limit.
Tamanho máximo de um valor de atributo	64 KiB	Valores de rótulo muito grandes quando o registro do OTLP é convertido em um `LogEntry`. Limit.
Profundidade máxima de aninhamento de atributos	20	As solicitações com atributos que excedem esse limite são rejeitadas quando o registro de log do 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 de gravidade para determinar o nível de gravidade do Cloud Logging. Se o registro do 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 os atributos anexados a um registro em uma string. Para ver um exemplo, consulte Campo de rótulos.
Os nomes de registro precisam ser seguros para URL ou codificados para URL durante a ingestão. Para saber como os nomes de registro são definidos, consulte Como os campos LogEntry são definidos.

Configurar o Google Cloud Observability para usar os mapeamentos do exportador

O Google Cloud Observability e o exportador do Google Cloud para o Cloud Logging usam regras diferentes para criar objetos LogEntry com base em dados de registro formatados em OTLP. Por exemplo, o Google Cloud Observability preenche o campo otel, mas os exportadores não.

Se você quiser que o Google Cloud Observability use as mesmas regras de mapeamento que os exportadores, faça as seguintes alterações nos aplicativos que enviam registros de OTLP para a API Telemetry:

Adicione o atributo gcp.use_legacy_mapping ao recurso incluído na solicitação. Para mais informações, consulte Como adicionar ou excluir atributos.

Quando esse atributo é definido, ocorre o seguinte:
1. O campo otel não está preenchido.
2. Os atributos que começam com gcp são descartados, com as seguintes exceções:
  - gcp.log.name
  - gcp.insert_id
  Os dois atributos anteriores são mapeados para campos LogEntry.
A regra de mapeamento legada faz com que o Google Cloud Observability descarte alguns conteúdos. No entanto, o tamanho dos objetos LogEntry é menor.
Adicione processadores ao coletor HTTP do OTLP que definem os seguintes rótulos de registro:
- Defina instrumentation_scope como instrumentation_scope.name.
- instrumentation_version: defina como instrumentation_scope.version.
- service.name: defina como resource.attributes["service.name"].
- Defina service.namespace como resource.attributes["service.namespace"].
- service.instance.id: defina como resource.attributes["service.instance.id"].
Para ver um exemplo, consulte Migrar para o exportador do OTLP: processadores.