Suporte ao OTLP no Google Cloud Observability

É possível ingerir dados de registro, métrica e trace formatados em OTLP no Google Cloud Observability usando a API Telemetry (OTLP), que implementa o protocolo OpenTelemetry. Com essa API, é possível coletar telemetria independente de fornecedor de SDKs e coletores do OpenTelemetry sem usar exportadores Google Cloud personalizados.

Quando você envia telemetria para seu projeto usando a API Telemetry, o Google Cloud Observability processa cada sinal da seguinte maneira:

  • Dados de registro:converte registros do OTLP em entradas de registro e os encaminha para armazenamento.
  • Dados de métricas:mapeia dados de métricas para série temporal do Prometheus no Cloud Monitoring.
  • Dados de trace:armazena traces distribuídos em um formato que geralmente é consistente com o OTLP.

Se você executa cargas de trabalho no Google Kubernetes Engine, use o OpenTelemetry gerenciado para GKE em vez de implantar e gerenciar manualmente um coletor do OpenTelemetry.

Suporte a protocolo

O endpoint do OTLP é compatível com todos os protocolos de transporte e serialização do OTLP, incluindo http/protobuf, http/json e grpc. Ao exportar diretamente de aplicativos que usam SDKs, recomendamos usar o exportador OTLP do gRPC, em vez de exportadores HTTP, porque a maioria dos exportadores de SDK não oferece suporte à atualização dinâmica de tokens.

Autenticação

É preciso configurar os exportadores com as credenciais necessárias para enviar dados ao projeto do Google Cloud . Por exemplo, ao usar coletores, normalmente você usa a extensão googleclientauth para autenticar com as credenciais do Google.

Para ver um exemplo de autenticação ao usar a exportação direta de dados de trace, consulte Configurar 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 para a linguagem ao seu aplicativo.

Para enviar dados de telemetria ao projeto do Google Cloud usando a API Telemetry, você também precisa fazer o seguinte:

  • Configurar um projeto de cota. Para saber mais, consulte Definir o projeto de cota.

  • Conceda os seguintes papéis do Identity and Access Management (IAM) ao usuário ou à conta de serviço que o aplicativo usa:

Ingestão de OTLP

Nesta seção, descrevemos como os dados de registro, métrica e trace são convertidos do OTLP em estruturas de dados do Google Cloud Observability.

Ingestão de dados de registro

Quando você usa a API Telemetry para ingerir registros formatados em OTLP, os dados de registro são convertidos em entradas de registro do Cloud Logging. Uma solicitação de registro recebida em formato 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. Os atributos resource determinam o recurso monitorado no LogEntry resultante. Para mais informações sobre quais atributos são necessários para a ingestão de registros formatados em OTLP, consulte Atributos OTLP para mapeamento de tipo de recurso.

Para oferecer suporte à ingestão de registros formatados em OTLP, a estrutura LogEntry do Cloud Logging contém um campo adicional, otel. Como os modelos de dados do OTLP e do Cloud Logging têm estruturas diferentes, o campo otel preserva uma cópia dos metadados de recurso, escopo e entidade da solicitação OTLP recebida.

Por exemplo, se você enviar um payload OTLP resourceLogs 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:

resourceLogs 

{
  "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"
      }
    },
   ...
  }

Como as entradas de registro do Cloud Logging são independentes e não se vinculam a esquemas de recursos externos, todos os metadados de recursos, escopos e entidades do OTLP são copiados para cada entrada de registro.

Ingestão de dados de métricas

O OTLP para métricas do Prometheus só funciona ao usar o OpenTelemetry Collector versão 0.140.0 ou mais recente.

Quando as métricas são ingeridas no Cloud Monitoring usando um coletor do OpenTelemetry e o exportador otlphttp ou enviadas diretamente usando um SDK do OpenTelemetry, as métricas do OTLP são mapeadas para as estruturas de métricas do Cloud Monitoring. Para ver informações sobre esses mapeamentos, consulte:

O Google Cloud Observability converte as métricas no formato de série temporal do Prometheus. Os nomes de métricas não podem ter domínio ou precisam ter o domínio prometheus.googleapis.com. Após a conversão, o nome da métrica inclui o prefixo prometheus.googleapis.com e um sufixo adicional, com base no tipo de ponto do OTLP. A métrica resultante do Cloud Monitoring tem a seguinte estrutura:

prometheus.googleapis.com/{metric_name}/{suffix}

Além disso, para cada recurso exclusivo do OpenTelemetry, a conversão adiciona uma métrica target_info que contém todos os atributos de recurso, exceto service.name, service.instance.id e service.namespace.

Como os nomes de métricas e as chaves de rótulo no Cloud Monitoring não são compatíveis com UTF-8 completo, os dados de métricas podem ser rejeitados:

  • Os nomes de métricas que não estão em conformidade com a expressão regular [a-zA-Z][a-zA-Z0-9_:./-]* são rejeitados. Os únicos caracteres especiais permitidos em nomes de métricas estão no conjunto _:./-.
  • Os pontos de dados que contêm atributos (ou seja, chaves de rótulo) que não estão em conformidade com a expressão regular [a-zA-Z_][a-zA-Z0-9_.]* são rejeitados. Os únicos caracteres especiais permitidos nas chaves de rótulo estão no conjunto _.. Todos os caracteres especiais são permitidos nos valores de rótulo.

Para evitar a rejeição das suas métricas por esses motivos, use a função replace_pattern para transformar os nomes e atributos das métricas.

Ingestão de dados de trace

Independentemente de você usar a API Telemetry ou a API Cloud Trace, os dados de trace recebidos são armazenados em um formato consistente com o OTLP. No entanto, recomendamos usar a API Telemetry porque ela oferece cotas de ingestão mais altas do que a API Cloud Trace.

Veja a seguir um exemplo de dados de trace que podem ser enviados de um aplicativo para o projeto do Google Cloud :

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

Cada item em cada matriz scopeSpans.spans se torna um único período armazenado:

  • O campo resource de cada período contém uma cópia dos dados de resourceSpans.resource.attributes.
  • O campo instrumentation_scope de cada período contém uma cópia dos dados de scopeSpans.scope.
  • Cada período corresponde a uma entrada na matriz scopeSpans.spans. Campos como traceId, spanId e kind são mapeados para campos com nomes semelhantes no esquema de trace.

Para mais informações, consulte estes documentos:

Faturamento

O faturamento de dados de registro, métrica e trace ingeridos usando a API Telemetry depende do sinal de telemetria. Para informações completas, consulte a página de faturamento.

Faturamento de dados de registro

Talvez você note uma mudança nos valores de armazenamento e faturamento do Cloud Logging ao usar a API Telemetry para ingerir registros devido a uma mudança no volume de registros.

As maiores mudanças no armazenamento e no faturamento do projeto do Google Cloud ocorrem quando as duas condições a seguir são verdadeiras:

  • O campo resource contém atributos de alta cardinalidade ou um grande número de atributos. Esses atributos determinam o recurso monitorado no LogEntry resultante.
  • O campo scopeLogs contém um grande número de itens nas matrizes logRecords. Os campos scopeLogs.scope são copiados para o campo otel em cada entrada de registro individual.

Como esses metadados de recurso e escopo são copiados para cada entrada de registro, o volume de registros armazenados pode aumentar.

Para minimizar o volume de armazenamento, recomendamos o seguinte:

  • Use um processador do coletor do OpenTelemetry, como um processador transform, para descartar atributos de recurso ou escopo desnecessários antes de exportar os dados.
  • Se você não precisar dos metadados adicionais preservados no campo otel, use a opção de mapeamento legado, gcp.use_legacy_mapping, que impede que o campo otel seja preenchido.

Faturamento de dados de métricas

O faturamento das métricas do OTLP é contabilizado na SKU "Amostras do Prometheus ingeridas", a mesma usada para métricas do Google Cloud Managed Service para Prometheus.

Faturamento de dados de trace

A API usada para enviar dados de trace ao projeto não afeta como as cobranças são calculadas para esses dados.

Como consultar dados de registro, métrica e trace

Use as páginas de análise (Análise de Registros, Metrics Explorer e Trace Explorer) para consultar dados de registros, métricas e traces. Também é possível usar a página Análise de Observabilidade para analisar os dados de registro e trace usando SQL.

As dicas a seguir podem ser úteis ao consultar os dados de métricas usando o Metrics Explorer:

  • Importante: para consultar nomes de métricas e chaves de rótulo com caracteres especiais diferentes de dois-pontos (:) e sublinhado (_), é necessário colocá-los entre chaves ({}) e aspas ("), de acordo com a especificação UTF-8 do PromQL. Por exemplo, as seguintes consultas são válidas:

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • Manter o rótulo le ao consultar histogramas exponenciais pode retornar resultados inesperados. As consultas histogram_quantile(.99, sum by (le) (metric)) mais comuns devem funcionar.

  • As métricas delta podem não ser consultadas corretamente em determinadas circunstâncias, como deltas muito esparsos.

Limites e cotas

Os limites da API Telemetry se aplicam a todos os tipos de indicadores.

As seguintes cotas e limites também se aplicam:

  • Dados de registro: as cotas e os limites da API Cloud Logging se aplicam.

  • Dados de métricas: as cotas e os limites da API Cloud Monitoring se aplicam. Por exemplo, as métricas não podem ter mais de 200 rótulos.

    A cota padrão para métricas ingeridas pela API Telemetry é de 60.000 solicitações por minuto. Com um tamanho máximo de lote de 200 pontos por solicitação, essa cota é uma cota padrão efetiva de 200.000 amostras por segundo. É possível solicitar um aumento de cota.

  • Dados de trace: não há outras cotas ou limites aplicáveis.

A seguir