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.

Implantar o OpenTelemetry gerenciado para GKE

Autopilot Standard

Neste documento, explicamos como configurar o OpenTelemetry gerenciado para GKE e enviar traces, métricas e registros do OpenTelemetry Protocol (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.

É possível usar 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.
Exporte 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 desta oferta gerenciada.

Antes de começar

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

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

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

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
Criar um projeto: para criar um projeto, é necessário 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 Google Cloud que você está criando.
Selecione o projeto Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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

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

Ative as APIs GKE, Telemetria (OTLP), Cloud Logging, Cloud Monitoring e Cloud Trace:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

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

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
Criar um projeto: para criar um projeto, é necessário 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 Google Cloud que você está criando.
Selecione o projeto Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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

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

Ative as APIs GKE, Telemetria (OTLP), Cloud Logging, Cloud Monitoring e Cloud Trace:

Funções necessárias para ativar APIs

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

Requisitos

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

O cluster precisa ter a versão 1.34.1-gke.2178000 ou mais recente do GKE.
CLI gcloud ativada com a versão 551.0.0 ou mais recente.
Se você usa o Terraform para provisionar sua infraestrutura do GKE, use o provedor terraform-provider-google-beta na versão v7.17.0 ou mais recente.

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:

Administrador de cluster do Kubernetes Engine (roles/container.clusterAdmin)
Leitor do Monitoring (roles/monitoring.viewer)
Visualizador de registros (roles/logging.viewer)
Usuário do Cloud Trace (roles/cloudtrace.user)

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 saber detalhes sobre os custos relacionados ao uso do Managed OpenTelemetry para GKE.

Ativar o OpenTelemetry gerenciado para GKE em um cluster

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

Ative o OpenTelemetry gerenciado para GKE em um cluster.
Configure o aplicativo que você está monitorando para enviar indicadores 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 gerenciada do coletor do OpenTelemetry do GKE que é implantada no namespace gke-managed-otel. O endpoint HTTP do coletor gerenciado do OpenTelemetry no cluster para registros, métricas e rastreamentos é o seguinte: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.
Uma definição de recurso personalizado, instrumentations.telemetry.googleapis.com, que pode ser usada para configurar automaticamente suas 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 Managed OpenTelemetry para GKE em um novo cluster, siga estas etapas:

gcloud

Para um cluster do Autopilot, use o seguinte comando:

gcloud beta 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, que precisa ser 1.34.1-gke.2178000 ou posterior.

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

gcloud beta 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, que precisa ser 1.34.1-gke.2178000 ou posterior.

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 Salvar.
Para um cluster padrão, faça o seguinte:
1. No console do Google Cloud , acesse a página Criar um cluster do Kubernetes.
  Acessar "Criar um cluster do Kubernetes"
2. No painel de navegação, clique em Recursos.
3. Na seção Operações, selecione Ativar o OpenTelemetry gerenciado.
4. Clique em Salvar.

Terraform

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

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  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

Verifique se a versão do cluster é 1.34.1-gke.2178000 ou mais recente. Para detalhes sobre como fazer upgrade de um cluster atual, consulte Upgrades de cluster padrão e Upgrades de cluster do Autopilot.

Ative o OpenTelemetry gerenciado para GKE usando o seguinte comando:

gcloud beta 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

Verifique se a versão do cluster é 1.34.1-gke.2178000 ou mais recente. Para detalhes sobre como fazer upgrade de um cluster atual, consulte Upgrades de cluster padrão e Upgrades de cluster do Autopilot.
No console do Google Cloud , acesse a página "Clusters do Kubernetes":

Acessar os clusters do Kubernetes
Clique no nome do cluster.
Na lista Recursos, localize a opção OpenTelemetry gerenciado. Se ele estiver listado como desativado, clique em editar Editar e selecione Ativar o OpenTelemetry gerenciado.
Clique em Salvar alterações.

Terraform

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

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  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 gerenciado do OpenTelemetry

Os aplicativos precisam ser configurados para enviar indicadores ao endpoint do coletor gerenciado. Quando os aplicativos são configurados, o coletor gerenciado do OpenTelemetry recebe sinais 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 indicadores do OpenTelemetry, os aplicativos precisam estar instrumentados para gerar métricas do OpenTelemetry. Para detalhes, consulte cargas de trabalho compatíveis.

É possível configurar seu aplicativo manualmente para enviar indicadores ao endpoint do coletor gerenciado ou usar a configuração automática. Não recomendamos usar os dois métodos juntos para a mesma carga de trabalho, porque a configuração automática pode substituir as mudanças manuais. Essa combinação pode dificultar o rastreamento de mudanças na configuração.

As seções a seguir descrevem como configurar aplicativos para enviar indicadores 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 e 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 Instrumentation. 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.

Para configurar o recurso personalizado Instrumentation, faça o seguinte:
1. Salve o manifesto Instrumentation a seguir 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 instrumentação automática. Use default para segmentar o namespace padrão.
  - NAME: o nome do arquivo de manifesto. Neste exemplo, o nome é otlp-auto-config-namespace.yaml.
  - (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 rastreamento a serem coletados. Se não for especificado, o padrão será 1.0. Para mais detalhes, consulte Modificar a taxa de amostragem de rastreamento.
  - 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
```
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 elas são executadas.

Quando uma carga de trabalho configurada com essas variáveis de ambiente está em execução em um cluster em que o coletor gerenciado está 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 ver os indicadores, consulte Ver telemetria. Por exemplo, consulte Gerar telemetria de amostra.

Modifique a configuração

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

Modifique o arquivo de manifesto Instrumentation.
Aplique a configuração modificada.
Reimplante 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 Criar e implantar a configuração.

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

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

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

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

Modificar a taxa de amostragem de rastreamento

Uma carga de trabalho pode gerar uma grande quantidade de dados de rastreamento. Na sua 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 eles sejam úteis.

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

Confira a seguir um exemplo da configuração da taxa de amostragem de rastreamento. Neste exemplo, a proporção é 0,25.Portanto, os dados de rastreamento são coletados a uma taxa de 25%. Modifique esse número de proporção para mudar 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.

Confira 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, um máximo de 300.000 ms e um múltiplo de 5.000 ms. O valor é expresso em milissegundos.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Selecione os tipos de indicadores a serem coletados

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

Desative os tipos de indicadores usando as variáveis de ambiente no contêiner em que a carga de trabalho é executada. Para modificar variáveis de ambiente, edite o recurso personalizado Instrumentation e reimplante a carga de trabalho no contêiner.

O exemplo a seguir é um arquivo de manifesto Instrumentation configurado para a coleta apenas de dados de rastreamento. 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

É possível configurar o OpenTelemetry gerenciado para GKE para coletar dados de comandos e respostas multimodais.

Essa funcionalidade está disponível para agentes LangGraph ReAct 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 Managed OpenTelemetry para GKE, todo o conteúdo dos comandos e respostas do usuário final é coletado. Esses dados de solicitação e resposta são armazenados em um bucket do Cloud Storage. Para detalhes sobre como gerenciar o bucket de armazenamento, incluindo o controle de acesso ou a exclusão de dados, consulte a documentação do Cloud Storage.

Você pode 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 Managed OpenTelemetry para GKE e coletar dados de solicitações e respostas multimodais, faça o seguinte:

Configure seu projeto Google Cloud e o SDK que você está usando seguindo as instruções na seção Coletar comandos e respostas multimodais.
Crie ou identifique um bucket do Cloud Storage para usar na coleta de comandos e respostas multimodais. Para mais detalhes, consulte Criar um bucket.
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 seu aplicativo grave objetos no bucket do Cloud Storage. Esses 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.

Configure o campo promptsResponses.uploadBasePath no recurso personalizado Instrumentation. 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 Instrumentation é 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 você pode coletar e como analisar seus comandos e respostas multimodais, consulte Coletar e analisar 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 Instrumentation do cluster. Para fazer isso, use o seguinte comando:

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

Substitua:

INSTRUMENTATION_NAME: o nome do recurso personalizado Instrumentation.
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, mas preservar a configuração de instrumentação automática para uso futuro, defina autoInstrumentationConfig.configInjection.enabled como false e aplique o recurso personalizado atualizado.

Confira 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 ou atualizar o recurso personalizado 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 Instrumentation.

Para interromper a exportação de indicadores OTLP para o coletor gerenciado de uma carga de trabalho que foi instrumentada anteriormente pelo recurso personalizado, é necessário reiniciar a carga de trabalho para que a mudança 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 com o Managed OpenTelemetry para GKE ativado, os indicadores do OpenTelemetry são enviados ao Google Cloud Observability.

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

Gerar telemetria de amostra

Esta seção descreve a implantação de um aplicativo de exemplo e a indicação do aplicativo para o endpoint OTLP do coletor gerenciado do OpenTelemetry. Em seguida, veja a telemetria em Google Cloud.

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

Se você já tiver um aplicativo instrumentado com um SDK do OpenTelemetry, é possível gerar telemetria apontando o aplicativo 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:

Conecte-se ao cluster em que você ativou o OpenTelemetry gerenciado. Para fazer isso, consulte Definir um cluster padrão para comandos kubectl.
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 Google Cloud de cada indicador.
1. Verifique se a telemetria foi ingerida visualizando registros, métricas e rastreamentos do aplicativo de demonstração no console do Google Cloud :
2. Para visualizar métricas, faça o seguinte:
  1. No console Google Cloud , acesse a página do Metrics Explorer:
    
    Acessar o Metrics Explorer
  2. Execute a seguinte consulta em PromQL no Metrics Explorer:
```
sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))
```
3. Para ver os rastreamentos, faça o seguinte:
  1. No console Google Cloud , acesse a página Explorador de traces.
    
    Acessar o Explorador de traces
  2. Filtra períodos de trace pelo nome do 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 Managed OpenTelemetry Collector é removido do cluster, e nenhum novo dado de telemetria é coletado.

Para desativar o OpenTelemetry gerenciado para GKE, siga estas etapas.

gcloud

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

  gcloud beta 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

No console, acesse a lista de clusters:

Acessar os clusters do Kubernetes
Selecione o cluster em que você quer desativar o coletor gerenciado do OpenTelemetry.
Em Detalhes do cluster, ao lado de OpenTelemetry gerenciado, selecione o ícone de edição.
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.

Atualize o arquivo de configuração do Terraform:

resource "google_container_cluster" "default" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

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 Managed OpenTelemetry para GKE, a definição de recurso personalizado Instrumentation e os recursos personalizados Instrumentation não são removidos do cluster. Se você reativar o OpenTelemetry gerenciado, ele vai usar a configuração preservada nos recursos personalizados Instrumentation.

Se você tiver dados de telemetria que já foram coletados pelo Managed OpenTelemetry para GKE, desativar o coletor não vai afetar esses dados. Os dados atuais ainda são armazenados no Google Cloud Observability, e nenhum novo dado de telemetria é 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 um 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 Instrumentation para ativar a injeção de 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. Isso significa que o pod injetado com a configuração seria rejeitado pelo GKE Autopilot.

Registros, métricas ou rastreamentos 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.

Confira as etapas que você pode seguir para resolver problemas comuns:

Verifique se todas as APIs necessárias estão ativadas no seu projeto.
Verifique se o recurso personalizado Instrumentation está configurado corretamente, com o namespace correspondente ao namespace em que a carga de trabalho está sendo executada 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 conferir se há erros nele. 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 indicador de telemetria usando o recurso personalizado Instrumentation, aplique o recurso e reimplante as cargas de trabalho.

Ao aplicar o recurso personalizado, use Server-Side Apply no comando kubectl apply ao atualizar o recurso personalizado Instrumentation.

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

As variáveis injetadas pelo 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 Deployments.

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

Execute este comando:

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

Examine o spec.containers[*].env dos pods.
Verifique se há um objeto Instrumentation 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 do 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 da criação do objeto Instrumentation, 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 rastreamento no Cloud Trace

Para reduzir os dados coletados pelo Cloud Trace, configure um sampler baseado em parent com uma proporção de ID de rastreamento para amostrar apenas uma porcentagem dos seus rastreamentos.

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 é equivalente a uma proporção de 1.

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

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

Se você encontrar a configuração errada para seu pod, verifique se ele está sendo direcionado corretamente pelo objeto Instrumentation e se você não tem vários objetos Instrumentation direcionando 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 tem como destino todos os pods no namespace.

Se várias instrumentações segmentarem o mesmo pod quando ele for criado, a instrumentação atualizada por último 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 para o 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 dos streams stdout e stderr.

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

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

A seguir

Para detalhes sobre como o OpenTelemetry gerenciado para GKE funciona, consulte OpenTelemetry gerenciado para GKE.
Para uma alternativa autoimplantada ao OpenTelemetry gerenciado para GKE, consulte Coletor do OpenTelemetry criado pelo Google.

Implantar o OpenTelemetry gerenciado para GKE Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Requisitos

Funções exigidas

Custos

Ativar o OpenTelemetry gerenciado para GKE em um cluster

Ativar em um novo cluster

gcloud

Console

Terraform

Ativar em um cluster atual

gcloud

Console

Terraform

Configurar o aplicativo para usar o coletor gerenciado do OpenTelemetry

Configurar a configuração automática

Modifique a configuração

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

Modificar a taxa de amostragem de rastreamento

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

Selecione os tipos de indicadores a serem coletados

Coletar dados de comandos e respostas multimodais

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

Ver telemetria

Gerar telemetria de amostra

Desativar o OpenTelemetry gerenciado para GKE

gcloud

Console

Terraform

Solução de problemas

Cargas de trabalho privilegiadas de parceiros do Autopilot

Registros, métricas ou rastreamentos não estão visíveis no console do Google Cloud

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

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

Uma quantidade excessiva de dados de rastreamento no Cloud Trace

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

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

A seguir

Implantar o OpenTelemetry gerenciado para GKE

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