文档

通过SkyWalking上报Java应用数据

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

通过SkyWalking为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后,可观测链路 OpenTelemetry 版即可开始监控应用,您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用SkyWalking Java Agent进行自动埋点,以及SkyWalking Java Agent可配置属性的相关信息。

前提条件

  • 打开SkyWalking下载页面,下载SkyWalking 6.X.X或以上版本(建议下载最新稳定版本),并将解压后的Agent文件夹放至Java进程有访问权限的目录。

  • 插件均放置在/plugins目录中。在启动阶段将新的插件放进该目录,即可令插件生效。将插件从该目录删除,即可令其失效。另外,日志文件默认输出到/logs目录中。

警告

日志、插件和配置文件都在Agent文件夹中,请不要改变文件夹结构。

获取接入点信息

  1. 登录可观测链路 OpenTelemetry 版控制台

  2. 在左侧导航栏单击集群配置,然后在右侧页面单击接入点信息页签。

  3. 在页面顶部选择需要接入的地域,然后在集群信息区域打开显示Token开关。

  4. 客户端采集工具区域单击SkyWalking

    在下方表格的相关信息列中,获取接入点信息。

    SkyWalking接入点信息

    说明

    如果应用部署于阿里云生产环境,则选择阿里云VPC网络接入点,否则选择公网接入点。

背景信息

SkyWalking是一款广受欢迎的国产APM(Application Performance Monitoring,应用性能监控)产品,主要针对微服务、Cloud Native和容器化(Docker、Kubernetes、Mesos)架构的应用。SkyWalking的核心是一个分布式追踪系统。

要通过SkyWalking将Java应用数据上报至可观测链路 OpenTelemetry 版控制台,首先需要完成埋点工作。SkyWalking既支持自动探针(Dubbo、gRPC、JDBC、OkHttp、Spring、Tomcat、Struts、Jedis等),也支持手动埋点(OpenTracing)。本文介绍自动埋点方法。

示例Demo

示例代码仓库地址:SkyWalking Demo

用SkyWalking为Java应用自动埋点

  1. 打开config/agent.config,配置接入点和令牌。

    说明 请将<endpoint><auth-token>分别替换成控制台集群配置 > 接入点信息页面上SkyWalking客户端在相应地域的接入点和鉴权令牌。关于获取方法,请参见前提条件。
    collector.backend_service=<endpoint>
    agent.authentication=<auth-token>
  2. 采用以下方法之一配置应用名称(Service Name)。

    重要

    请将<ServiceName>替换为您的应用名称。如果同时采用以下两种方法,则仅第二种方法(在启动命令行中添加参数)生效。

    • 打开config/agent.config,配置应用名称。

      agent.service_name=<ServiceName>
    • 在应用程序的启动命令行中添加-Dskywalking.agent.service_name参数。

      java -javaagent:<skywalking-agent-path> -Dskywalking.agent.service_name=<ServiceName> -jar yourApp.jar
  3. 根据应用的运行环境,选择相应的方法来指定SkyWalking Agent的路径。

    说明

    请将以下示例代码中的<skywalking-agent-path>替换为Agent文件夹中的skywalking-agent.jar的绝对路径。

    • Linux Tomcat 7 / Tomcat 8

      tomcat/bin/catalina.sh第一行添加以下内容:

      CATALINA_OPTS="$CATALINA_OPTS -javaagent:<skywalking-agent-path>"; export CATALINA_OPTS
    • Windows Tomcat 7 / Tomcat 8

      tomcat/bin/catalina.bat第一行添加以下内容:

      set "CATALINA_OPTS=-javaagent:<skywalking-agent-path>"
    • JAR File或Spring Boot

      在应用程序的启动命令行中添加-javaagent参数。

      重要

      -javaagent参数一定要在-jar参数之前。

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

      {JETTY_HOME}/start.ini配置文件中添加以下内容:

      --exec    # 去掉前面的井号取消注释。
      -javaagent:<skywalking-agent-path>
  4. 重新启动应用。

Java Agent可配置属性

SkyWalking Java Agent支持丰富的用户可配置属性。完整的属性配置详情,请参见示例Demo的config/agent.config文件。

属性列表(部分)

以下属性以apache-skywalking-java-agent-8.16.0为准。

展开查看属性列表

属性名

描述

默认值

agent.namespace

命名空间,用于隔离跨进程传播的header。如果进行了配置,header将为HeaderName:Namespace。

未设置

agent.service_name

在SkyWalking UI中展示的服务名。5.x版本对应Application,6.x版本对应Service。 建议:为每个服务设置唯一的名字,服务下的多个实例使用相同的服务名。

Your_ApplicationName

agent.sample_n_per_3_secs

负数或0表示不采样,默认不采样。SAMPLE_N_PER_3_SECS表示每3秒采样N条。

未设置

agent.authentication

鉴权是否开启取决于后端的配置,可查看服务端接入点的鉴权Token。对于大多数的场景,需要后端对鉴权进行扩展。目前仅实现了基本的鉴权功能。

未设置

agent.span_limit_per_segment

单个segment中span的最大数量。通过这个配置项,SkyWalking可评估应用程序内存使用量。

未设置

agent.ignore_suffix

如果这个集合中包含了第一个span的操作名,这个segment将会被忽略掉。

未设置

agent.is_open_debugging_class

如果为true,SkyWalking会将所有经Instrument转换过的类文件保存到/debugging文件夹下。SkyWalking团队会要求提供这些类文件以解决兼容性问题。

未设置

agent.cause_exception_depth

在记录异常信息的时候,探针需要记录的堆栈深度。

5

agent.force_reconnection_period

gRPC的强制重连周期,基于grpc_channel_check_interval。

1

agent.operation_name_threshold

设置操作名不建议超过的最大长度(190)。

150

agent.keep_tracing

如果该值为true,即使后台不可用,也要保持跟踪。

false

osinfo.ipv4_list_size

限制IPv4列表的长度。

10

collector.grpc_channel_check_interval

检查gRPC的Channel状态的时间间隔。

30

collector.backend_service

接收SkyWalking Trace数据的后端地址。

127.0.0.1:11800

collector.heartbeat_period

探针心跳报告时间。单位:秒。

30

collector.grpc_upstream_timeout

gRPC客户端向上游发送数据时超时多长时间。单位:秒。

30

collector.get_profile_task_interval

嗅探器获取配置文件任务列表间隔。

20

logging.level

日志级别。默认为debug。

DEBUG

logging.file_name

日志文件名。

skywalking-api.log

logging.output

日志输出方式,默认是文件,使用控制台默认为标准输出(命令行直接输出)。

FILE

logging.dir

日志目录。默认为空串,表示使用"system.out"输出日志。

""

logging.pattern

日志格式。所有的转换说明符:

  • %level:日志等级。

  • %timestamp:现在的时间,格式: yyyy-MM-dd HH:mm:ss:SSS

  • %thread:当前线程的名称。

  • %msg:用户记录的某些消。

  • %class:TargetClass的SimpleName。

  • %throwable:用户抛出的异常。

  • %agent_name:agent.service_name。

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

logging.max_file_size

日志文件的最大大小。当日志文件大小超过该值,归档当前的日志文件,并将日志写入到新文件中。

300 * 1024 * 1024

logging.max_history_files

最大历史日志文件数量。默认情况下,负数或0表示关闭。

-1

配置方式

系统属性

使用-Dskywalking. + agent.config配置文件的key。例如:

# 通过系统属性配置agent.service_name
java -javaagent:/path/to/skywalking-agent.jar -Dskywalking.agent.service_name=<your_service_name> -jar your-project.jar

代理选项

在JVM参数中的代理路径之后添加属性即可。

# 模版
-javaagent:/path/to/skywalking-agent.jar=[key1]=[value1],[key2]=[value2]

# 举例
java -javaagent:/path/to/skywalking-agent.jar=agent.service_name=<your-service-name>,agent.authentication=<your-token> -jar your-project.jar

系统环境变量

将属性配置成系统环境变量,skywalking-agent会自动获取。可以在config/agent.config文件中查询具体属性对应的系统环境变量,例如agent.service_name的系统环境变量为SW_AGENT_NAME。

agent.service_name=${SW_AGENT_NAME:default_name}

# 配置环境变量
export SW_AGENT_NAME=<your_service_name>

优先级

以上配置方式的优先级从高到低依次为代理选项、系统属性、系统环境变量、配置文件。

Java Agent插件

SkyWalking Java Agent支持多种中间件、框架和库。支持的所有插件可在示例Demo的/plugins文件夹下查看。

激活插件

所有在/plugins文件夹下的插件都是已被激活的插件。若从/plugins中移除某个插件的jar包,则表示插件不可用。

官方已支持插件

官方支持的插件都已在/plugins文件夹下。

可选插件

Java Agent的插件支持可插拔。在Agent或第三方仓库的optional-plugins文件夹下提供了可选的插件。 想要使用可选插件,可以将对应插件移动到/plugins文件夹下。image.png

Bootstrap类插件

由于意外风险,所有Bootstrap插件都是可选的。Bootstrap插件在bootstrap-plugins文件夹中。若需要使用这些插件,可以将目标插件的jar文件放入/plugins文件夹下。image.png

支持插件列表

关于下面的插件,官方认为可能存在性能影响或者使用限制,所以只在第三方仓库发布。更多信息请参见SkyAPM Java插件扩展仓库

展开查看插件列表

框架

插件版本

HTTP Server

Tomcat 7

Tomcat 8

Tomcat 9

Spring Boot Web 4.x

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

Nutz Web Framework 1.x

Struts2 MVC 2.3.x -> 2.5.x

Resin 3

Resin 4

Jetty Server 9

Spring Webflux 5.x

Undertow 2.0.0.Final -> 2.0.13.Final

RESTEasy 3.1.0.Final -> 3.7.0.Final

Play Framework 2.6.x -> 2.8.x

Light4J Microservices Framework 1.6.x -> 2.x

Netty SocketIO 1.x

HTTP Client

Feign 9.x

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

Okhttp 3.x

Apache httpcomponent HttpClient 4.2, 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, 8.x

Oracle Driver

H2 Driver 1.3.x -> 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, 42.x

Mariadb Driver 2.x, 1.8

RPC框架

Dubbo 2.5.4 -> 2.6.0

Dubbox 2.8.4

Apache Dubbo 2.7.0

Motan 0.2.x -> 1.1.0

gRPC 1.x

Apache ServiceComb Java Chassis 0.1 -> 0.5,1.0.x

SOFARPC 5.4.0

Armeria 0.63.0 -> 0.98.0

Apache Avro 1.7.0 - 1.8.x

Finagle 6.25.0 -> 20.1.0

MQ

RocketMQ 4.x

Kafka 0.11.0.0 -> 1.0

ActiveMQ 5.x

RabbitMQ 5.x

Pulsar 2.2.x -> 2.4.x

NoSQL

Redis

Jedis 2.x

Redisson Easy Java Redis client 3.5.2+

Lettuce 5.x

MongoDB

MongoDB Java Driver 2.13-2.14,3.3+

Memcached Client

Spymemcached 2.x

Xmemcached 2.x

Elasticsearch

transport-client 5.2.x-5.6.x

transport-client 6.7.1-6.8.4

rest-high-level-client 6.7.1-6.8.4

SolrJ 7.0.0-7.7.1

SolrJ 7.x

Cassandra 3.x

cassandra-java-driver 3.7.0-3.7.2

服务发现

Netflix Eureka

分布式协调

Zookeeper 3.4.x (3.4.4除外)

Spring生态系统

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

Spring Core Async SuccessCallback/FailureCallback/ListenableFutureCallback 4.x

Hystrix: 分布式系统延时和故障容错 1.4.20 -> 1.5.12

调度器

Elastic Job 2.x

OpenTracing社区支持

Canal: 阿里巴巴的基于MySQL binlog的增量订阅与消费组件 1.0.25 -> 1.1.2

JSON

GSON 2.8.x

Vert.x 生态

Vert.x Eventbus 3.2+

Vert.x Web 3.x

线程调度框架

Spring @Async 4.x and 5.x

缓存

Ehcache 2.x

Kotlin

Coroutine 1.0.1 -> 1.3.x

插件开发

您可以参考官方文档自定义开发一个SkyWalking Java Agent Plugin。

可观测链路 OpenTelemetry 版支持Trace上报,您可以参考官方文档开发一个自定义的Trace Plugin。

常见问题

问:SkyWalking正常连接服务端后,无法创建应用?

答:可能是由于链路追踪的数据未上报。您需要检查是否有链路追踪的数据上报,可以查看{skywalking agent path}/logs/skywalking-api.log内容。如果有数据上报,则显示如下图所示。pg_xtrace_skywalking

如果未产生数据上报,则可能原因是:开启采样、设置过滤或未触发生成链路追踪的请求。

  • 本页导读 (1)
文档反馈