All Products
Search
Document Center

Application Real-Time Monitoring Service:Use SkyWalking to report Java application data

Last Updated:May 11, 2024

After you use SkyWalking to instrument an application and report the trace data to the Managed Service for OpenTelemetry console, Managed Service for OpenTelemetry starts to monitor the application. Then, you can view the monitoring data of the application, such as the application topology, traces, abnormal transactions, slow transactions, and SQL analysis. This topic describes how to use the SkyWalking Java agent to perform automatic instrumentation. This topic also describes the configurable attributes of the SkyWalking Java agent.

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 agent folder 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.

Warning

All logs, plug-ins, and configuration files are stored in the agent folder. Do not change the folder.

To obtain an endpoint of SkyWalking, perform the following steps:

  1. Log on to the Managed Service for OpenTelemetry console.

  2. In the left-side navigation pane, click Cluster Configurations. On the page that appears, click the Access point information tab.

  3. In the top navigation bar, select a region. In the Cluster Information section, turn on Show Token.

  4. Set the Client parameter to SkyWalking.

    Obtain an endpoint of SkyWalking in the Related Information column of the table in the lower part.

    SkyWalking接入点信息

    Note

    If your application is deployed in an Alibaba Cloud production environment, use a VPC endpoint. Otherwise, use a public endpoint.

Background information

SkyWalking is a popular application performance monitoring (APM) service developed in China. SkyWalking is designed for microservices, cloud-native architectures, and container-based architectures. Container-based architectures include 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 automatic instrumentation for various frameworks and libraries, including Dubbo, gRPC, JDBC, OkHttp, Spring, Tomcat, Struts, and Jedis. SkyWalking also allows you to manually instrument applications based on the OpenTracing standard. This topic describes how to automatically instrument an application.

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 V8.16.0.

Expand to view attributes of the SkyWalking Java agent

Attribute

Description

Default value

agent.namespace

The namespace that is used to isolate headers in cross-process propagation. If you configure this attribute, the header name is HeaderName:Namespace.

None

agent.service_name

The service name that is displayed in the SkyWalking user interface (UI). Version 5.x corresponds to Application and version 6.x corresponds to Service. We recommend that you specify a unique name for each service. Multiple instances of a service share the same name.

Your_ApplicationName

agent.sample_n_per_3_secs

A negative number or 0 indicates that no sample data is collected. By default, no sample data is collected. SAMPLE_N_PER_3_SECS indicates that N sample data records are collected every 3 seconds.

None

agent.authentication

Authentication is enabled based on the backend configurations. You can view the authentication token of the server endpoint. Backend extensions are required for most scenarios. Only basic authentication features are implemented.

None

agent.span_limit_per_segment

The maximum number of spans in a single segment. If this attribute is configured, SkyWalking can assess the memory usage of applications.

None

agent.ignore_suffix

If the operation name of the first span is included in this collection, this segment is ignored.

None

agent.is_open_debugging_class

If you set this attribute to true, the SkyWalking agent stores all instrumented class files to the /debugging folder. The SkyWalking team may request you to provide these class files to resolve compatibility issues.

None

agent.cause_exception_depth

The stack depth that the SkyWalking agent needs to record when exceptions are recorded.

5

agent.force_reconnection_period

The force reconnection period of gRPC based on the value of the grpc_channel_check_interval attribute.

1

agent.operation_name_threshold

The maximum length of an operation name. An operation name can be up to 190 characters in length.

150

agent.keep_tracing

If you set this attribute to true, the SkyWalking agent continues to collect data even when the background service is unavailable.

false

osinfo.ipv4_list_size

The maximum number of IPv4 addresses.

10

collector.grpc_channel_check_interval

The interval at which the gRPC channel status is checked.

30

collector.backend_service

The backend address of the collector that receives the SkyWalking trace data.

127.0.0.1:11800

collector.heartbeat_period

The period during which the heartbeat of the SkyWalking agent is reported. Unit: second.

30

collector.grpc_upstream_timeout

The timeout period during which the gRPC client sends data to upstream applications. Unit: second.

30

collector.get_profile_task_interval

The interval at which the SkyWalking agent queries the tasks that are run to configure files.

20

logging.level

The log level. Default value: DEBUG.

DEBUG

logging.file_name

The name of the log file.

skywalking-api.log

logging.output

The mode in which logs are exported. By default, the logs are exported as files. If you use the console to export logs, the logs are exported in standard mode. If you run commands to export logs, the logs are directly exported.

FILE

logging.dir

The directory in which the logs are stored. The default value is an empty string. This indicates that the logs are stored in the system.out directory.

""

logging.pattern

The log format. Supported format conversion specifiers:

  • %level: the log level.

  • %timestamp: the current time, in the yyyy-MM-dd HH:mm:ss:SSS format.

  • %thread: the name of the current thread.

  • %msg: the recorded messages.

  • %class: the simple name of the class.

  • %throwable: the exception that is thrown by the user.

  • %agent_name: the name of the agent.

%level %timestamp %thread %class : %msg %throwable

logging.max_file_size

The maximum size of the log file. If the size of a log file exceeds the threshold, the current log file is archived and logs are written into a new file.

300 * 1024 * 1024

logging.max_history_files

The maximum number of historical log files. By default, a negative number or 0 indicates that the number of historical log files is not limited.

-1

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.image.png

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.image.png

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.

Expand to view the plug-ins

Framework

Plug-in version

HTTP Server

Tomcat 7

Tomcat 8

Tomcat 9

Spring Boot Web 4.x

Spring MVC 3.x, 4.x, and 5.x with servlet 3.x

Nutz Web Framework 1.x

Struts2 MVC in the version range from 2.3.x to 2.5.x

Resin 3

Resin 4

Jetty Server 9

Spring Webflux 5.x

Undertow in the version range from 2.0.0.Final to 2.0.13.Final

RESTEasy in the version range from 3.1.0.Final to 3.7.0.Final

Play Framework in the version range from 2.6.x to 2.8.x

Light4J Microservices Framework in the version range from 1.6.x to 2.x

Netty SocketIO 1.x

HTTP Client

Feign 9.x

Netflix Spring Cloud Feign 1.1.x, 1.2.x, and 1.3.x

Okhttp 3.x

Apache httpcomponent HttpClient 4.2 and 4.3

Spring RestTemplete 4.x

Jetty Client 9

Apache httpcomponent AsyncClient 4.x

HTTP Gateway

Spring Cloud Gateway 2.1.x.RELEASE

JDBC

MySQL Driver 5.x, 6.x, and 8.x

Oracle Driver

H2 Driver in the version range from 1.3.x to 1.4.x

Sharding-JDBC 1.5.x

ShardingSphere 3.0.0

ShardingSphere 3.0.0, 4.0.0-RC1

PostgreSQL Driver 8.x, 9.x, and 42.x

Mariadb Driver 2.x and 1.8

RPC framework

Dubbo in the version range from 2.5.4 to 2.6.0

Dubbox 2.8.4

Apache Dubbo 2.7.0

Motan in the version range from 0.2.x to 1.1.0

gRPC 1.x

Apache ServiceComb Java Chassis in the version range from 0.1 to 0.5 and 1.0.x

SOFARPC 5.4.0

Armeria in the version range from 0.63.0 to 0.98.0

Apache Avro in the version range from 1.7.0 to 1.8.x

Finagle in the version range from 6.25.0 to 20.1.0

MQ

RocketMQ 4.x

Kafka in the version range from 0.11.0.0 to 1.0

ActiveMQ 5.x

RabbitMQ 5.x

Pulsar in the version range from 2.2.x to 2.4.x

NoSQL

Redis

Jedis 2.x

Redisson Easy Java Redis client 3.5.2 or later

Lettuce 5.x

MongoDB

MongoDB Java Driver 2.13, 2.14, and 3.3 or later

Memcached Client

Spymemcached 2.x

Xmemcached 2.x

Elasticsearch

transport-client in the version range from 5.2.x to 5.6.x

transport-client in the version range from 6.7.1 to 6.8.4

rest-high-level-client in the version range from 6.7.1 to 6.8.4

SolrJ in the version range from 7.0.0 to 7.7.1

SolrJ 7.x

Cassandra 3.x

cassandra-java-driver in the version range from 3.7.0 to 3.7.2

Service discovery

Netflix Eureka

Distributed coordination

ZooKeeper 3.4.x (except 3.4.4)

Spring ecosystem

Spring Bean annotations(@Bean, @Service, @Component, @Repository) 3.x and 4.x

Spring Core Async SuccessCallback/FailureCallback/ListenableFutureCallback 4.x

Hystrix in the version range from 1.4.20 to 1.5.12 for distributed system latency and fault tolerance

Scheduler

Elastic Job 2.x

OpenTracing community support

Canal in the version range from 1.0.25 to 1.1.2: MySQL binlog-based component developed by Alibaba Cloud for incremental data synchronization and consumption

JSON

GSON 2.8.x

Vert.x ecosystem

Vert.x Eventbus 3.2 or later

Vert.x Web 3.x

Thread scheduling framework

Spring @Async 4.x and 5.x

Cache

Ehcache 2.x

Kotlin

Coroutine in the version range from 1.0.1 to 1.3.x

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

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.