Implantar o OpenTelemetry gerenciado para GKE

Neste documento, explicamos como configurar o OpenTelemetry gerenciado para o GKE enviar traces, métricas e registros do protocolo OpenTelemetry (OTLP) para o Google Cloud Observability de aplicativos em execução no GKE.

Para mais detalhes sobre como o OpenTelemetry gerenciado para GKE funciona, consulte OpenTelemetry gerenciado para GKE.

Use o OpenTelemetry gerenciado para GKE para fazer o seguinte:

  • Configure as cargas de trabalho em execução no GKE para enviar traces, métricas e registros do protocolo OpenTelemetry (OTLP) ao coletor gerenciado.
  • Receber traces, métricas e registros do OpenTelemetry Protocol (OTLP) dos aplicativos em execução no GKE.
  • Exportar esses dados para o Google Cloud Observability.

Se você precisar de filtragem e controles no nível do coletor, use o coletor do OpenTelemetry criado pelo Google em vez dessa oferta gerenciada.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  2. Instale a CLI do Google Cloud.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  5. Crie ou selecione um projeto do Google Cloud .

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
    • Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  6. Verifique se você tem as permissões necessárias para concluir este guia.

  7. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  8. Ative as APIs do GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring e API Cloud Trace, se ainda não estiverem ativadas:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. 

    gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  9. Instale a CLI do Google Cloud.

  10. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  11. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  12. Crie ou selecione um projeto do Google Cloud .

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
    • Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  13. Verifique se você tem as permissões necessárias para concluir este guia.

  14. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  15. Ative as APIs do GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring e API Cloud Trace, se ainda não estiverem ativadas:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. 

    gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
    16.

Requisitos

Para usar o OpenTelemetry gerenciado para GKE, você precisa atender aos seguintes requisitos:

  • O cluster precisa ter o GKE versão 1.34.1-gke.2178000 ou posterior. Para configurar o protocolo de exportação OTLP como gRPC no recurso personalizado de instrumentação, use o GKE versão 1.37.1-gke.1697000 ou mais recente.
  • CLI gcloud ativada com a versão 576.0.0 ou mais recente.
  • Se você usa o Terraform para provisionar sua infraestrutura do GKE, use o terraform-provider-google na versão v8.8.0 ou posterior.

Funções exigidas

Para receber as permissões necessárias para ativar e usar o OpenTelemetry gerenciado pelo GKE, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Custos

Consulte Faturamento para detalhes sobre os custos relacionados ao uso do OpenTelemetry gerenciado para o GKE.

Ativar o OpenTelemetry gerenciado para GKE em um cluster

Para configurar o OpenTelemetry gerenciado para o GKE, faça o seguinte:

  • Ativar o OpenTelemetry gerenciado para GKE em um cluster.
  • Configure o aplicativo que você está monitorando para enviar sinais ao endpoint do coletor gerenciado.

Quando você ativa o OpenTelemetry gerenciado para o GKE, os seguintes objetos são implantados no cluster:

  • Uma implantação do coletor do OpenTelemetry gerenciado pelo GKE que é implantada no namespace gke-managed-otel. Os endpoints do coletor do OpenTelemetry gerenciados no cluster para registros, métricas e traces são os seguintes:
    • Endpoint HTTP: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318
    • Endpoint gRPC: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317

  • Uma definição de recurso personalizado, instrumentations.telemetry.googleapis.com, que pode ser usada para definir a configuração automática das cargas de trabalho.

    Para mais detalhes sobre recursos personalizados, consulte recurso personalizado na documentação do Kubernetes.

Ativar em um novo cluster

Para ativar o OpenTelemetry gerenciado para GKE em um novo cluster, siga estas etapas:

gcloud

Para um cluster do Autopilot, use o seguinte comando:

gcloud container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região ou zona.
  • VERSION: a versão do GKE. Consulte os Requisitos para saber qual é a versão mínima que você pode usar.

Para um cluster padrão, use o seguinte comando:

gcloud container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região ou zona.
  • VERSION: a versão do GKE. Consulte os Requisitos para saber qual é a versão mínima que você pode usar.

Console

  • Para um cluster do Autopilot, faça o seguinte:

    1. No console do Google Cloud , acesse a página Criar um cluster do Autopilot.

      Acessar "Criar um cluster do Autopilot"

    2. No painel de navegação, clique em Configurações avançadas.

    3. Na seção Operações, selecione Ativar o OpenTelemetry gerenciado.

    4. Clique em Criar.

  • Para um cluster padrão, faça o seguinte:

    1. No console do Google Cloud , acesse a página Criar um cluster do Kubernetes.

      Acesse Criar um cluster do Kubernetes

    2. No painel de navegação, clique em Configurações avançadas.
    3. Na linha OpenTelemetry gerenciado, clique em Editar configuração.
    4. Selecione Ativar o OpenTelemetry gerenciado.
    5. Clique em Salvar.
    6. Clique em Criar.

Terraform

Para ativar o OpenTelemetry gerenciado para GKE em um novo cluster usando o Terraform, consulte o exemplo a seguir:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Para saber mais como usar o Terraform, consulte o Suporte do Terraform para GKE.

Ativar em um cluster atual

Para ativar o OpenTelemetry gerenciado para GKE em um cluster atual, siga estas etapas:

gcloud

  1. Verifique se a versão do cluster atende aos requisitos. Para detalhes sobre como fazer upgrade de um cluster, consulte Upgrades de cluster padrão e Upgrades de cluster do Autopilot.

  2. Ative o OpenTelemetry gerenciado para o GKE usando o seguinte comando:

    gcloud container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION

    Substitua:

    • CLUSTER_NAME: o nome do cluster.
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • LOCATION: a região ou zona.

Console

  1. Verifique se a versão do cluster atende aos requisitos. Para detalhes sobre como fazer upgrade de um cluster, consulte Upgrades de cluster padrão e Upgrades de cluster do Autopilot.

  2. No console do Google Cloud , acesse a página de clusters do Kubernetes:

    Acessar os clusters do Kubernetes

  3. Clique no nome do cluster.

  4. Na lista Recursos, localize a opção OpenTelemetry gerenciado. Se ele estiver listado como desativado, clique em Editar e selecione Ativar o OpenTelemetry gerenciado.

  5. Clique em Salvar alterações.

Terraform

Para ativar o OpenTelemetry gerenciado para GKE em um cluster, adicione o bloco managed_opentelemetry_config ao recurso google_container_cluster, como no exemplo a seguir:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Para saber mais como usar o Terraform, consulte o Suporte do Terraform para GKE.

Configurar o aplicativo para usar o coletor do OpenTelemetry gerenciado

Os aplicativos precisam ser configurados para enviar sinais ao endpoint do coletor gerenciado. Quando os aplicativos são configurados, o coletor gerenciado do OpenTelemetry recebe indicadores dos aplicativos em execução no cluster em que o coletor está ativado. Os indicadores do aplicativo incluem traces, métricas e registros.

Para enviar sinais do OpenTelemetry, os aplicativos precisam já estar instrumentados para gerar métricas do OpenTelemetry. Para mais detalhes, consulte cargas de trabalho compatíveis.

É possível configurar o aplicativo manualmente para enviar sinais ao endpoint do coletor gerenciado ou usar a configuração automática. Não recomendamos o uso dos dois métodos juntos para a mesma carga de trabalho, porque a configuração automática pode substituir as alterações manuais. Essa combinação pode dificultar o acompanhamento das mudanças na configuração.

As seções a seguir descrevem como configurar aplicativos para enviar sinais ao coletor usando a configuração automática.

Configurar a configuração automática

A configuração automática usa variáveis de ambiente para configurar as cargas de trabalho para enviar indicadores ao endpoint do coletor gerenciado.

Para ativar a injeção automática de variáveis de ambiente em pods, use o recurso personalizado de instrumentação. As variáveis de ambiente têm a configuração do OpenTelemetry e podem ser injetadas em alguns pods com rótulos correspondentes em um namespace ou em todos os pods em um namespace.

Em seguida, quando um aplicativo é implantado no namespace, o GKE usa a configuração para injetar automaticamente variáveis de ambiente nos pods em que as cargas de trabalho são executadas.

  1. Para configurar o recurso personalizado de instrumentação, faça o seguinte:

    1. Salve o seguinte manifesto de instrumentação em um arquivo chamado otlp-auto-config-namespace.yaml:

      apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL

      Substitua:

      • NAMESPACE: o namespace que contém os pods que você quer segmentar para a instrumentação automática. Use default para segmentar o namespace padrão.
      • NAME: o nome do objeto Instrumentation no arquivo de manifesto.
      • (Opcional) O rótulo anexado aos pods a serem segmentados. Se um seletor vazio for especificado ({}), todos os pods no namespace serão segmentados.
        • KEY: a chave do rótulo.
        • VALUE: o valor do rótulo.
      • TRACE_RATIO: a proporção de dados de trace a serem coletados. Se não for especificado, o padrão será 1.0. Para mais detalhes, consulte Modificar a taxa de amostragem de trace.
      • METRICS_INTERVAL: o intervalo, em milissegundos, dos dados de monitoramento a serem coletados. O padrão é 30000. O valor precisa ser não negativo, com um mínimo de 5.000 ms, um máximo de 300.000 ms e um múltiplo de 5.000 ms. Para mais detalhes, consulte Modificar o intervalo de exportação de métricas.

    2. Se você quiser modificar alguma das configurações, consulte a seção a seguir para modificar a configuração.

    3. Aplique a configuração executando o seguinte comando:

      kubectl apply -f otlp-auto-config-namespace.yaml

  2. Para injetar as variáveis de ambiente automaticamente, implante o aplicativo no namespace do cluster que tem a configuração aplicada.

    • Para aplicar a configuração a uma carga de trabalho que ainda não está em execução no namespace, implante a carga de trabalho usando o seguinte comando:

      kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE

      Substitua:

      • DEPLOYMENT_NAME: o nome da implantação.
      • NAMESPACE: o namespace.

    • Para aplicar a configuração a uma carga de trabalho que já está em execução no namespace, reimplante a carga de trabalho usando o seguinte comando:

      kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

      Substitua:

      • DEPLOYMENT_NAME: o nome da implantação.
      • NAMESPACE: o namespace.

Depois de aplicar a configuração ao cluster, o GKE configura automaticamente todas as cargas de trabalho quando elas são implantadas no cluster. As cargas de trabalho são instrumentadas injetando variáveis de ambiente nos pods em que as cargas de trabalho são executadas.

Quando uma carga de trabalho configurada com essas variáveis de ambiente é executada em um cluster em que o coletor gerenciado é implantado, ela envia sinais do OpenTelemetry para o coletor gerenciado. Esses indicadores estão disponíveis para visualização no Google Cloud Observability.

Para mais detalhes sobre como visualizar os indicadores, consulte Ver telemetria. Para ver um exemplo, consulte Gerar telemetria de amostra.

Modifique a configuração

Para modificar a configuração, faça o seguinte:

  1. Modifique o arquivo de manifesto de instrumentação.

  2. Aplique a configuração modificada.

  3. Implante novamente ou reinicie os aplicativos no namespace correspondente do cluster depois de aplicar a configuração modificada.

Para mais detalhes sobre essas etapas, siga as instruções na seção Configurar a configuração automática.

Configurar o protocolo de exportação do OTLP (HTTP ou gRPC)

Por padrão, a configuração automática define as cargas de trabalho para exportar telemetria por HTTP. No GKE versão 1.37.1-gke.1697000 e posterior, é possível configurar o recurso personalizado de instrumentação para exportar telemetria por HTTP ou gRPC.

Um recurso personalizado de instrumentação é compatível com apenas um protocolo para todos os provedores. Para usar o gRPC, defina o exportador como otlp_grpc: {} para cada provedor que você usa e defina qualquer provedor não utilizado como null. Por exemplo, para desativar as métricas, use meter_provider: null.

O exemplo a seguir é um arquivo de manifesto de instrumentação configurado para exportar telemetria por gRPC para os provedores de trace, métricas e geração de registros:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
      processors:
      - batch:
          exporter:
            otlp_grpc: {}
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
          exporter:
            otlp_grpc: {}
    logger_provider:
      processors:
      - batch:
          exporter:
            otlp_grpc: {}

Substitua:

  • NAMESPACE: o namespace que contém os pods que você quer segmentar para a instrumentação automática. Use default para segmentar o namespace padrão.
  • NAME: o nome do objeto de instrumentação no arquivo de manifesto.
  • (Opcional) O rótulo anexado aos pods a serem segmentados. Se um seletor vazio for especificado ({}), todos os pods no namespace serão segmentados.
    • KEY: a chave do rótulo.
    • VALUE: o valor do rótulo.
  • TRACE_RATIO: a proporção de dados de trace a serem coletados. Se não for especificado, o padrão será 1.0. Para mais detalhes, consulte Modificar a taxa de amostragem de trace.
  • METRICS_INTERVAL: o intervalo, em milissegundos, dos dados de monitoramento a serem coletados. O padrão é 30000. O valor precisa ser não negativo, com um mínimo de 5.000 ms, um máximo de 300.000 ms e um múltiplo de 5.000 ms. Para mais detalhes, consulte Modificar o intervalo de exportação de métricas.

Modificar a quantidade ou a frequência da coleta de dados

É possível modificar a quantidade de dados de trace coletados alterando a taxa de amostragem de trace.

É possível alterar a frequência com que os dados de monitoramento são enviados ao Cloud Monitoring modificando o intervalo de exportação de métricas.

Não é possível modificar a quantidade ou a frequência dos dados de registro coletados. No entanto, é possível desativar a coleta de todos os dados de geração de registros, métricas ou traces. Veja mais detalhes em Selecionar o tipo de indicador a ser coletado.

Modificar a taxa de amostragem de trace

Uma carga de trabalho pode gerar uma grande quantidade de dados de trace. Para sua própria situação, é importante determinar o equilíbrio entre o custo de coleta e armazenamento de dados e o nível de detalhes necessário para que os dados sejam úteis.

O comportamento padrão do SDK do OpenTelemetry é always_on, que equivale a uma proporção de 1.

Veja a seguir um exemplo da configuração da taxa de amostragem de trace. Neste exemplo, a proporção é de 0,25, então os dados de trace são coletados a uma taxa de 25%. Modifique esse número para alterar a taxa de amostragem.

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

Modificar o intervalo de exportação de métricas

O intervalo de exportação de métricas determina a granularidade dos dados que você pode ver nos gráficos do Cloud Monitoring.

Veja a seguir um exemplo da configuração do intervalo de exportação de métricas. Neste exemplo, o intervalo de exportação é de 30.000 ms.

O intervalo de exportação de métricas é usado para especificar o intervalo de atraso entre o início de duas exportações consecutivas de métricas do SDK do OpenTelemetry.

O valor desse intervalo precisa ser não negativo, com um mínimo de 5.000 ms, máximo de 300.000 ms e múltiplo de 5.000 ms. O valor é expresso em milissegundos.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Selecione os tipos de indicadores que serão coletados

Para controlar quais tipos de indicadores são coletados de uma carga de trabalho, desative os tipos de indicadores que você não quer coletar. Os tipos de indicadores são traces, métricas e registros.

Desative os tipos de sinal usando as variáveis de ambiente no contêiner em que a carga de trabalho é executada. Para modificar as variáveis de ambiente, modifique o recurso personalizado de instrumentação e reimplante a carga de trabalho no contêiner.

O exemplo a seguir é um arquivo de manifesto de instrumentação configurado para a coleta de apenas dados de trace. A coleta de registros e métricas está desativada porque meter_provider e logger_provider estão definidos como null.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

Coletar dados de comandos e respostas multimodais

Na versão 1.35.2-gke.1210000 ou mais recente do cluster do GKE, é possível configurar o OpenTelemetry gerenciado para o GKE coletar dados de comandos multimodais e respostas.

Essa funcionalidade está disponível para agentes ReAct do LangGraph e agentes de IA generativa criados com o framework do Kit de Desenvolvimento de Agente (ADK).

Quando você coleta dados de comandos e respostas multimodais com o OpenTelemetry gerenciado para GKE, todo o conteúdo dos comandos e respostas do usuário final é coletado. Esses dados de comando e resposta são armazenados em um bucket do Cloud Storage. Para saber como gerenciar o bucket de armazenamento, incluindo o controle de acesso ou a exclusão de dados, consulte a documentação do Cloud Storage.

É possível usar produtos como o Model Armor e a Proteção de Dados Sensíveis para gerenciar dados sensíveis que podem estar nos comandos e nas respostas.

Para configurar o OpenTelemetry gerenciado para o GKE para coletar dados de comandos multimodais e respostas, faça o seguinte:

  1. Configure seu Google Cloud projeto e o SDK que você está usando seguindo as instruções na seção Coletar comandos multimodais e respostas.

  2. Crie ou identifique um bucket do Cloud Storage para coletar comandos e respostas multimodais. Para mais detalhes, consulte Criar um bucket.

  3. Conceda à conta de serviço usada pelo aplicativo a permissão storage.objects.create para o bucket do Cloud Storage.

    Essa permissão permite que o aplicativo grave objetos no bucket do Cloud Storage. Esses repositórios de objetos armazenam os comandos e as respostas que o aplicativo agêntico cria e recebe. Para mais informações, consulte Definir e gerenciar políticas do IAM em buckets.

  4. Configure o campo promptsResponses.uploadBasePath no recurso personalizado de instrumentação, por exemplo:

    apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

    Substitua BUCKET_NAME pelo nome do bucket do Cloud Storage.

Quando o recurso personalizado de instrumentação é atualizado e as cargas de trabalho são reiniciadas, as variáveis de ambiente que configuram os comandos e as respostas são injetadas nos contêineres das cargas de trabalho.

Para mais detalhes sobre os tipos de mídia que podem ser coletados e como explorar seus comandos e respostas multimodais, consulte Coletar e visualizar comandos e respostas multimodais.

Desativar a configuração automática de cargas de trabalho

Para desativar a instrumentação automática de cargas de trabalho com a configuração especificada, exclua o recurso personalizado de instrumentação do cluster. Para isso, use o seguinte comando:

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

Substitua:

  • INSTRUMENTATION_NAME: o nome do recurso personalizado de instrumentação.
  • NAMESPACE: o namespace que contém os pods em que você quer desativar a configuração automática.

Para desativar temporariamente a injeção automática de variável de ambiente e preservar a configuração de autoinstrumentação para uso futuro, defina autoInstrumentationConfig.configInjection.enabled como false e aplique o recurso personalizado atualizado.

Veja a seguir um exemplo do recurso personalizado com a injeção automática de variável de ambiente temporariamente desativada:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

Depois de excluir o recurso personalizado ou atualizá-lo para desativar a injeção automática de configuração, o GKE não instrumenta automaticamente novas cargas de trabalho que são segmentadas pelo recurso personalizado de instrumentação.

Para interromper a exportação de indicadores OTLP para o coletor gerenciado de uma carga de trabalho que foi instrumentada anteriormente pelo recurso personalizado, reinicie a carga de trabalho para que a alteração entre em vigor. Para isso, use o seguinte comando:

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

Substitua:

  • DEPLOYMENT_NAME: o nome da implantação.
  • NAMESPACE: o namespace.

Ver telemetria

Quando uma carga de trabalho configurada é executada no GKE em que o OpenTelemetry gerenciado para GKE está ativado, os sinais do OpenTelemetry são enviados ao Google Cloud Observability.

Para detalhes sobre como visualizar dados no Google Cloud Observability, consulte:

Gerar telemetria de amostra

Nesta seção, descrevemos como implantar um aplicativo de exemplo e apontar esse aplicativo para o endpoint OTLP do coletor do OpenTelemetry gerenciado. Em seguida, é possível visualizar a telemetria no Google Cloud.

O aplicativo de exemplo é um pequeno gerador que exporta traces, registros e métricas para o coletor do OpenTelemetry gerenciado no cluster. O aplicativo é codificado para usar o endpoint gRPC do coletor: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317

Se você já tiver um aplicativo instrumentado com um SDK do OpenTelemetry, será possível gerar telemetria do aplicativo apontando-o para o endpoint do coletor ou configurando a instrumentação automática para o aplicativo.

Para implantar o aplicativo de exemplo, faça o seguinte:

  1. Conecte-se ao cluster em que você ativou o OpenTelemetry gerenciado. Para fazer isso, consulte Definir um cluster padrão para comandos da kubectl.

  2. Execute este comando:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml

    Após alguns minutos, a telemetria gerada pelo aplicativo começa a fluir pelo coletor para o back-end do Google Cloud para cada indicador.

    1. Verifique se a telemetria foi ingerida visualizando registros, métricas e traces do aplicativo de demonstração no console do Google Cloud :

    2. Para visualizar métricas, faça o seguinte:

      1. No console do Google Cloud , acesse a página do Metrics Explorer:

        Acessar o Metrics Explorer

      2. Execute a seguinte consulta PromQL no Metrics Explorer:

        sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))

    3. Para ver os traces, faça o seguinte:

      1. No console do Google Cloud , acesse a página Análise de traces.

        Acessar o Explorador de traces

      2. Filtre os períodos de trace por nome de período igual a lets-go.

    4. Para ver os registros, faça o seguinte:

      1. No console do Google Cloud , acesse a página Análise de registros.

        Acessar a Análise de registros

      2. Execute a seguinte consulta:

        resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"

Desativar o OpenTelemetry gerenciado para GKE

É possível desativar o OpenTelemetry gerenciado para GKE no cluster. Quando você desativa o coletor, o coletor gerenciado do OpenTelemetry é removido do cluster, e nenhum dado de telemetria novo é coletado.

Para desativar o OpenTelemetry gerenciado para GKE, siga as etapas abaixo.

gcloud

Para desativar o OpenTelemetry gerenciado para GKE em um cluster, execute o seguinte comando gcloud:

  gcloud container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região ou zona.

Console

  1. No console, acesse a lista de clusters:

    Acessar os clusters do Kubernetes

  2. Selecione o cluster em que você quer desativar o OpenTelemetry gerenciado.

  3. Em Detalhes do cluster, ao lado de OpenTelemetry gerenciado, selecione o ícone de edição.

  4. Desmarque a caixa de seleção para desativar o recurso.

Terraform

Para desativar o OpenTelemetry gerenciado para GKE, atualize o bloco managed_opentelemetry_config no recurso google_container_cluster para definir o escopo como NONE.

  1. Atualize o arquivo de configuração do Terraform:

    resource "google_container_cluster" "default" {
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

  2. Aplique a configuração do Terraform:

    terraform apply

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • LOCATION: a região ou zona.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Quando você desativa o OpenTelemetry gerenciado para GKE, o CustomResourceDefinition de instrumentação e todos os recursos personalizados de instrumentação criados não são removidos do cluster.

Se você reativar o OpenTelemetry gerenciado, ele vai usar a configuração preservada nos recursos personalizados de instrumentação.

Se você tiver dados de telemetria que já foram coletados pelo OpenTelemetry gerenciado para GKE, desativar o coletor não vai afetar esses dados. Os dados atuais ainda são armazenados no Google Cloud Observability, e nenhum dado de telemetria novo é coletado.

Solução de problemas

Cargas de trabalho privilegiadas de parceiros do Autopilot

Se você tentar usar a configuração automática com uma carga de trabalho privilegiada de parceiro do Autopilot, talvez o pod da carga de trabalho seja rejeitado.

A injeção de configuração do OpenTelemetry não é compatível com cargas de trabalho privilegiadas de parceiros do GKE Autopilot. Segmentar essas cargas de trabalho usando um recurso personalizado de instrumentação para ativar a injeção variável de ambiente do OpenTelemetry pode fazer com que a carga de trabalho não corresponda à lista de permissões de carga de trabalho privilegiada do Autopilot, o que significa que o pod com injeção de configuração seria rejeitado pelo GKE Autopilot.

Os registros, as métricas ou os traces não estão visíveis no console do Google Cloud

Os dados podem não estar visíveis por vários motivos. Esses motivos incluem permissões ausentes para visualizar os dados ou configuração incorreta que impede a coleta de dados.

As etapas para resolver problemas comuns são as seguintes:

  • Verifique se todas as APIs necessárias estão ativadas no seu projeto.

  • Verifique se o recurso personalizado de instrumentação está configurado corretamente, com o namespace correspondente ao namespace em que a carga de trabalho está em execução e o seletor correspondente ao rótulo da carga de trabalho.

  • Inspecione o pod da carga de trabalho para ver se as variáveis de ambiente foram injetadas corretamente.

  • Verifique os registros de contêiner do coletor do OpenTelemetry para ver se há erros no coletor. Para isso, execute o seguinte comando:

    kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector

A desativação de um indicador de telemetria não está funcionando

Ao desativar um sinal de telemetria usando o recurso personalizado de instrumentação, aplique o recurso personalizado e reimplante as cargas de trabalho.

Ao aplicar o recurso personalizado, use a aplicação do lado do servidor no comando kubectl apply ao atualizar o recurso personalizado de instrumentação.

Para saber como desativar um indicador de telemetria, consulte Selecionar os tipos de indicador a serem coletados.

As variáveis injetadas do OpenTelemetry não estão visíveis na minha carga de trabalho

As variáveis são injetadas nos contêineres dos pods de carga de trabalho, não na carga de trabalho. Verifique os pods, não os objetos proprietários, como ReplicaSets ou implantações.

Por exemplo, para confirmar se as variáveis foram injetadas corretamente para a carga de trabalho de amostra no namespace padrão usado na seção anterior Gerar telemetria, faça o seguinte:

  1. Execute este comando:

    kubectl get pods -n default -l app=telemetrygen-app -o yaml

  2. Examine o spec.containers[*].env dos pods.

  3. Verifique se há um objeto de instrumentação no mesmo namespace e se ele está segmentando o pod e tem o recurso de injeção de configuração ativado. Para isso, execute o seguinte comando:

    kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml

As variáveis são injetadas nos contêineres somente quando os pods são criados, porque a API Kubernetes não permite modificar a maioria dos campos na especificação de um pod existente, como variáveis de ambiente. Para que a configuração entre em vigor em cargas de trabalho criadas antes do objeto de instrumentação, reinicie a carga de trabalho. Por exemplo, para uma implantação chamada telemetry-gen-app, execute o seguinte comando:

kubectl rollout restart deployment -n default telemetry-gen-app

Uma quantidade excessiva de dados de trace no Cloud Trace

Para reduzir a coleta de dados pelo Cloud Trace, configure um amostrador baseado em pai com uma proporção de ID de trace para amostrar apenas uma porcentagem dos traces.

Por exemplo, adicione o seguinte ao objeto Instrumentation:

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

O comportamento padrão do SDK do OpenTelemetry é o rastreamento "always_on", que equivale a uma proporção de 1.

As variáveis de ambiente não correspondem à configuração

Se você fez uma atualização no objeto de instrumentação, verifique se reiniciou os pods, conforme descrito na seção Modificar a configuração.

Se a configuração do pod estiver incorreta, verifique se ele é corretamente segmentado pelo objeto Instrumentation e se não há vários objetos Instrumentation segmentando o mesmo pod:

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

Um seletor vazio segmenta todos os pods no namespace.

Se várias instrumentações forem direcionadas ao mesmo pod quando ele for criado, a instrumentação atualizada mais recentemente vai entrar em vigor.

O comando kubectl logs não retorna saída.

Quando os registros são transmitidos diretamente de um aplicativo para um coletor do OpenTelemetry, eles ignoram o caminho de geração de registros padrão do ambiente de execução do contêiner. Esse é o cenário comum ao usar o OpenTelemetry para registros. Por padrão, o exportador envia os registros para o endpoint otlp, em vez de para os streams stdout e stderr.

Nesse caso, como os registros não são gravados nos streams stdout ou stderr para que o ambiente de execução do contêiner os capture, o comando kubectl logs não vai exibir nenhuma saída para esse aplicativo. Em vez disso, a saída de registro está disponível no Cloud Logging.

Se você quiser usar o SDK do OpenTelemetry e também enviar registros para o stream stdout, configure isso usando o exportador de registros. Para mais informações, consulte Exportador de registros: saída padrão.

A seguir