Ativar indicadores de telemetria nas bibliotecas de cliente do Cloud para Java

Google Cloud oferece monitoramento, geração de registros e diagnósticos avançados para aplicativos Java.

As bibliotecas de cliente Java são instrumentadas para emitir dados de rastreamento, métricas e registros. A instrumentação é opcional. Você precisa ativá-la explicitamente. Este documento descreve os indicadores disponíveis e como ativá-los.

Indicadores disponíveis

Os indicadores de ouro incluem os seguintes dados de telemetria, seguindo as Convenções semânticas do OpenTelemetry:

• Traces:traces HTTP/gRPC de baixo nível que representam as solicitações de rede feitas pelas bibliotecas de cliente.
• Métricas:métricas de solicitação do cliente, rastreamento de latência e taxas de solicitação. A métrica principal é gcp.client.request.duration.
• Registros:registros de erros acionáveis no nível DEBUG, fornecendo detalhes sobre solicitações com falha na camada de transporte, mesmo que sejam repetidas com êxito.

Os indicadores incluem atributos padrão do OpenTelemetry (por exemplo, http.response.status_code e rpc.system.name) e atributos personalizados específicos do Google Cloud, que podem incluir estes e atributos semelhantes:

• gcp.client.service: o nome do serviço (por exemplo, pubsub ou storage).
• gcp.client.repo: o repositório da biblioteca de cliente (por exemplo, googleapis/google-cloud-java).
• gcp.client.version: a versão da biblioteca de cliente.
• gcp.client.artifact: o caminho específico do módulo (por exemplo, com.google.cloud:google-cloud-secretmanager).
• gcp.resource.destination.id: o ID do recurso em que a ação está sendo realizada.
• gcp.errors.domain: o domínio de erro para registros de erros acionáveis.
• gcp.errors.metadata.<key>: chaves de metadados de erro adicionais para solicitações com falha (simplificadas).

Para uma lista completa de atributos padrão, consulte as convenções semânticas HTTP e gRPC do OpenTelemetry.

Como ativar a telemetria

Para proteger dados sensíveis, os indicadores de telemetria são desativados por padrão. É preciso ativar explicitamente essa opção.

Rastros, registros ou métricas podem conter dados sensíveis, como nomes de recursos, URLs completos e mensagens de erro.

Antes de configurar assinantes ou exportadores para rastreamentos, registros ou métricas, revise o conteúdo dos intervalos e consulte a documentação do OpenTelemetry para configurar filtros e formatadores e evitar o vazamento de informações sensíveis, dependendo do caso de uso pretendido.

Rastreamento e métricas

Nas bibliotecas de cliente Java geradas, é necessário ativar o rastreamento e as métricas de maneira programática fornecendo a fábrica de rastreadores adequada às configurações do cliente durante a inicialização:

• Rastreamento:configure o cliente com um OpenTelemetryTracingFactory.
• Métricas:configure o cliente com um OpenTelemetryMetricsFactory.
• Ambos:se você quiser ativar o rastreamento e as métricas, configure o cliente com um CompositeTracerFactory que encapsula as duas fábricas.

Para o SDK do BigQuery para Java, ative o rastreamento definindo BigQueryOptions.newBuilder().setEnableOpenTelemetryTracing(true) e fornecendo o rastreador do OpenTelemetry.

Logging

Os registros de erros acionáveis são integrados diretamente à estrutura principal do ApiTracer. Para ativar os registros de erros acionáveis globalmente nas bibliotecas de cliente do Google Cloud, use a seguinte variável de ambiente:

export GOOGLE_SDK_JAVA_LOGGING=true

Propagação do contexto de trace

A propagação do contexto de rastreamento nas bibliotecas de cliente Java exige que o rastreamento seja ativado explicitamente.

Quando a geração de trace está ativada (por exemplo, ao configurar um OpenTelemetryTracingFactory) e seu aplicativo tem um período ativo do OpenTelemetry no contexto atual quando um método de biblioteca de cliente é chamado, a biblioteca o usa para fornecer um contexto de rastreamento para as solicitações de saída. Isso garante que os rastreamentos no nível do aplicativo possam ser correlacionados com os registros e comportamentos do serviço de back-end.

Exportar telemetria

Depois que a telemetria é ativada nas bibliotecas de cliente, o aplicativo precisa ser configurado para coletar e exportar esses dados para o back-end de observabilidade.

Rastreamento e métricas

Para exportar os traces e as métricas gerados pelas bibliotecas de cliente Java, inicialize o SDK do OpenTelemetry com o exportador de sua preferência (por exemplo, OTLP) e configure o propagador global de mapa de texto no seu aplicativo.

Para mais detalhes sobre como coletar e exportar dados do OpenTelemetry para o Cloud Monitoring ou o Cloud Trace, consulte Escolher uma abordagem de instrumentação.

Logging

As bibliotecas de cliente Java usam frameworks de geração de registros padrão, como SLF4J e java.util.logging. Quando GOOGLE_SDK_JAVA_LOGGING=true está definido, os registros de erros acionáveis são emitidos no nível DEBUG.

Para encaminhar esses registros estruturados ao Cloud Logging, configure sua estrutura de geração de registros (por exemplo, Logback) para gravar JSON na saída padrão (stdout). Se você estiver implantando em um ambiente como o Google Kubernetes Engine ou o Cloud Run, os agentes integrados vão extrair esses registros automaticamente.

Para instruções detalhadas sobre como configurar o Logback ou o java.util.logging para gerar JSON compatível com o Cloud Logging, incluindo a correlação de rastreamentos, consulte Configurar a geração de registros estruturados para Java.