Suporte ao OTLP no Google Cloud Observability

É possível ingerir dados de registros, métricas e trace formatados em OTLP no Google Cloud Observability usando a API Telemetria (OTLP), que implementa o protocolo OpenTelemetry. Com essa API, é possível coletar telemetria neutra de fornecedores 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 indicador da seguinte maneira:

  • Dados de registros:convertem registros de log do OTLP em entradas de registro e os encaminham para armazenamento.
  • Dados de métricas:mapeia dados de métricas para série temporal do Prometheus no Cloud Monitoring.
  • Dados de rastreamento:armazenam rastreamentos distribuídos em um formato geralmente consistente com o OTLP.

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

Suporte a protocolo

O endpoint 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 usando SDKs, recomendamos usar o exportador gRPC OTLP em vez de exportadores HTTP, porque a maioria dos exportadores de SDK não oferece suporte à atualização dinâmica de tokens.

Autenticação

Configure os exportadores com as credenciais necessárias para enviar dados ao seu projeto Google Cloud . Por exemplo, ao usar coletores, normalmente você usa a extensão googleclientauth para autenticar com 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 de autenticação do Google específica do idioma ao seu aplicativo.

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

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

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

Ingestão de OTLP

Esta seção descreve como seus dados de registros, métricas e traces são convertidos do OTLP em estruturas de dados do Google Cloud Observability.

Ingestão de dados de registros

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 formatada em OTLP recebida 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 Mapeamento de atributos OTLP para 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 recurso, escopo e entidade 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 quando você usa a versão 0.140.0 ou mais recente do coletor do OpenTelemetry.

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 OTLP são mapeadas para estruturas de métricas do Cloud Monitoring. Para informações sobre esses mapeamentos, consulte:

O Google Cloud Observability converte 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 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 identificadores no Cloud Monitoring não oferecem suporte ao UTF-8 completo, os dados de métricas podem ser rejeitados:

  • 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 rastreamento

Independente de usar a API Telemetry ou a API Cloud Trace, os dados de rastreamento 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.

Confira a seguir um exemplo de dados de rastreamento que podem ser enviados de um aplicativo para seu projeto do Google Cloud :

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

Cada item em cada matriz scopeSpans.spans se torna um único intervalo armazenado:

  • O campo resource de cada intervalo contém uma cópia dos dados de resourceSpans.resource.attributes.
  • O campo instrumentation_scope de cada intervalo 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 rastreamento.

Para mais informações, consulte estes documentos:

Faturamento

O faturamento dos dados de registros, métricas e rastreamentos ingeridos usando a API Telemetry depende do indicador de telemetria. Para informações completas, consulte a página de faturamento.

Faturamento de dados de registros

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 seu projeto 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 individual, 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 desnecessários de recurso ou escopo antes de exportar os dados.
  • Se você não precisar dos metadados adicionais preservados no campo otel, use a opção de mapeamento legada, gcp.use_legacy_mapping, que impede o preenchimento do campo otel.

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 rastreamento

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

Como consultar dados de registro, métricas e rastreamento

Use as páginas do explorador (Análise de registros, Metrics Explorer e Explorador de traces) para consultar seus dados de registro, métrica e trace. Você também pode usar a página da Análise de observabilidade para analisar seus dados de registro e rastreamento 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 envolvê-los em chaves ({}) e aspas ("), de acordo com a especificação UTF-8 do PromQL. Por exemplo, as consultas a seguir 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 típicas devem funcionar.

  • As métricas delta podem não consultar 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 registros: as cotas e os limites da API Cloud Logging são aplicáveis.

  • 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 rastreamento: não há outras cotas ou limites aplicáveis.

A seguir