O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Migrar coletores para usar exportadores OTLP

A API Telemetry (OTLP) é uma implementação do protocolo OpenTelemetry. O suporte ao OTLP permite adicionar exportadores genéricos otlphttp e otlp_grpc/otlp_logs à configuração do coletor, evitando exportadores específicos do fornecedor. Os aplicativos podem enviar dados de registro, métricas e traces para a API Telemetry.

Este guia é para você se a configuração do coletor usar o googlecloud exportador ou o googlemanagedprometheus exportador:

Dados de registro: migre do googlecloud exportador para o otlp_grpc/otlp_logs exportador.
Dados de métricas: migre do googlemanagedprometheus exportador para o otlphttp exportador.
Dados de trace: migre do googlecloud exportador para o otlphttp exportador.

Para migrar para exportadores OTLP, siga estas etapas:

Ativar a API Telemetry
Autorizar a conta de serviço do coletor
Definir a variável de ambiente GOOGLE_CLOUD_PROJECT
Adicionar a extensão googleclientauth
Adicionar os exportadores otlphttp e otlp_grpc/otlp_logs
Adicionar processadores
Atualizar pipelines de serviço
Validar sua configuração
Migrar painéis e políticas de alertas
Remover exportadores específicos do fornecedor

Ativar a API Telemetry

Os exportadores OTLP gravam na API Telemetry. Portanto, essa API precisa estar ativada no seu projeto. Para ativar a API Telemetry, execute o seguinte comando:

gcloud services enable telemetry.googleapis.com

Autorizar a conta de serviço do coletor

O coletor faz a autenticação em Google Cloud APIs usando a identidade do ambiente em que é executado. A conta de serviço que executa o coletor precisa ter permissão para usar a API Telemetry para gravar dados de registro, métricas e traces. Além disso, como a API Telemetry é uma API de consumidor, é necessário especificar explicitamente o Google Cloud projeto cuja cota é consumida por chamadas de API e conceder à conta de serviço as permissões necessárias para consumir a cota desse projeto.

Funções exigidas

Para garantir que a conta de serviço que executa o coletor tenha as permissões necessárias para enviar dados de registro, métricas e traces, peça ao administrador para conceder as seguintes funções do IAM à conta de serviço que executa o coletor no seu projeto:

Gravador de telemetria do Cloud (roles/telemetry.writer)
Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)

Essas funções predefinidas contêm as permissões necessárias para enviar dados de registro, métricas e traces. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para enviar dados de registro, métricas e traces:

logging.logEntries.create
monitoring.timeSeries.create
telemetry.traces.write
serviceusage.services.use

Conta de serviço do Kubernetes

Se você implantar o coletor no Google Kubernetes Engine (GKE) usando a Federação de identidade da carga de trabalho para GKE, conceda as funções necessárias à sua conta de serviço do Kubernetes.

É possível usar os comandos a seguir para conceder as funções necessárias se a cota da API estiver sendo extraída do mesmo Google Cloud projeto que é o destino das chamadas da API Telemetry. Antes de executar os comandos, substitua PROJECT_ID pelo ID do seu projeto. No entanto, se você usar um projeto de cota separado, substitua PROJECT_ID no segundo comando pelo ID do projeto de cota:

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

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

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

Conta de serviço para a Federação de identidade da carga de trabalho para GKE

Se você configurou uma conta de serviço para a Federação de Identidade da Carga de Trabalho para GKE, 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 gmp-test-sa pelo nome da sua conta de serviço.
Execute o comando para conceder as funções necessárias para gravar dados de registro, métricas e traces.

Outra conta de serviço

Se você executar o coletor em uma VM do Compute Engine ou fora do GKE, conceda as funções necessárias à Google Cloud conta de serviço usada pela implantação.

Definir a variável de ambiente `GOOGLE_CLOUD_PROJECT`

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

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

Adicionar a extensão `googleclientauth`

Adicione a extensão googleclientauth à configuração do coletor. A API Telemetry é uma API de consumidor e exige que você especifique o projeto Google Cloud e o projeto de cota. O resultado será semelhante a este:

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

Adicionar os exportadores `otlphttp` e `otlp_grpc/otlp_logs`

Use o exportador otlphttp para enviar dados de métricas e traces formatados em OTLP para o projeto e o exportador otlp_grpc/otlp_logs para enviar dados de registro. Configure os dois exportadores com a extensão googleclientauth.

O resultado será semelhante a este:

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

Para o exportador otlp_grpc/otlp_logs, o campo endpoint precisa ser especificado usando o formato host:port.

Adicionar processadores

Esta seção lista os processadores que você precisa adicionar ao coletor. Há outros processadores que você pode usar. Por exemplo, as configurações do coletor do OpenTelemetry Collector criado pelo Google geralmente incluem o processador memory_limiter e um que transforma dados de métricas. Para conferir um exemplo, consulte o OpenTelemetry Collector criado pelo Google no GKE.

Adicionar o processador `resource/gcp_project_id`

Adicione um processador resource que capture informações sobre o seu Google Cloud projeto.

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

Adicionar o processador `resourcedetection`

Se você estiver executando no Google Cloud, considere adicionar o resourcedetection processador. Esse processador pode descobrir automaticamente informações sobre sua arquitetura.

A configuração a seguir procura as variáveis de ambiente padrão do OpenTelemetry e, em seguida, consulta o Google Cloud servidor de metadados para coletar informações sobre sua infraestrutura:

  resourcedetection:
    detectors: ["env", "gcp"]

Adicionar o processador `batch`

Para enviar a telemetria de maneira mais eficiente para o Google Cloud projeto, recomendamos que você use o batch processador.

Por exemplo, o coletor do OpenTelemetry Collector criado pelo Google usa a seguinte configuração para o processador em lote:

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

Adicionar o processador `metricstarttime`

Adicione o processador metricstarttime à configuração. Esse processador garante que as métricas cumulativas incluam um horário de início e um horário de observação. Por padrão, as métricas do Prometheus incluem apenas um horário atual. Portanto, se você omitir esse processador e o aplicativo gerar métricas do Prometheus, os dados de métricas poderão ser rejeitados ou você poderá ver picos de dados.

Adicione esse processador se o coletor receber métricas do Prometheus.

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

Adicionar o processador de transformação

Para preservar a origem e a versão da instrumentação nos dados de registro, adicione o seguinte processador transform:

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

Atualizar pipelines de serviço

Em seguida, atualize os pipelines do coletor para usar os exportadores otlp_grpc/otlp_logs e otlphttp. Para dados de registro e trace, essas instruções substituem o exportador atual pelo exportador OTLP apropriado. Para os dados de métricas, essas instruções resultam em gravações duplas. Essa abordagem permite verificar se o exportador OTLP está enviando dados de métricas para o Google Cloud projeto. Ela também permite atualizar gráficos e políticas de alertas antes de desativar os fluxos de dados do exportador original.

Faça as seguintes mudanças nas configurações de pipeline do coletor:

Adicione a extensão googleclientauth à entrada service.
Para o pipeline de registros, substitua googlecloud/logging por otlp_grpc/otlp_logs e adicione os seguintes processadores à lista de processadores do pipeline:
- resource/gcp_project_id
- transform/otlp_grpc/preserve_instrumentation_source_version
- resourcedetection (se você adicionou esse processador)
- batch
Essa configuração executa uma única gravação de dados de registro. Se você quiser gravar os dados de registro duas vezes, adicione o exportador otlp_grpc/otlp_logs à lista de exportadores.
Para o pipeline de métricas, adicione o exportador otlphttp à lista de exportadores do pipeline junto com o exportador googlemanagedprometheus e, em seguida, adicione os seguintes processadores:
- resource/gcp_project_id
- metricstarttime
- resourcedetection (se você adicionou esse processador)
- batch
Essa configuração executa uma gravação dupla de dados de métricas. Depois de validar o fluxo de dados de métricas e atualizar gráficos e políticas de alertas, remova o exportador do Prometheus.
Para o pipeline de traces, substitua o exportador atual pelo exportador otlphttp e adicione os seguintes processadores:
- resource/gcp_project_id
- resourcedetection (se você adicionou esse processador)
- batch
Essa configuração executa uma única gravação de dados de trace.

O resultado dessas mudanças é semelhante a este:

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

O snippet anterior usa o receptor OTLP para dados de registro, métricas e traces. A configuração do coletor pode ser diferente. Por exemplo, se você tiver um aplicativo que grava dados de registro estruturados, o receptor filelog será apropriado.

Validar sua configuração

Reinicie a implantação e verifique se os otlphttp e otlp_grpc/otlp_logs exportadores estão enviando dados para o Google Cloud projeto. Para verificar a configuração, faça o seguinte:

Consulte as entradas de registro para erros relacionados à gravação de dados de telemetria.
Confira as taxas de erro da API Cloud Logging, da API Cloud Monitoring e da API Telemetry.
Visualize série temporal usando o Metrics Explorer.

Migrar painéis e políticas de alertas

Atualize seus gráficos e painéis da seguinte maneira:

Se você estiver monitorando o uso da API Cloud Logging ou da API Cloud Monitoring com gráficos ou políticas de alertas, crie outros gráficos ou políticas de alertas para monitorar o uso da API Telemetry.
Se os receptores de métricas incluírem um receptor otlp ou se o coletor extrair métricas do Prometheus com caracteres UTF-8, atualize os gráficos e painéis. O exportador otlphttp gera métricas diferentes do exportador googlemanagedprometheus. Para mais informações, consulte Diferenças no formato das métricas exportadas.

Não é necessário atualizar os gráficos e painéis se o coletor receber apenas dados de métricas do Prometheus.
Se os pipelines de métricas incluírem um prometheus receptor, ocorrerão colisões de fluxo de dados entre as métricas geradas pelos otlphttp e googlemanagedprometheus exportadores. Para resolver estas colisões, remova o exportador googlemanagedprometheus.

Diferenças no formato das métricas exportadas

As atualizações nos gráficos e políticas de alertas com base em métricas são necessárias devido às seguintes diferenças entre as métricas exportadas pelos exportadores OTLP e 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 diferem entre as métricas ingeridas usando o exportador googlemanagedprometheus e aquelas ingeridas usando o otlphttp exportador. 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.

As regras de transformação não se aplicam a métricas com caracteres UTF-8. Portanto, é necessário reescrever os painéis e as políticas de alertas para usar os novos nomes de métricas ou consultas que combinam 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 googlemanagedprometheus exportador. Isso mantém a compatibilidade com versões anteriores, mas sacrifica a compatibilidade com versões futuras, e não será possível usar recursos de código aberto que referenciam os nomes de métricas UTF-8.

Remover exportadores específicos do fornecedor

Depois de validar os novos fluxos de dados e atualizar os painéis e as políticas de alertas, remova os exportadores googlecloud/logging e googlemanagedprometheus da configuração do coletor. Talvez seja necessário remover os processadores que foram usados apenas pelos exportadores removidos da configuração.

É necessário atualizar a lista de exportadores e os pipelines de serviço.

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

Solução de problemas

Esta seção descreve como resolver falhas que podem ocorrer ao migrar a configuração do coletor.

Dados de métricas ausentes ou picos nos dados de métricas

Se os dados de métricas estiverem ausentes ou contiverem picos, verifique se você adicionou o processador metricstarttime à configuração do coletor. Para mais informações, consulte Adicionar o metricstarttime processador.

Você também pode revisar os registros do coletor, os registros do sistema e os registros de auditoria de acesso a dados do Monitoring. Por exemplo, se uma gravação em uma série temporal falhar, um registro de auditoria de acesso a dados que inclui o motivo da falha será gerado.

Mensagens de erro sobre a gravação de série temporal

O sistema gera mensagens de erro quando uma tentativa de gravar dados em uma série temporal falha. Você pode usar essas mensagens para entender por que a gravação falhou e como resolver o problema.

Mensagem de erro que indica uma incompatibilidade de valor:
```
"One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."
```
Esse erro ocorre se você enviou métricas target_info INT64 anteriormente, porque a API Telemetry define o tipo de valor de todas as métricas como DOUBLE. A melhor solução de longo prazo é excluir o descritor de métrica para as métricas target_info INT64. Para excluir esse descritor do seu escopo de métricas, use este script do Golang.
Mensagem de erro que indica várias fontes gravando dados de série temporal:
```
"One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."
```
Para resolver esse problema, remova o exportador googlemanagedprometheus da configuração do coletor. Para mais informações, consulte Remover exportadores específicos do fornecedor.

A seguir

Visão geral dos exemplos de instrumentação baseados em coletores refere-se a aplicativos de exemplo que podem ser baixados e instalados. Cada aplicativo de exemplo inclui um coletor completo que exporta dados de métricas e traces usando a API Telemetry.
Implantar o OpenTelemetry Collector criado pelo Google no Google Kubernetes Engine inclui uma configuração completa do coletor.