Anexe o agente Java do Application Real-Time Monitoring Service (ARMS) à sua aplicação para coletar traces, topologia de aplicações, dados de transações anômalas e lentas, e análise SQL.
Para aplicações implantadas em clusters do Container Service for Kubernetes (ACK), instale o componente ack-onepilot. Consulte Instalar automaticamente um agente ARMS no ACK ou Instalar automaticamente um agente ARMS em um cluster Kubernetes de código aberto.
Pré-requisitos
Antes de começar, certifique-se de que:
Sua rede atende aos requisitos de conectividade do agente ARMS
Sua versão do JDK é suportada pelo Application Monitoring
A memória máxima de heap da JVM (
-Xmx) é de pelo menos 256 MB
Instalar o agente ARMS
Etapa 1: Baixar o agente
Acesse o console do ARMS.
No painel de navegação à esquerda, clique em Integration Center.
Clique no cartão Java Application Monitor e selecione Manual Installation.
Baixe o pacote do agente usando um dos métodos a seguir:
Pelo console — No painel Java Application Monitor, siga as instruções de download.
Pela linha de comando — Execute o comando
wgetda sua região. Selecione sua região na tabela abaixo.
Etapa 2: Extrair o pacote do agente
Extraia o arquivo ZIP baixado para um diretório de trabalho:
unzip AliyunJavaAgent.zip -d <working-directory>Substitua <working-directory> pelo diretório onde deseja instalar o agente, por exemplo, /opt/arms.
Etapa 3: Configurar a chave de licença e o nome da aplicação
O agente ARMS requer dois parâmetros para reportar dados:
| Parâmetro | Descrição | Onde encontrar |
|---|---|---|
LicenseKey | Autentica o agente com sua conta ARMS | Copie do painel Java Application Monitor ou chame a API DescribeTraceLicenseKey |
AppName | Identifica sua aplicação no console do ARMS. Em uma arquitetura distribuída, múltiplas instâncias pares compartilham o mesmo nome. | Escolha um nome, por exemplo, order-service |
Passe esses parâmetros de uma das seguintes maneiras:
Opção A: Passar como argumentos JVM (recomendado)
Adicione -Darms.licenseKey e -Darms.appName diretamente no comando de inicialização. Consulte a Etapa 4 para o comando completo.
Opção B: Usar um arquivo de configuração
Essa abordagem é útil quando múltiplas aplicações compartilham um único script de inicialização.
Primeiro, verifique a versão do agente no arquivo version dentro do diretório extraído.
ARMS agent V4.0.0 ou posterior:
Crie um arquivo chamado arms-agent.properties no diretório do agente:
arms.licenseKey=<your-license-key>
arms.appName=<your-app-name>Em seguida, adicione um dos seguintes ao seu comando de inicialização:
Argumento JVM:
-Dotel.javaagent.configuration-file=/path/to/arms-agent.propertiesVariável de ambiente:
OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.properties
ARMS agent anterior à V4.0.0:
Edite o arquivo arms-agent.config no diretório do agente:
arms.licenseKey=<your-license-key>
arms.appName=<your-app-name>Para obter detalhes sobre outros parâmetros do agente, consulte Modificar parâmetros do agente ARMS e regiões de relatório de dados.
Etapa 4: Adicionar o agente ao comando de inicialização
Adicione a opção -javaagent ao seu comando de inicialização. A sintaxe varia conforme o ambiente de execução.
Substitua os seguintes espaços reservados pelos valores reais:
| Espaço reservado | Descrição | Exemplo |
|---|---|---|
<working-directory> | Diretório onde você extraiu o agente | /opt/arms |
<your-license-key> | Sua chave de licença do ARMS | a]xxxxxx@xxxxxxxx |
<your-app-name> | Nome da aplicação para o ARMS | order-service |
Spring Boot ou java -jar
Coloque -javaagent antes do argumento -jar:
java -javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar \
-Darms.licenseKey=<your-license-key> \
-Darms.appName=<your-app-name> \
-jar demoApp.jarTomcat
Adicione a seguinte linha em {TOMCAT_HOME}/bin/setenv.sh:
JAVA_OPTS="$JAVA_OPTS -javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey=<your-license-key> -Darms.appName=<your-app-name>"Se setenv.sh não existir, acrescente a mesma configuração ao parâmetro JAVA_OPTS em {TOMCAT_HOME}/bin/catalina.sh. Consulte a linha 256 do catalina.sh como referência.
Jetty
Adicione o seguinte ao arquivo {JETTY_HOME}/start.ini:
--exec
-javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar
-Darms.licenseKey=<your-license-key>
-Darms.appName=<your-app-name>Múltiplas instâncias no mesmo servidor
Para executar múltiplas instâncias da mesma aplicação em um servidor, adicione -Darms.agentId com um valor exclusivo para diferenciar os processos JVM:
java -javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar \
-Darms.licenseKey=<your-license-key> \
-Darms.appName=<your-app-name> \
-Darms.agentId=001 \
-jar demoApp.jarPara versões do agente anteriores à V2.7.3.5, substitua
AliyunJavaAgent/aliyun-java-agent.jarporArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar. Faça a atualização para a versão mais recente assim que possível.No Windows, substitua
/por\nos caminhos e use arquivos.batem vez de.sh.Para ativar o Application Security (disponível a partir da V2.7.1.4), adicione
-Darms.appsec.enable=true. Consulte Faturamento do Application Security para obter informações sobre preços.
Etapa 5: Reiniciar a aplicação
Reinicie sua aplicação Java para que o agente entre em vigor.
(Opcional) Instalar com Docker
Use o seguinte Dockerfile como modelo para instalar o agente ARMS em uma imagem Docker:
# Replace <your-base-image:tag> with your image
FROM <your-base-image:tag>
WORKDIR /root/
# Download the agent (use the URL for your region; see Step 1)
RUN wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/AliyunJavaAgent.zip" -O AliyunJavaAgent.zip
RUN unzip AliyunJavaAgent.zip -d /root/
# Set credentials as environment variables
ENV arms_licenseKey=<your-license-key>
ENV arms_appName=<your-app-name>
# Inject the agent via JAVA_TOOL_OPTIONS
ENV JAVA_TOOL_OPTIONS ${JAVA_TOOL_OPTIONS} '-javaagent:/root/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey='${arms_licenseKey}' -Darms.appName='${arms_appName}
# Verify the environment variable
RUN env | grep JAVA_TOOL_OPTIONS
# Add your application-specific instructions below
# ...Verificar a instalação
Após reiniciar a aplicação, o agente começa a reportar dados em aproximadamente um minuto.
No console do ARMS, escolha Application Monitoring > Application List.
Confirme que sua aplicação aparece na lista e que os registros de dados estão sendo enviados.
Se sua aplicação não aparecer após alguns minutos, verifique o seguinte:
| Problema | Ação |
|---|---|
| Credenciais incorretas | Verifique se os valores de LicenseKey e AppName correspondem aos valores no console do ARMS. |
| Caminho do agente incorreto | Confirme que o caminho -javaagent aponta para o arquivo aliyun-java-agent.jar correto. |
| Aplicação não reiniciada | Reinicie a aplicação após adicionar a configuração do agente. |
| Conectividade de rede | Verifique se o servidor consegue alcançar o endpoint do ARMS pela rede. Consulte Configurações de rede. |
| Falha na inicialização do agente | Verifique nos logs de inicialização da aplicação as mensagens de inicialização do agente ARMS. Procure por linhas contendo ArmsAgent ou arms-agent. Se nenhuma entrada de log do agente aparecer, o argumento -javaagent pode não ter sido carregado. |
Para mais orientações de solução de problemas, consulte o FAQ do Application Monitoring.