Before you can view the trace data of an application in the Managed Service for OpenTelemetry console, you must use a client to report the trace data to Managed Service for OpenTelemetry. This topic describes how to use SkyWalking to report the data of Java applications.
Prerequisites
SkyWalking 6.X.X or later is downloaded from the SkyWalking download page. We recommend that you download the latest stable version. The decompressed folder Agent is stored in a directory that can be accessed by Java processes.
All plug-ins are stored in the
/plugins
directory. If you add a plug-in to the directory during startup, the plug-in takes effect. If you remove a plug-in from the directory, the plug-in becomes ineffective. By default, log files are stored in the/logs
directory.
All logs, plug-ins, and configuration files are stored in the Agent folder. Do not change the folder.
Background information
SkyWalking is a popular application performance monitoring (APM) service developed in China. SkyWalking is designed for microservices, cloud-native architectures, and containers, such as Docker, Kubernetes, and Mesos. SkyWalking is also a distributed tracing system.
Before you can use SkyWalking to report Java application data to the Managed Service for OpenTelemetry console, you must instrument your applications. SkyWalking provides auto-instrument agents such as Dubbo, gRPC, JDBC, OkHttp, Spring, Tomcat, Struts, and Jedis, and allows you to manually instrument applications. This topic describes how to automatically instrument applications.
Sample code
For more information about the sample code repository, see skywalking demo at GitHub.
Use SkyWalking to automatically instrument a Java application
Open the
config/agent.config
file and configure the endpoint and token.Note Replace<endpoint>
with the endpoint of the region where the SkyWalking client resides. Replace<auth-token>
with the authentication token of the client. You can obtain the endpoint and the authentication token on the Overview page in the Tracing Analysis console. For more information, see the Prerequisites topic.collector.backend_service=<endpoint> agent.authentication=<auth-token>
Use one of the following methods to specify an application name:
ImportantReplace
<ServiceName>
with your application name. If you use both methods, only the second method that adds a parameter to the startup command takes effect.Open the
config/agent.config
file and specify an application name.agent.service_name=<ServiceName>
Add the -Dskywalking.agent.service_name parameter to the startup command of the application:
java -javaagent:<skywalking-agent-path> -Dskywalking.agent.service_name=<ServiceName> -jar yourApp.jar
Use one of the following methods to specify the path to the Agent folder based on the running environment of the application:
NoteReplace
<skywalking-agent-path>
in the following sample code with the absolute path to the skywalking-agent.jar file in the Agent folder.Linux Tomcat 7 or Tomcat 8
Add the following content as the first line in the
tomcat/bin/catalina.sh
file:CATALINA_OPTS="$CATALINA_OPTS -javaagent:<skywalking-agent-path>"; export CATALINA_OPTS
Windows Tomcat 7 or Tomcat 8
Add the following content as the first line in the
tomcat/bin/catalina.bat
file:set "CATALINA_OPTS=-javaagent:<skywalking-agent-path>"
JAR File or Spring Boot
Add the -javaagent parameter to the startup command of the application.
ImportantThe -javaagent parameter must be written before the -jar parameter.
java -javaagent:<skywalking-agent-path> -jar yourApp.jar
Jetty
Add the following content to the
{JETTY_HOME}/start.ini
configuration file:--exec # Remove the number sign (#) to uncomment the code. -javaagent:<skywalking-agent-path>
Restart the application.
Configurable attributes of the SkyWalking Java agent
The SkyWalking Java agent supports a wide range of attributes that you can configure. For more information, see the config/agent.config file in the sample code.
Partial attributes of the SkyWalking Java agent
The following table describes the partial attributes of SkyWalking Java agent V8.16.0.
Configuration methods
System attributes
Use -Dskywalking.
and the key of the agent.config
configuration file. Example:
# Configure the agent.service_name attribute by using system attributes.
java -javaagent:/path/to/skywalking-agent.jar -Dskywalking.agent.service_name=<your_service_name> -jar your-project.jar
Proxy options
Add the attributes after the proxy path in the JVM parameter.
# Template
-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
System environment variables
Configure the attributes as system environment variables. The SkyWalking agent automatically obtains the system environment variables. You can query the system environment variables that correspond to specific attributes in the config/agent.config file. For example, the agent.service_name attribute corresponds to the system environment variable SW_AGENT_NAME.
agent.service_name=${SW_AGENT_NAME:default_name}
# Configure the environment variable.
export SW_AGENT_NAME=<your_service_name>
Priority
The preceding configuration methods are prioritized in the following order: proxy options, system properties, system environment variables, and configuration files.
SkyWalking Java agent plug-ins
The SkyWalking Java agent supports a variety of middleware, frameworks, and repositories. For more information about the supported plug-ins, see the /plugins folder in the sample code.
Activate plug-ins
All plug-ins in the /plugins folder are activated. If the JAR package of a plug-in is removed from the /plugins folder, the plug-in becomes unavailable.
Supported official plug-ins
The supported official plug-ins are available in the /plugins folder.
Optional plug-ins
The plug-ins of the SkyWalking Java agent are pluggable. Optional plug-ins are available in the optional-plugins folder of the third-party repository or Agent. To use an optional plug-in, move the plug-in to the /plugins folder.
Bootstrap plug-ins
All Bootstrap plugins are optional due to unexpected risks. Bootstrap plugins are available in the bootstrap-plugins folder. If you want to use Bootstrap plug-ins, you can add the JAR packages of the plug-ins to the /plugins folder.
Supported plug-ins
The official team of SkyWalking believes that the following plug-ins may affect the performance of SkyWalking and limit its use. Therefore, the plug-ins are released only in third-party repositories. For more information, see java-plugin-extensions at GitHub.
Develop a plug-in
To create a custom SkyWalking Java agent plug-in, refer to the official documentation of SkyWalking.
Managed Service for OpenTelemetry supports trace reporting. To create a custom trace plug-in, refer to the official documentation of SkyWalking.
FAQ
Q: Why am I unable to create an application after SkyWalking is connected to the server?
A: The data may not be reported to Managed Service for OpenTelemetry. You must check whether the data is reported to Managed Service for OpenTelemetry. For example, you can check the content in the {skywalking agent path}/logs/skywalking-api.log file. If data is reported, the following figure is displayed.
Data may not be reported due to the following reasons: sampling is enabled, the data is filtered, or the request for using Managed Service for OpenTelemetry is not triggered.