Neste documento, descrevemos como modificar um app Java para coletar dados de rastreamento e métrica usando o framework de código aberto OpenTelemetry, e como gravar registros JSON estruturados para saída padrão. Este documento também fornece informações sobre um app de exemplo Spring Boot Java que pode ser instalado e executado. O app está configurado para gerar métricas, traces e registros. As etapas são as mesmas, esteja você usando ou não o Spring Boot Framework.
Sobre a instrumentação manual e automática
A instrumentação descrita neste documento depende da instrumentação automática do OpenTelemetry para enviar telemetria ao seu projeto do Google Cloud. Para Java, a instrumentação automática se refere à prática de injetar dinamicamente bytecode em bibliotecas e frameworks para capturar telemetria. A instrumentação automática pode coletar telemetria para itens como chamadas HTTP de entrada e saída. Para saber mais, consulte Instrumentação automática para Java.
O OpenTelemetry também oferece uma API para adicionar instrumentação personalizada ao seu próprio código. O OpenTelemetry se refere a isso como instrumentação manual. Este documento não descreve a instrumentação manual. Para exemplos e informações sobre esse tópico, consulte Instrumentação manual.
Antes de começar
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Instrumentar o app para coletar traces, métricas e registros
Para instrumentar o app para coletar dados de rastreamento e métrica e gravar um JSON estruturado para saída padrão, siga as etapas a seguir, conforme descrito nas próximas seções deste documento:
- Configurar o app para usar o agente Java do OpenTelemetry
- Configurar o OpenTelemetry
- Configurar a geração de registros estruturados
- Gravar registros estruturados
Configurar o app para usar o agente Java do OpenTelemetry
Para configurar o app para gravar registros estruturados e coletar métricas e rastrear dados usando o OpenTelemetry, atualize a invocação do app para usar o Agente Java do OpenTelemetry. Esse método de instrumentação do app é conhecido como instrumentação automática, porque não requer modificação do código do app.
O exemplo de código a seguir ilustra um Dockerfile que faz o download do
arquivo JAR do agente Java do OpenTelemetry e atualiza a invocação da linha de comando para transmitir a
sinalização -javaagent
.
Para ver o exemplo completo, clique em more_vert Mais e selecione Ver no GitHub.
Como alternativa, também é possível definir a sinalização -javaagent
na variável de ambiente JAVA_TOOL_OPTIONS
:
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
Configurar o OpenTelemetry
A configuração padrão do agente Java do OpenTelemetry exporta traces e métricas usando o protocolo OTLP. Ela também configura o OpenTelemetry para usar o formato Contexto de Rastreamento do W3C para propagar o contexto do trace. Essa configuração garante que os períodos tenham o relacionamento pai-filho correto em um trace.
Para mais informações e opções de configuração, consulte Instrumentação automática em Java do OpenTelemetry.
Configurar a geração de registros estruturados
Para incluir as informações de trace como parte dos registros formatados em JSON gravados na saída padrão, configure seu app para gerar registros estruturados no formato JSON. Recomendamos usar o Log4j2 como implementação da geração de registros.
O exemplo de código a seguir ilustra um arquivo log4j2.xml
configurado para gerar registros estruturados JSON usando o Layout do modelo JSON:
A configuração anterior extrai informações sobre o período ativo do Contexto de diagnóstico mapeado do SLF4J e adiciona essas informações como atributos ao registro. Esses atributos podem ser usados para correlacionar um registro com um trace:
logging.googleapis.com/trace
: nome do recurso do trace associado à entrada de registro.logging.googleapis.com/spanId
: o ID do período com o trace associado à entrada de registro.logging.googleapis.com/trace_sampled
: o valor desse campo precisa sertrue
oufalse
.
Para mais informações sobre esses campos, consulte a estrutura
LogEntry
.
Gravar registros estruturados
Para gravar registros estruturados que se vinculam a um trace, use a API de geração de registros
SLF4J. Por exemplo, a instrução a seguir mostra como chamar o método
Logger.info()
:
logger.info("handle /multi request with subRequests={}", subRequests);
O agente Java do OpenTelemetry preenche automaticamente o Contexto de diagnóstico mapeado do SLF4J com o contexto de período do período ativo atual no OpenTelemetry Context. O Contexto de diagnóstico mapeado é incluído nos registros JSON, conforme descrito em Configurar geração de registros estruturados.
Executar um app de exemplo configurado para coletar telemetria
O aplicativo de exemplo usa formatos neutros em relação a fornecedores, incluindo registros JSON e
métricas e traces do OTLP, além do Framework do Spring Boot. Para rotear
a telemetria para o Google Cloud, este exemplo usa o Collector
do OpenTelemetry
configurado com os exportadores do Google. O app tem dois endpoints:
O endpoint
/multi
é processado pela funçãohandleMulti
. O gerador de carga no app emite solicitações para o endpoint/multi
. Quando esse endpoint recebe uma solicitação, ele envia de três a sete solicitações para o endpoint/single
no servidor local.O endpoint
/single
é processado pela funçãohandleSingle
. Quando esse endpoint recebe uma solicitação, ele fica suspenso por um pequeno atraso e depois responde com uma string.
Fazer o download e implantar o app
Para executar a amostra:
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Clone o repositório:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java
Acesse o diretório da amostra:
cd opentelemetry-operations-java/examples/instrumentation-quickstart
Crie e execute a amostra:
docker compose up --abort-on-container-exit
Se você não estiver usando o Cloud Shell, execute o aplicativo com a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
apontando para um arquivo de credenciais. O Application Default Credentials fornece um arquivo de credenciais em$HOME/.config/gcloud/application_default_credentials.json
.# Set environment variables export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" export USERID="$(id -u)" # Run docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
Ver suas métricas
A instrumentação do OpenTelemetry no app de amostra gera métricas do Prometheus, que podem ser visualizadas usando o Metrics Explorer:
Prometheus/http_server_duration_milliseconds/histogram
registra a duração das solicitações do servidor e armazena os resultados em um histograma.Prometheus/http_client_duration_milliseconds/histogram
registra a duração das solicitações do cliente e armazena os resultados em um histograma.
-
No Console do Google Cloud, acesse a página do leaderboard Metrics Explorer:
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoramento.
- No elemento Metric, expanda o menu Selecionar uma métrica,
digite
http_server
na barra de filtro e use os submenus para selecionar um tipo de recurso e métrica específicos:- No menu Active resources, selecione Prometheus Target.
- No menu Categorias de métrica ativas, selecione Instância.
- No menu Métricas ativas, selecione uma métrica de faturamento†.
- Clique em Aplicar.
- Configure a visualização dos dados.
Quando as medições de uma métrica são cumulativas, o Metrics Explorer normaliza automaticamente os dados medidos pelo período de alinhamento, o que resulta na exibição de uma taxa no gráfico. Para mais informações, consulte Tipos, tipos e conversões.
Quando valores inteiros ou duplos são medidos, como acontece com as duas métricas
counter
, o Metrics Explorer soma automaticamente todas as séries temporais. Para visualizar os dados das rotas HTTP/multi
e/single
, defina o primeiro menu da entrada Agregação como Nenhum.Para mais informações sobre como configurar um gráfico, consulte Selecionar métricas ao usar o Metrics Explorer.
Visualizar os rastros
Para visualizar os dados de trace, faça o seguinte:
-
No console do Google Cloud, acesse a página Explorador de traces:
Acessar o Explorador de traces
Também é possível encontrar essa página usando a barra de pesquisa.
- No gráfico de dispersão, selecione um rastro com o URI de
/multi
. No diagrama de Gantt no painel Detalhes do trace, selecione o período rotulado como
/multi
.Um painel é aberto com informações sobre a solicitação HTTP. Esses detalhes incluem o método, o código de status, o número de bytes e o user agent do autor da chamada.
Para visualizar os registros associados a esse trace, selecione a guia Registros e eventos.
A guia mostra registros individuais. Para exibir os detalhes da entrada de registro, expanda a entrada de registro. Também é possível clicar em Ver registros e ver o registro usando a Análise de registros.
Para mais informações sobre como usar o explorador do Cloud Trace, consulte Encontrar e explorar traces.
Acessar os registros
Na Análise de registros, é possível inspecionar os registros e visualizar os traces associados, quando eles existirem.
-
No console do Google Cloud, acesse a página do Análise de registros.
Acessar a Análise de registros
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
Localize um registro com a descrição de
handle /multi request
.Para ver os detalhes do registro, expanda a entrada.
Clique em Traces em uma entrada de registro com a mensagem "handle /multi request" e selecione View trace details.
O painel Detalhes do trace é aberto e mostra o trace selecionado.
Para mais informações sobre como usar a Análise de registros, consulte Ver registros usando a Análise de registros.
A seguir
- OpenTelemetry
- Visão geral do OTLP
- Geração de registros estruturados
- Solução de problemas do Managed Service para Prometheus
- Resolver problemas do Cloud Trace