Visão geral da ingestão de registros OTLP

Este documento apresenta o uso da API Telemetry (OTLP), telemetry.googleapis.com, para a ingestão de registros formatados em OTLP no Cloud Logging, onde são armazenados como entradas de registro. Por exemplo, consulte Gravar registros formatados em OTLP na API Telemetry.

Também é possível enviar registros para a API de telemetria de aplicativos que usam SDKs ou um coletor OpenTelemetry.

Para informações sobre a API Telemetry para registros, métricas e rastreamentos, consulte a referência da API Telemetry (OTLP).

Suporte a protocolo

O endpoint OTLP é compatível com todos os protocolos OTLP, incluindo http/protobuf, http/json e grpc. Ao exportar de um coletor do OpenTelemetry, você pode usar qualquer um dos protocolos. No entanto, devido à falta de suporte para atualização dinâmica de tokens na maioria dos exportadores de SDK, se você estiver exportando diretamente dos SDKs, recomendamos usar apenas o exportador gRPC OTLP, não os exportadores HTTP.

Faturamento

Ao usar a API Telemetry para ingerir registros, talvez você note uma mudança nos valores de armazenamento e faturamento do Cloud Logging. Uma solicitação de registro formatada em OTLP em JSON tem a seguinte estrutura geral:

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

Cada item em cada matriz logRecords se torna uma única entrada de registro do Cloud Logging. As maiores mudanças no armazenamento e no faturamento do seu projeto Google Cloud ocorrem quando as duas condições a seguir são verdadeiras:

  • O campo resource contém um grande número de atributos obrigatórios para chaves e valores. Esses atributos são usados para determinar o recurso monitorado no LogEntry resultante.

    O recurso monitorado consiste em um tipo de recurso monitorado do Cloud Logging e valores para os rótulos associados. Alguns tipos de recursos monitorados têm poucos rótulos, mas outros têm muitos. Para mais informações sobre quais atributos são necessários para a ingestão de registros formatados em OTLP, consulte Mapeamento de atributos OTLP para tipo de recurso.

  • O campo scopeLogs contém um grande número de itens nas matrizes logRecords.

Para oferecer suporte à ingestão de registros formatados em OTLP, a estrutura LogEntry do Cloud Logging contém um campo adicional, otel. Os modelos de dados do OTLP e do Cloud Logging não são uma correspondência perfeita. Por isso, o campo otel contém uma cópia do recurso, do escopo e das entidades do OTLP da solicitação OTLP recebida.

Por exemplo, se você enviar um resourceLog OTLP como o seguinte para a API Telemetry, cada entrada de registro resultante vai conter um campo resource (para o recurso monitorado) e um campo otel, conforme mostrado nas outras guias:

resourceLog 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

O Cloud Logging não tem como vincular outros recursos a uma entrada de registro. Portanto, todas as informações sobre recursos, escopos e entidades do OTLP precisam ser copiadas para cada entrada de registro.

Essa duplicação preserva o máximo de informações possível da solicitação original na entrada de registro resultante. Mas a duplicação também significa que o campo otel repete informações de recursos também usadas no campo monitored-resource (resource) da entrada de registro. O campo resource da entrada de registro e as informações de recurso duplicadas no campo otel são sujeitos a cobrança.

Quando você inclui um grande número de registros de registros na solicitação OTLP, as informações OTLP precisam ser copiadas para cada entrada de registro resultante, nos campos resource e otel. Quando você inclui um grande número de logRecords OTLP em uma solicitação, o número de campos resource sujeitos a cobrança nas entradas de registro aumenta proporcionalmente ao número de logRecords OTLP por resource por solicitação.

Para minimizar as informações adicionais armazenadas, recomendamos enviar um item logRecord por solicitação.

Limites e cotas

Para informações sobre limites e cotas associados ao uso da API Telemetry para geração de registros, consulte Limites e cotas para ingestão de registros.

As cotas e os limites do Cloud Logging também se aplicam ao usar a API Telemetry para ingestão de registros.