Managed Service for OpenTelemetry:Use SkyWalking to report Java application data

Sample code

For more information about the sample code repository, see skywalking-demo at GitHub.

Use SkyWalking to automatically instrument a Java application

1. Open the config/agent.config file and configure the endpoint and token.

   Note

   Replace <endpoint> with the endpoint of the region in which the SkyWalking client resides. Replace <auth-token> with the authentication token of the client. You can log on to the Managed Service for OpenTelemetry console and view the endpoint on the Access point information tab of the Cluster Configurations page. For more information about how to obtain the endpoint, see the "Prerequisites" section of this topic.

   collector.backend_service=<endpoint>
   agent.authentication=<auth-token>

2. Use one of the following methods to specify an application name:

   Important

   Replace <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

3. Use one of the following methods to specify the path to the skywalking-agent.jar file in the agent folder:

   Note

   Replace <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.

     Important

     The -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>

4. 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 8.16.0.

Configuration methods

System attributes

Use -Dskywalking. and the key of the agent.config configuration file. Sample code:

# 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>

Precedence

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?

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.