修改配置

在安装探针之前，请解压tingyun-agent-java.zip文件，并修改tingyun.properties中 nbs.license_key和 nbs.app_name。

nbs.license_key

该选项为必填项，与您的基调听云账号关联。探针采集到得数据，会上传到该 license key绑定的账号下。License Key的获取方式请参考本页第一步和第二步。如果您是从探针下载页面获取的探针，请参考下面的配置：

#请删除“<%=license_key%>”，并输入当前账号的License Key。
#nbs.license_key=<%=license_key%> 

#例如：
nbs.license_key=1234567890

nbs.app_name

默认值是“Java Application”，建议修改为应用的业务名称。

#默认值是Java Application,建议修改为应用的业务名称
#nbs.app_name=Java Application

#例如：更改后user_center表示该应用负责“用户中心”业务
nbs.app_name=user_center

除了在tingyun.properties配置nbs.app_name之外，基调听云Java Agent还提供通过JVM Options配置应用名称。即在JVM启动参数增加：-Dtingyun.config.nbs.app_name。例如：

#推荐使用
-Dtingyun.config.nbs.app_name="Application Name" //Application Name为应用名称

#错误的配置方式
-Dtingyun.config.nbs.app_name=Application Name  //参数值包含空格，且未使用双引号，导致启动失败。
-Dtingyun.config.nbs.app_name="Application-华北" //参数值包含中文，可能会导致报表中的应用名称为乱码，不推荐使用。
-Dtingyun.config.nbs.app_name=“Application goods” //使用中文双引号，导致启动失败

更多JVM Options请参考官方说明。

注意事项

在tingyun-agent-java.zip文件中包含以下内容：

• tingyun-agent-java.jar: 基调听云探针文件。
• tingyun.properties: 配置文件，包括license key、应用名称等其他参数，具体请查看配置文件中的说明选择适合的填写。
• extensions/ : 扩展目录，放置扩展plugins及自定义嵌码配置xml文件。
• ReleaseNote：探针版本更新说明。

JVM Options

在安装探针之前，除了需要确认tingyun.properties中的配置以外，强烈建议检查并修改JVM Options中以下几个参数：

• 如果没有设置内存参数，建议在JAVA_OPTS中增加内存配置。以Linux环境中Tomcat的启动脚本catalina.sh为例：

JAVA_OPTS="$JAVA_OPTS -Xms2048m -Xmx2048m -XX:MaxPermSize=128m -XX:PermSize=128m"

• 如果已经设置过JVM Options，建议在原有基础上-Xmx增加200M或更多，-XX:PermSize增加60M或更多。

• 如果出现 java.lang.OutOfMemoryError:PermGen space，则需要将XX:MaxPermSize和XX:PermSize参数调大。

更多JVM Options请参考官方说明。

根据以往的经验，如果应用没有优化过JVM Options，那么安装探针后的应用在启动时或运行一段时间后可能会抛出内存溢出异常，导致应用不可用。

Caused by : java.lang.OutOfMemoryError:PermGen space
			at java.lang.ClassLoader.defineClass (Native Method)
			at java.lang.ClassLoader.defineClassCond(ClassLoader.java:631)
			at java.lang.ClassLoader.defineClass(ClassLoader.java.615)
			...more

原因

在JDK1.6、JDK1.7版本中PermGen space（Permanent Generation Space）是指内存永久保存区域，是JVM存储Class和元数据的地方。

如果应用程序加载大量的Class，而且没有优化-XX:MaxPermSize参数，在未安装探针时就占用了PermGen space大部分空间。那么安装探针之后，Classloader会将探针的Class放入PermGen space。此时如果PermGen space空间不足，就会抛出java.lang.OutOfMemoryError:PermGen space异常。

在JDK1.8版本从Hotspot JVM中删除了Permanent Generation，被Metaspace代替。虽然JDK1.8的Metaspace只受系统内存限制，但依然可以通过-XX:MaxMetaspaceSize调整其大小。

查看JVM启动参数

在Linux环境下可以通过 jps -vJava进程的一些简单情况。

[root@localhost apache-tomcat-6.0.45]# java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)

[root@localhost apache-tomcat-6.0.45]# jps -v
12 Bootstrap -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.library.path=/opt/apache-tomcat/lib -Xms512m -Xmx2048m -XX:NewRatio=4 -Xss1024k -XX:PermSize=64M -XX:MaxPermSize=256M -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:/opt/apache-tomcat/logs/gc.log -Duser.language=zh -Duser.region=CN -Duser.timezone=GMT+08  -javaagent:/opt/tingyun_agent/tingyun/tingyun-agent-java.jar  -Djava.endorsed.dirs=/opt/apache-tomcat/endorsed -Dcatalina.base=/opt/apache-tomcat -Dcatalina.home=/opt/apache-tomcat -Djava.io.tmpdir=/opt/apache-tomcat/temp

或者登录基调听云Server报表，在应用环境菜单里查看JVM启动参数。

目录权限

在Application Server 启动的时候，探针会在tingyun-agent-java.jar的同级目录查找tingyun.properties文件；并在该目录创建logs文件夹，用来记录探针运行日志，请确保该目录有写权限。

时间同步

tingyun-agent-java.jar在运行时采用的是当前主机系统时间，为确保探针上传数据的时间有效性，请在启动探针之前，确保系统时间与标准时间一致。