OpenTelemetry gerenciado para o GKE

Neste documento, descrevemos o OpenTelemetry gerenciado para o Google Kubernetes Engine (GKE), que permite enviar traces, métricas e registros do protocolo OpenTelemetry (OTLP) para o Google Cloud Observability de aplicativos em execução no GKE. O OpenTelemetry gerenciado oferece a única solução gerenciada pelo Google Cloud para coletar dados de trace no GKE.

Para usar o OpenTelemetry gerenciado para o Google Kubernetes Engine (GKE), os aplicativos precisam já estar instrumentados para gerar sinais usando o protocolo OpenTelemetry. Para mais detalhes, consulte Cargas de trabalho compatíveis.

O OpenTelemetry gerenciado para GKE tem dois componentes:

  • Coleta gerenciada: o coletor gerenciado fornece um endpoint do protocolo OpenTelemetry no cluster como destino para que as cargas de trabalho enviem traces, métricas e registros no formato OTLP, sem precisar gerenciar um coletor.

  • Configuração automática: um recurso personalizado chamado Instrumentation permite uma configuração automática para que as cargas de trabalho do GKE gerem e ingiram traces, métricas e registros correlacionados do OpenTelemetry. Essa abordagem é compatível com o Kit de Desenvolvimento de Agente (ADK) e com os dados de comandos multimodais e respostas.

    É possível usar o recurso personalizado de instrumentação para cargas de trabalho que usam o SDK do OpenTelemetry e são configuradas com variáveis de ambiente padrão do OpenTelemetry. Esse recurso personalizado de instrumentação, instrumentations.telemetry.googleapis.com, é diferente do recurso de instrumentação do operador do OpenTelemetry.

Para saber como usar o OpenTelemetry gerenciado para GKE, consulte Implantar o OpenTelemetry gerenciado para GKE.

O OpenTelemetry gerenciado para GKE permite coletar telemetria OTLP sem precisar gerenciar e operar um coletor do OpenTelemetry. A execução do seu próprio coletor pode gerar sobrecarga, incluindo autenticação, configuração, upgrades e monitoramento. No entanto, se você precisar de filtragem e controles no nível do coletor, use o coletor do OpenTelemetry criado pelo Google em vez desse serviço gerenciado.

O OpenTelemetry fornece APIs, bibliotecas e SDKs para gerar traces, métricas e registros distribuídos para monitoramento de aplicativos. Para mais informações sobre o OpenTelemetry, consulte a documentação sobre o OpenTelemetry e o protocolo OpenTelemetry (OTLP). Para mais detalhes sobre como gerar e coletar os dados comportamentais de execução do aplicativo, consulte Observabilidade para desenvolvedores de aplicativos.

Como funciona o OpenTelemetry gerenciado para GKE

O OpenTelemetry gerenciado para GKE tem dois componentes: coleta gerenciada e configuração automática.

Coleta gerenciada

A coleta gerenciada fornece um endpoint OTLP no cluster implantando um coletor OpenTelemetry gerenciado no cluster. Esse endpoint OTLP no cluster recebe traces, métricas e registros no formato OTLP. Para receber dados de uma carga de trabalho, ela precisa ser configurada para enviar dados ao coletor.

O endpoint para o qual a carga de trabalho envia dados depende do protocolo usado, da seguinte maneira:

  • O URL http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 do endpoint HTTP.
  • O URL http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317 para o endpoint gRPC.

A coleta gerenciada envia os dados coletados para o Google Cloud Observability. Os dados ficam disponíveis nos seguintes serviços:

O coletor gerenciado pode ser ativado para um cluster do GKE usando o console ou a CLI gcloud. Para instruções, consulte Ativar o OpenTelemetry gerenciado para GKE em um cluster.

Configuração automática

A configuração automática permite que o GKE configure as cargas de trabalho em execução no GKE para enviar sinais ao endpoint do coletor gerenciado.

Há diferentes métodos que podem ser usados para configurar uma carga de trabalho. A configuração automática usa variáveis de ambiente injetadas no contêiner da carga de trabalho para que ela envie sinais ao coletor gerenciado. Se você estiver configurando a carga de trabalho manualmente, use outros métodos. Para detalhes, consulte Configuração manual.

Ao usar a configuração automática, você define a configuração usando o recurso personalizado de instrumentação. Em seguida, o GKE injeta variáveis de ambiente, como o endpoint do exportador do OTLP, nos contêineres da carga de trabalho. Quando os contêineres da carga de trabalho têm essas variáveis de ambiente, os dados do OpenTelemetry são enviados ao coletor gerenciado à medida que a carga de trabalho é executada.

A configuração automática está disponível para cargas de trabalho que oferecem suporte nativo ao OpenTelemetry, o que significa que elas usam o SDK do OpenTelemetry e são configuradas usando variáveis de ambiente padrão do OpenTelemetry. Para mais detalhes, consulte Cargas de trabalho compatíveis.

Para instruções sobre como configurar seu aplicativo usando a configuração automática, consulte Configurar seu aplicativo para usar o coletor gerenciado do OpenTelemetry.

O recurso personalizado de instrumentação

Use o recurso personalizado de instrumentação para fazer o seguinte:

  • Especifique se as variáveis de ambiente serão injetadas nos contêineres dos pods selecionados ou de todos os pods em um namespace.
  • Controlar o tipo de dados coletados (registros, métricas e traces).
  • Controlar a frequência com que os dados de métricas são enviados ao coletor gerenciado.
  • Controlar a taxa de amostragem dos dados de trace.
  • Controlar o protocolo de transporte OTLP (HTTP ou gRPC) usado para exportar telemetria para o coletor gerenciado.

Para detalhes sobre como usar o recurso personalizado de instrumentação, consulte Modificar a configuração.

Injetar variáveis de ambiente automaticamente

Para injetar automaticamente variáveis de ambiente do OpenTelemetry nas cargas de trabalho do GKE, configure um objeto de instrumentação no cluster. Em seguida, quando você implanta o aplicativo no cluster com o objeto Instrumentation, as variáveis são injetadas pelo GKE.

O objeto de instrumentação precisa estar no cluster quando o aplicativo é implantado e os pods são criados. Se você implantou o aplicativo antes de criar o objeto de instrumentação, reinicie os pods do aplicativo para acionar a injeção automática das variáveis de ambiente.

Variáveis de ambiente

Quando uma carga de trabalho é implantada no namespace em que a configuração automática está ativada, o GKE injeta variáveis de ambiente nos contêineres das cargas de trabalho. Essas variáveis de ambiente são variáveis do OpenTelemetry da configuração do SDK do OpenTelemetry.

A lista a seguir contém todas as variáveis de ambiente que podem ser injetadas pelo OpenTelemetry gerenciado para GKE. As variáveis de ambiente específicas injetadas em um contêiner dependem da configuração no recurso personalizado de instrumentação.

As variáveis de ambiente que podem ser injetadas automaticamente em contêineres são as seguintes:

  • Endpoint e protocolo do exportador do OpenTelemetry.
    • OTEL_EXPORTER_OTLP_ENDPOINT: um URL de endpoint base para qualquer tipo de indicador. Dependendo do exportador configurado no recurso personalizado de instrumentação, o valor dessa variável de ambiente é o endpoint HTTP do coletor do OpenTelemetry gerenciado no cluster (http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318, padrão) ou o endpoint gRPC (http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317).
    • OTEL_EXPORTER_OTLP_PROTOCOL: especifica o protocolo de transporte OTLP usado pelo exportador do SDK. O valor dessa variável de ambiente é um dos seguintes, dependendo do protocolo de transporte OTLP que você usa:
      • grpc se você usar o protocolo de transporte otlp_grpc.
      • http/protobuf se você não especificar um protocolo de transporte ou se usar o protocolo de transporte otlp_http.
  • Configuração da proporção de amostragem de trace.
    • OTEL_TRACES_SAMPLER: define o amostrador usado para amostrar traces pelo SDK como um dos seguintes:
      • parentbased_traceidratio quando a amostragem de trace é configurada no recurso personalizado.
      • parentbased_always_on é o valor padrão dessa variável de ambiente. Ele será usado se essa variável de ambiente não estiver configurada ou for nula no recurso personalizado.
    • OTEL_TRACES_SAMPLER_ARG: especifica a proporção de amostragem de trace (entre 0,0 e 1,0). Se não estiver configurado no recurso personalizado, 1.0 será usado.
  • Intervalo de atraso entre o início de duas exportações de métricas consecutivas.
    • OTEL_METRIC_EXPORT_INTERVAL: o intervalo de tempo (em milissegundos) entre o início de duas tentativas de exportação (mín.: 5.000, máx.: 300.000, padrão: 30.000).
  • Desativação da exportação de telemetria do OTLP por tipo de indicador. Os exportadores de indicadores são desativados quando tracer_provider, meter_provider ou logger_provider são definidos como null no recurso personalizado de instrumentação.
    • OTEL_TRACES_EXPORTER: desativa a exportação de traces quando definido como none. Valor padrão: otlp.
    • OTEL_METRICS_EXPORTER: desativa a exportação de métricas quando definido como none. Valor padrão: otlp.
    • OTEL_LOGS_EXPORTER: desativa a exportação de registros quando definido como none. Valor padrão: otlp.
  • Identificação de pods hostNetwork para associar os metadados pelo processador de atributos do Kubernetes do coletor do OpenTelemetry.
    • K8S_POD_UID: o UID do pod de um pod hostNetwork para preencher a configuração k8s.pod.uid na variável de ambiente OTEL_RESOURCE_ATTRIBUTES.
    • OTEL_RESOURCE_ATTRIBUTES: o valor inclui k8s.pod.uid=$(K8S_POD_UID) para permitir que o processador de atributos do Kubernetes associe metadados, como k8s.namespace.name, k8s.deployment.name e k8s.node.name, a pods hostNetwork. A associação de metadados e pods hostNetwork permite adicionar os metadados extraídos a períodos, métricas e registros como atributos de recurso.
  • Comandos e respostas.
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl': instrui o OpenTelemetry a formatar objetos do Cloud Storage como linhas JSON. Essa variável de ambiente tem um valor fixo: jsonl.
    • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload': instrui o OpenTelemetry a fazer upload de dados de comandos e respostas em vez de incorporar esse conteúdo em períodos de trace. As referências aos objetos enviados são incluídas em uma entrada de registro. Essa variável de ambiente tem um valor fixo: upload.
    • OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental': instrua o OpenTelemetry a usar as convenções semânticas mais recentes para IA generativa. Essa variável de ambiente tem um valor fixo: gen_ai_latest_experimental.
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH: especifique o caminho para objetos. Por exemplo, gs://STORAGE_BUCKET_NAME/PATH

Configuração manual

Há diferentes métodos que podem ser usados para configurar uma carga de trabalho para enviar sinais ao endpoint do coletor gerenciado. Se você estiver configurando manualmente sua carga de trabalho, poderá adicionar e modificar manualmente as variáveis de ambiente ou usar outro método, como flags de linha de comando.

Não recomendamos usar a configuração manual e a automática juntas para a mesma carga de trabalho, porque a configuração automática pode substituir as alterações manuais. Essa combinação pode dificultar o rastreamento de mudanças na configuração.

Para detalhes sobre a configuração automática, consulte Configuração automática.

Cargas de trabalho compatíveis

As cargas de trabalho compatíveis são aquelas que usam o OpenTelemetry para coletar dados sobre o comportamento de execução do aplicativo. As cargas de trabalho oferecem suporte nativo ao OpenTelemetry se usarem o SDK do OpenTelemetry e forem configuradas usando variáveis de ambiente padrão do OpenTelemetry. Por exemplo, o Kit de Desenvolvimento de Agente (ADK) oferece suporte nativo ao OpenTelemetry.

Para mais detalhes sobre como os dados de comportamento do ambiente de execução do aplicativo são gerados e coletados, consulte Observabilidade para desenvolvedores de aplicativos.

Se uma carga de trabalho for compatível com alguns tipos de dados OTLP, mas não com outros, o OpenTelemetry gerenciado para GKE vai coletar os dados OTLP. Por exemplo, se uma carga de trabalho usar o SDK do OpenTelemetry para implementar traces, mas não o usar para registros ou métricas, os dados de registros e métricas não serão coletados pelo OpenTelemetry gerenciado para GKE. Para saber como controlar o tipo de dados a serem coletados, consulte Selecionar os tipos de indicadores a serem coletados.

A injeção de configuração do OpenTelemetry não é compatível com cargas de trabalho privilegiadas de parceiros do Autopilot do GKE.

Faturamento

Quando você envia dados de telemetria para o Google Cloud, a cobrança é feita por volume de ingestão. As métricas são faturadas usando os preços do Google Cloud Managed Service para Prometheus, os registros são faturados usando os preços do Cloud Logging e os traces são faturados usando os preços do Cloud Trace.

Para informações sobre os custos associados à ingestão de traces, registros e métricas do Google Cloud Managed Service para Prometheus, consulte Preços do Google Cloud Observability.

Cotas

Quando você usa o OpenTelemetry gerenciado para GKE, as cotas dos serviços do Google Cloud Observability se aplicam. Se quiser saber mais, consulte estas referências:

A seguir