OpenTelemetry gerenciado para o GKE

Este documento descreve 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 do Google Cloud para coletar dados de rastreamento no GKE.

Para usar o OpenTelemetry gerenciado para o Google Kubernetes Engine (GKE), os aplicativos precisam já estar instrumentados para gerar indicadores 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 um destino para cargas de trabalho enviarem 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 oferece suporte ao Kit de Desenvolvimento de Agente (ADK) e a dados de comandos e respostas multimodais.

    É possível usar o recurso personalizado Instrumentation 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 Instrumentation, instrumentations.telemetry.googleapis.com, é diferente do recurso Instrumentation para o operador do OpenTelemetry.

Para conferir as etapas de uso do 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 controles e filtragem 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 OpenTelemetry e o protocolo OpenTelemetry (OTLP). Para mais detalhes sobre como gerar e coletar dados de comportamento de execução do aplicativo, consulte Instrumentação e observabilidade.

Como o OpenTelemetry gerenciado para GKE funciona

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 do 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 do coletor gerenciado é: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

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 cargas de trabalho em execução no GKE para enviar indicadores 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 indicadores ao coletor gerenciado. Se você estiver configurando a carga de trabalho manualmente, poderá usar outros métodos. Para mais detalhes, consulte Configuração manual.

Ao usar a configuração automática, você define a configuração usando o recurso personalizado Instrumentation. Em seguida, o GKE injeta variáveis de ambiente, como o endpoint do exportador 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 o aplicativo usando a configuração automática, consulte Configurar o aplicativo para usar o coletor do OpenTelemetry gerenciado.

O recurso personalizado Instrumentation

Use o recurso personalizado Instrumentation para fazer o seguinte:

  • Especificar 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 rastreamento.

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

Injetar variáveis de ambiente automaticamente

Para injetar variáveis de ambiente do OpenTelemetry nas cargas de trabalho do GKE automaticamente, é necessário configurar um objeto Instrumentation no cluster. Em seguida, ao implantar o aplicativo no cluster com o objeto Instrumentation, as variáveis serão injetadas pelo GKE.

O objeto Instrumentation precisa estar no cluster quando o aplicativo é implantado e os pods são criados. Se você implantou o aplicativo antes de criar o objeto Instrumentation, será necessário reiniciar 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 Instrumentation.

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

  • Endpoint do exportador do OpenTelemetry.
    • OTEL_EXPORTER_OTLP_ENDPOINT: um URL de endpoint base para qualquer tipo de indicador. Esse endpoint sempre aponta para o endpoint HTTP do coletor do OpenTelemetry gerenciado no cluster para registros, métricas e traces. O endpoint é: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.
  • Configuração da proporção de amostragem de rastreamento.
    • OTEL_TRACES_SAMPLER: define o sampler usado para amostrar traces pelo SDK como um dos seguintes:
      • parentbased_traceidratio quando a amostragem de rastreamento é configurada no recurso personalizado.
      • parentbased_always_on é o valor padrão dessa variável de ambiente. Ele é 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 rastreamento (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ínimo: 5.000, máximo: 300.000, padrão: 30.000).
  • Desativação da exportação de telemetria 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 arquivo Instrumentation.
    • 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 por 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 recursos.
  • Comandos e respostas.
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl': instrui a 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 rastreamento. 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': instrui 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: especifica o caminho dos 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 indicadores ao endpoint do coletor gerenciado. Se você estiver configurando a carga de trabalho manualmente, poderá adicionar e modificar variáveis de ambiente manualmente ou usar outro método, como flags de linha de comando.

Não recomendamos usar a configuração manual e a configuração automática juntas 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 das mudanças na configuração.

Para mais 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 de execução do aplicativo são gerados e coletados, consulte Instrumentação e observabilidade.

Se uma carga de trabalho oferece suporte a alguns tipos de dados OTLP e não a outros, o OpenTelemetry gerenciado para GKE coleta os dados OTLP. Por exemplo, se uma carga de trabalho usa o SDK do OpenTelemetry para implementar traces, mas não o usa para registros ou métricas, os dados de registros e métricas não são coletados pelo OpenTelemetry gerenciado para GKE. Para mais detalhes sobre 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

Ao enviar dados de telemetria para Google Cloud, você é cobrado pelo volume de ingestão. As métricas são cobradas usando os preços do Google Cloud Managed Service para Prometheus, os registros são cobrados usando os preços do Cloud Logging e os traces são cobrados 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

Ao usar o OpenTelemetry gerenciado para GKE, as cotas dos serviços do Google Cloud Observability são aplicadas. Se quiser saber mais, consulte estas referências:

A seguir