Visão geral da ingestão de OTLP

Este documento apresenta o uso da API Telemetry (OTLP), telemetry.googleapis.com, que implementa o protocolo OpenTelemetry. A API Telemetry permite ingerir dados de registro, métrica e trace formatados em OTLP no Google Cloud Observability:

  • Os registros de log OTLP são convertidos em entradas de registro e, em seguida, roteados e armazenados. Para mais informações sobre o processo de conversão, consulte a seção Ingestão de registros OTLP deste documento.
  • Os dados de métricas são ingeridos no Cloud Monitoring. Para informações sobre nomes de métricas e rótulos e as restrições de ingestão, consulte a seção Ingestão de métricas OTLP deste documento.
  • Os dados de trace são armazenados em um formato geralmente consistente com o OTLP. Para mais informações, consulte Ingestão de traces OTLP.

É possível enviar dados de telemetria para a API Telemetry de aplicativos que usam SDKs ou exportando de um coletor OpenTelemetry.

Se você estiver usando o Google Kubernetes Engine, poderá usar o OpenTelemetry gerenciado para GKE em vez de implantar e configurar manualmente um coletor OpenTelemetry que usa a API Telemetry.

Suporte a protocolo

O endpoint OTLP oferece suporte a 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 o uso do 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

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

Para um exemplo de autenticação ao usar a exportação direta de dados de trace, 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 Google Cloud projeto 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.

  • Conceder os seguintes papéis do Identity and Access Management (IAM, na sigla em inglês) ao usuário ou à conta de serviço usada pelo aplicativo:

Ingestão de OTLP

Esta seção descreve como os dados de registro, métrica e trace são convertidos de 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, seus 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 do Cloud Logging LogEntry contém um campo adicional, otel. Como os modelos de dados OTLP e 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 resourceLogs 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:

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 estão vinculadas 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 ao usar o coletor OpenTelemetry versão 0.140.0 ou mais recente.

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

O Google Cloud Observability converte métricas no formato de série temporal do Prometheus. Os nomes das métricas não podem ter um domínio ou 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 OpenTelemetry exclusivo, a conversão adiciona uma target_info métrica 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ótulos no Cloud Monitoring não oferecem suporte ao 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ótulos) 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 chaves de rótulos estão no conjunto _.. Todos os caracteres especiais são permitidos em valores de rótulos.

Para evitar a rejeição das métricas por esses motivos, use a replace_pattern função 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 o uso da 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 trace que podem ser enviados de um aplicativo para o seu Google Cloud projeto:

{
  "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 resourceSpans.resource.attributes dados.
  • O campo instrumentation_scope de cada intervalo contém uma cópia dos dados scopeSpans.scope.
  • Cada intervalo corresponde a uma entrada na matriz scopeSpans.spans. Campos como traceId, spanId e kind são mapeados em 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 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 seu Google Cloud projeto 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 de recurso determinam o recurso monitorado no LogEntryresultante.
  • 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 de 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 de coletor 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 de métricas 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 seu projeto não afeta a forma como as cobranças são calculadas para esses dados.

Como consultar dados de registro, métrica e trace

É possível usar as páginas do Explorer (Análise de registros, Metrics Explorer e Explorador de Traces) para consultar os dados de registro, métrica e trace. Você também pode usar a página Observability Analytics para analisar os dados de registro e trace usando o SQL.

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

  • Importante: a consulta de nomes de métricas e chaves de rótulos com caracteres especiais diferentes do dois-pontos (:) e do sublinhado (_) exige que você os coloque entre 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"}

  • A retenção do 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 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 indicador.

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