Managed Service for OpenTelemetry:Relatar dados de aplicação Java com o agente SkyWalking

Pré-requisitos

• Acesse a página de download do SkyWalking e baixe o SkyWalking 6.X.X ou uma versão posterior (recomenda-se a versão estável mais recente). Coloque a pasta agent extraída em um diretório acessível ao processo Java.

• Todos os plugins estão armazenados no diretório /plugins. Para ativar um novo plugin, adicione-o a este diretório antes da inicialização. Para desativar um plugin, remova-o deste diretório. Por padrão, os arquivos de log são gravados no diretório /logs.

Contexto

O SkyWalking é uma ferramenta popular de Monitoramento de Desempenho de Aplicações (APM), projetada para aplicações construídas sobre arquiteturas de microsserviços, Cloud Native e conteinerizadas (docker, Kubernetes e Mesos). Em sua essência, o SkyWalking é um sistema de rastreamento distribuído.

Para usar o SkyWalking para relatar dados da sua aplicação Java ao console do Managed Service for OpenTelemetry, é necessário primeiro instrumentar a aplicação. O SkyWalking suporta tanto a instrumentação automática para frameworks como Dubbo, gRPC, JDBC, OkHttp, Spring, Tomcat, Struts e Jedis, quanto a instrumentação manual com OpenTracing. Este tópico descreve o método de instrumentação automática.

Demonstração

Repositório de código: SkyWalking Demo

Instrumentar uma aplicação Java com o SkyWalking

1. Baixe o SkyWalking Java Agent.

2. Configure as informações de conexão e do service no arquivo de configuração do SkyWalking Java Agent.

   collector.backend_service=<endpoint> // Replace with the endpoint obtained from the prerequisites.
   agent.authentication=<token> // Replace with the authentication token obtained from the prerequisites.
   agent.service_name=<service-name> // Replace with your actual service name.

3. Especifique o caminho para o agente SkyWalking com base no ambiente de execução da sua aplicação.

   Nota

   Nos exemplos a seguir, substitua <skywalking-agent-path> pelo caminho absoluto para skywalking-agent.jar na pasta do agente.

   Linux Tomcat 7 / Tomcat 8

   Adicione o seguinte à primeira linha de tomcat/bin/catalina.sh:

   CATALINA_OPTS="$CATALINA_OPTS -javaagent:<skywalking-agent-path>"; export CATALINA_OPTS

   Windows Tomcat 7 / Tomcat 8

   Adicione o seguinte à primeira linha de tomcat/bin/catalina.bat:

   set "CATALINA_OPTS=-javaagent:<skywalking-agent-path>"

   JAR or Spring Boot

   Adicione o parâmetro -javaagent ao comando de inicialização da sua aplicação.

   Importante

   O parâmetro -javaagent deve aparecer antes do parâmetro -jar.

   java -javaagent:<skywalking-agent-path> -jar yourApp.jar

   Jetty

   Adicione as seguintes linhas ao arquivo de configuração {JETTY_HOME}/start.ini:

   --exec
   -javaagent:<skywalking-agent-path>

4. Reinicie sua aplicação.

Atributos configuráveis do agente Java

O agente Java do SkyWalking suporta uma ampla variedade de atributos configuráveis pelo usuário. Para obter uma lista completa de atributos, consulte o arquivo config/agent.config na demonstração de exemplo.

Principais atributos

Os atributos a seguir são baseados no apache-skywalking-java-agent-8.16.0.

Métodos de configuração

Propriedades do sistema

Use o prefixo -Dskywalking. seguido pelo nome do atributo do arquivo agent.config. Por exemplo:

# Configure agent.service_name using a system property
java -javaagent:/path/to/skywalking-agent.jar -Dskywalking.agent.service_name=<your_service_name> -jar your-project.jar

Opções do agente

Anexe atributos ao caminho do agente nos argumentos da JVM.

# Syntax
-javaagent:/path/to/skywalking-agent.jar=[key1]=[value1],[key2]=[value2]
# Example
java -javaagent:/path/to/skywalking-agent.jar=agent.service_name=<your-service-name>,agent.authentication=<your-token> -jar your-project.jar

Variáveis de ambiente

O agente SkyWalking lê variáveis de ambiente automaticamente. É possível encontrar a variável de ambiente correspondente para cada atributo no arquivo config/agent.config. Por exemplo, a variável de ambiente para agent.service_name é SW_AGENT_NAME.

agent.service_name=${SW_AGENT_NAME:default_name}
# Set the environment variable
export SW_AGENT_NAME=<your_service_name>

Precedência

As configurações são aplicadas com a seguinte precedência, da mais alta para a mais baixa: opções do agente, propriedades do sistema, variáveis de ambiente e arquivo de configuração.

Plugins do agente Java

O agente Java do SkyWalking suporta uma variedade de middlewares, frameworks e bibliotecas. Todos os plugins suportados estão disponíveis na pasta /plugins da aplicação de demonstração.

Ativar plugins

Todos os plugins na pasta /plugins estão ativos. Para desativar um plugin, remova seu arquivo JAR da pasta /plugins.

Plugins oficialmente suportados

Todos os plugins oficialmente suportados estão localizados na pasta /plugins.

Plugins opcionais

Os plugins opcionais residem na pasta optional-plugins do pacote do agente ou em um repositório de terceiros. Para ativar um plugin opcional, mova seu arquivo JAR para a pasta /plugins.

optional-plugins/
  apm-customize-enhance-plugin-8.16.0.jar
  apm-ehcache-2.x-plugin-8.16.0.jar
  apm-fastjson-1.x-plugin-8.16.0.jar
  apm-gson-2.x-plugin-8.16.0.jar
  apm-guava-cache-plugin-8.16.0.jar
  apm-jackson-2.x-plugin-8.16.0.jar
  apm-kotlin-coroutine-plugin-8.16.0.jar
  apm-mybatis-3.x-plugin-8.16.0.jar
  apm-quartz-scheduler-2.x-plugin-8.16.0.jar
  apm-resttemplate-6.x-plugin-8.16.0.jar
  apm-sentinel-1.x-plugin-8.16.0.jar
  apm-shenyu-2.4.x-plugin-8.16.0.jar
  apm-spring-annotation-plugin-8.16.0.jar
  apm-spring-cloud-gateway-2.0.x-plugin-8.16.0.jar
  apm-spring-cloud-gateway-2.1.x-plugin-8.16.0.jar
  apm-spring-cloud-gateway-3.x-plugin-8.16.0.jar
  apm-spring-tx-plugin-8.16.0.jar
  apm-spring-webflux-5.x-plugin-8.16.0.jar
  apm-springmvc-annotation-6.x-plugin-8.16.0.jar
  apm-trace-ignore-plugin-8.16.0.jar
  apm-zookeeper-3.4.x-plugin-8.16.0.jar
  trace-sampler-cpu-policy-plugin-8.16.0.jar

Plugins de bootstrap

Devido a possíveis riscos de estabilidade, todos os plugins de bootstrap são opcionais. Eles estão localizados na pasta bootstrap-plugins. Para ativar um plugin de bootstrap, mova seu arquivo JAR para a pasta /plugins.

bootstrap-plugins/
  apm-jdk-forkjoinpool-plugin-8.16.0.jar
  apm-jdk-http-plugin-8.16.0.jar
  apm-jdk-threading-plugin-8.16.0.jar
  apm-jdk-threadpool-plugin-8.16.0.jar

Plugins suportados

Alguns plugins estão disponíveis apenas em um repositório de terceiros devido a possíveis impactos no desempenho ou limitações de uso. Para mais informações, consulte o repositório SkyAPM Java Plugin Extension.

Desenvolvimento de plugins

Para desenvolver um plugin personalizado do agente Java SkyWalking, consulte a documentação oficial.

O Managed Service for OpenTelemetry suporta o relato de traces. Consulte a documentação oficial para obter detalhes sobre o desenvolvimento de um plugin de trace personalizado.

Perguntas frequentes

P: Por que minha aplicação não aparece depois que o Agente SkyWalking se conecta ao servidor?

DEBUG 2020-03-09 17:18:16:356 SkywalkingAgent-5-ServiceAndEndpointRegisterClient-0 ServiceAndEndpointRegisterClient : ServiceAndEndpointRegisterClient running, status:CONNECTED.
DEBUG 2020-03-09 17:18:19:357 SkywalkingAgent-5-ServiceAndEndpointRegisterClient-0 ServiceAndEndpointRegisterClient : ServiceAndEndpointRegisterClient running, status:CONNECTED.
DEBUG 2020-03-09 17:18:21:301 DataCarrier.DEFAULT.Consumer.0.Thread TraceSegmentServiceClient : 1 trace segments have been sent to collector.
DEBUG 2020-03-09 17:18:22:353 SkywalkingAgent-2-GRPCChannelManager-0 GRPCChannelManager : Selected collector grpc service running, reconnect:false.
DEBUG 2020-03-09 17:18:22:357 SkywalkingAgent-5-ServiceAndEndpointRegisterClient-0 ServiceAndEndpointRegisterClient : ServiceAndEndpointRegisterClient running, status:CONNECTED.
DEBUG 2020-03-09 17:18:25:356 SkywalkingAgent-5-ServiceAndEndpointRegisterClient-0 ServiceAndEndpointRegisterClient : ServiceAndEndpointRegisterClient running, status:CONNECTED.

Se o relato de dados não estiver ocorrendo, as possíveis causas incluem amostragem ativada, filtros configurados ou falta de solicitações que gerem traces distribuídos.

P: O ARMS suporta o SkyWalking Java Agent 9.x ou versões posteriores? Como resolver problemas de compatibilidade em um ambiente JDK 21?

R: O ARMS suporta a conexão com agentes open-source do SkyWalking. No entanto, a compatibilidade de versões específicas do SkyWalking Java Agent (como skywalking-java-agent:9.2.0 ou skywalking-java-agent:9.6.0) com versões do JDK é determinada pela comunidade open-source. Para confirmar a compatibilidade de versões, consulte a documentação oficial do SkyWalking.

Se você estiver executando o JDK 21 e encontrar o erro Unsupported class file major version 65, a causa é que versões mais antigas do Agente (como 8.7.0) dependem de uma versão do Byte-buddy que não suporta Java 21 (versão principal do arquivo de classe 65). Para resolver esse problema, use um dos seguintes métodos:

• Atualize seu SkyWalking Java Agent para a versão 8.16.0 ou posterior. Esta versão inclui uma release do Byte-buddy que suporta Java 21.

• Faça o downgrade do JDK da sua aplicação para uma versão suportada pelo seu Agente atual.

Se precisar de suporte estável para versões superiores do JDK, recomendamos o uso do agente proprietário de monitoramento de aplicações do ARMS.

P: O agente SkyWalking tem um impacto significativo no uso do disco local do Pod?

R: O agente SkyWalking tem um impacto mínimo no disco local do Pod. O agente grava logs temporariamente no armazenamento local apenas (caminhos padrão: ArmsAgent/log ou o diretório /logs dentro da pasta do Agente). Ele não armazena dados de trace de forma persistente. O consumo primário de recursos do agente SkyWalking é cpu e memória, não disco. Os arquivos de log são retidos por um curto período e limpos automaticamente pelo sistema. Portanto, o agente SkyWalking tem um impacto insignificante no uso do disco local do Pod.