Migrar para o exportador OTLP

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Neste documento, descrevemos como modificar uma configuração do coletor OpenTelemetry que usa um exportador atual — neste caso, o exportador googlemanagedprometheus — para usar o exportador otlphttp 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, que precisa estar ativada no projeto. Ative a API Telemetry executando o comando a seguir:

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. Estes comandos pressupõem que você está usando a federação de identidade da carga de trabalho para o 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 projeto do Google Cloud .

Se a conta de serviço tiver um formato diferente, use 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.
• Execute o comando para conceder o papel roles/telemetry.metricsWriter.

Defina a variável de ambiente PROJECT_ID.

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

env:
- name: PROJECT_ID
  value: PROJECT_ID

Localize 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 vai causar problemas porque a estrutura dos descritores de métricas criados pelos dois métodos é diferente. Elas são métricas separadas.
• Se você estiver usando métricas do Prometheus, haverá colisões até que você remova o exportador googlemanagedpromethus.

A configuração atualizada vai ficar assim:

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 seus painéis e 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 o estilo do Prometheus, usando substituições de sublinhado.

Observação: como a API Telemetry define o tipo de valor de todas as métricas como DOUBLE, esperamos que haja possíveis colisões de tipo de valor, principalmente se você já tiver enviado métricas INT64 target_info. Se você encontrar colisões, a melhor solução a longo prazo é excluir o descritor de métrica das métricas INT64 target_info. Para excluir esse descritor do escopo de métricas, use este script Golang.

Remover a configuração do exportador anterior

Depois de atualizar os painéis e alertas para se referirem às métricas exportadas por otlphttp, remova o exportador antigo, googlemanagedprometheus nesse caso, da configuração. A configuração revisada é 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, os painéis e as políticas de alertas atuais vão continuar funcionando quando você mudar para o exportador OTLP.

No entanto, se você usou o exportador googlemanagedprometheus para coletar e enviar dados que foram originalmente emitidos usando OTLP ou se você raspou métricas do Prometheus com caracteres UTF-8, será necessário atualizar seus 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 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 o ponto (.) e a 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 exportador googlemanagedprometheus 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 alerta para usar os novos nomes de métricas ou unir os nomes antigos e novos.

Não recomendamos escrever regras de processador para recriar essas transformações e 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 você não poderá usar facilmente recursos de código aberto que referenciam os nomes de métricas UTF-8.