Migrar para o exportador OTLP

Este documento descreve como modificar uma configuração de métricas do coletor do OpenTelemetry que usa um exportador atual (nesse caso, o googlemanagedprometheus exportador) para usar o otlphttp exportador e a API Telemetry (OTLP), telemetry.googleapis.com.

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.

Ativar a API Telemetry

O exportador otlphttp grava na API Telemetry. Portanto, essa API precisa estar ativada no seu projeto. Ative a API Telemetry executando o seguinte comando:

gcloud services enable telemetry.googleapis.com

Autorizar a conta de serviço do Kubernetes

A conta de serviço do Kubernetes precisa ter permissão para usar a API Telemetry. Os comandos a seguir concedem o papel necessário do Identity and Access Management (IAM) à conta de serviço do Kubernetes. Esses comandos pressupõem que você esteja usando a Federação de Identidade da Carga de Trabalho para GKE:

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/telemetry.metricsWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Substitua a variável PROJECT_ID pelo ID do seu Google Cloud projeto.

Se a conta de serviço tiver um formato diferente, você poderá usar o comando na documentação do Google Cloud Managed Service para Prometheus para autorizar a conta de serviço, com as seguintes mudanças:

  • Substitua o nome da conta de serviço gmp-test-sa pela sua conta de serviço.
  • Execute o comando para conceder o papel roles/telemetry.metricsWriter.

Definir a variável de ambiente PROJECT_ID

Defina a variável de ambiente PROJECT_ID na implantação do coletor. O resultado será semelhante a este:

env:
- name: PROJECT_ID
  value: PROJECT_ID

Localizar o exportador a ser substituído

No arquivo de configuração, localize o exportador e o serviço que o usa:

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

Adicionar configuração para o exportador otlphttp

Nesta etapa, você adiciona o exportador otlphttp e o processador metricstarttime à configuração. Esse exportador adicional faz com que o coletor grave as métricas duas vezes.

  • Se você estiver usando métricas nativas do OTLP, a gravação dupla não causará problemas porque a estrutura dos descritores de métricas criados pelos dois métodos é diferente. São métricas separadas.
  • Se você estiver usando métricas do Prometheus, verá colisões até você remover o exportador googlemanagedpromethus.

A configuração atualizada será semelhante a esta: Defina o processador metricstarttime ao migrar:

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

Depois de gravar as métricas duas vezes, atualize os painéis e as políticas de alertas para usar os novos nomes de métricas gerados pelo exportador otlphttp. O exportador otlphttp não renomeia as métricas para serem "estilo Prometheus", usando substituições de sublinhado.

Remover a configuração do exportador anterior

Depois de atualizar os painéis e alertas para se referir às métricas exportadas por otlphttp, remova o exportador antigo, googlemanagedprometheus nesse caso, da configuração. A configuração revisada será semelhante a esta:

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

Migrar painéis e políticas de alertas, se necessário

Se você usou o exportador googlemanagedprometheus apenas para dados de métricas do Prometheus, quando mudar para o exportador OTLP, os painéis e as políticas de alertas atuais continuarão funcionando.

No entanto, se você usou o exportador googlemanagedprometheus para coletar e enviar dados que foram originalmente emitidos usando o OTLP ou se você coletou métricas do Prometheus com caracteres UTF-8, será necessário atualizar os painéis e alertas para usar o nome da métrica UTF-8.

Isso ocorre devido às seguintes diferenças entre as métricas exportadas usando o OTLP e as métricas exportadas usando o exportador googlemanagedprometheus:

  • A API Telemetry permite o uso de caracteres de ponto (.) e barra (/) em nomes de métricas. O exportador googlemanagedprometheus converte todas as instâncias desses caracteres no caractere de sublinhado (_). Por exemplo, uma métrica OTLP chamada prometheus.googleapis.com/foo.bar/gauge é exportada literalmente pelo exportador OTLP, mas é exportada como prometheus.googleapis.com/foo_bar/gauge pelo exportador googlemanagedprometheus.

    Quando as métricas são ingeridas, o Cloud Monitoring cria descritores de métricas com base nos nomes. A diferença na forma como os caracteres de ponto (.) e barra (/) são processados pelos caminhos de ingestão significa que os descritores de métricas resultantes são diferentes entre as métricas ingeridas usando o exportador googlemanagedprometheus e aquelas ingeridas usando o exportador otlphttp. Se você usar os dois caminhos de ingestão, terá dois conjuntos de métricas. Para receber resultados completos ao consultar, é necessário unir manualmente os resultados das versões do Prometheus e do OTLP das métricas.

  • A API Telemetry não anexa uma unidade a um nome de métrica quando uma unidade está presente e não anexa um sufixo _total aos contadores. Portanto, uma métrica exportada como prometheus.googleapis.com/foo/counter ao usar a API Telemetry é exportada como prometheus.googleapis.com/foo_seconds_total/counter pelo exportador googlemanagedprometheus. Essa diferença também se aplica aos sufixos _total e _ratio.

Para mais informações sobre as diferenças entre as métricas, consulte Diferenças entre o googlemanagedprometheus exportador e a API Telemetry.

Como as regras de transformação não se aplicam a métricas com caracteres UTF-8, é necessário reescrever os painéis e as políticas de alertas para usar os novos nomes de métricas ou unir os nomes de métricas antigos e novos.

Não recomendamos escrever regras de processador para recriar essas transformações para continuar gravando métricas UTF-8 como se elas fossem coletadas pelo exportador googlemanagedprometheus. Isso mantém a compatibilidade com versões anteriores, mas sacrifica a compatibilidade com versões futuras, e não será possível usar facilmente recursos de código aberto que referenciam os nomes de métricas UTF-8.