全局配置

全局配置的­­­配置项允许用户设置对整个系统统一生效，包括日志溯源开关、开启追踪、错误及异常采集设置和探针熔断等选项。

Apdex T

Apdex 定义了应用响应时间的最优门槛 T（即Apdex T），另外根据应用响应时间结合T 定义了三种不同的性能表现：

• Satisfied（满意）：应用响应时间低于或等于 T（T由性能评估人员根据预期性能要求确定），则认为用户对应用的性能表现满意。比如 T为 1.5s，则一个耗时 1s 的响应结果则可以认为是满意的。

• Tolerating（可容忍）：应用响应时间大于 T，但同时小于或等于4T。假设应用设定的 T 值为 1s，则 4 * 1 = 4 秒，即为应用响应时间的容忍上限。

• Frustrated（不能忍受）：应用响应时间大于4T。另外，当一个请求的响应状态码为400及以上（401除外）或发生最外层异常时，无论响应时间长短，均归类为不能忍受。

应用与微服务取应用的平均响应时间作为计算指标，默认定义Apdex T 为 500毫秒。全局配置中的Apdex T配置适用于所有业务系统中的应用。

Apdex标准从用户的角度出发，对真实的响应时间进行采样，采集一定时间之后，将应用响应时间的表现，转化为用户对于应用性能的可量化的满意度评价，我们称之为Apdex指数，范围为0~1。0代表对所有请求响应时间的表现都不满意，1代表对所有请求响应时间的表现都满意。

计算公式为： Apdex指数 =（满意数+可容忍数/2）/成功次数

基调听云应用与微服务定义Apdex指数范围对应的颜色展示如下：

• 0.94~1：

• 0.85~0.94：

• 0.7~0.85：

• 0.7以下：

日志溯源

Java Agent 3.6.3.3及以下版本

一个事务往往会跨越很多个应用，事务的日志都分散在各个应用下，查找单次请求的所有日志较为困难。基调听云应用与微服务的日志溯源功能可以很好的解决这个问题。开启日志溯源功能后，应用与微服务探针可以自动在用户的日志内容中输出NBS.APPID和NBS.REQUEST_GUID属性，通过NBS.REQUEST_GUID属性可以关联不同应用和实例上单次请求的日志。当用户通过基调听云应用与微服务追踪到慢事务时，可以根据该次慢追踪的追踪ID在应用日志中查询该慢事务的所有日志信息。

说明：

• NBS.REQUEST_GUID即基调听云应用与微服务控制台页面中的追踪ID。
• 日志溯源默认是关闭状态。
• 只有对Java应用支持该功能。
• 日志溯源功能支持主流的Log4j和Logback日志框架。
• 要使用日志溯源功能，链路的所有应用都需要部署基调听云APM探针。

配置日志溯源，请按照以下步骤进行操作：

1. 如果应用初次使用该功能，需要在探针配置文件tingyun.properties中开启以下设置。

   # 日志追溯相关Plugin，开启后可以在应用的日志中，打印应用与微服务相关数据，如应用ID、追踪ID等。
   class_transformer.tingyun-log4j-plugin-2.0.0.enabled=true
   class_transformer.tingyun-log4j-plugin-2.3.enabled=true
   class_transformer.tingyun-log4j-plugin-1.2.enabled=true
   class_transformer.tingyun-logback-plugin-1.2.enabled=true
   

2. 登录应用与微服务控制台，在左侧导航栏中选择全局配置，在常规选项页签中开启日志溯源功能。

   

3. 配置被监控应用的日志配置文件。

   • Log4j配置

     log4j.appender.order-file-appender.layout.ConversionPattern=[%d] [%-5p] [%t]
     [%c] [%R][%A]%m%n
     

   • Log4j2配置

     <Console name="Console" target="SYSTEM_OUT"\>
      <PatternLayout pattern="%d{HH:mm:ss.SSS} [log4j2] %-5level %logger{36} -
      %msg%n[%A][%R]"/\>
     </Console\>
     

   • Logback配置

     <encoder\>
          <pattern\>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} -
       %msg%n[%A][%R]\</pattern\>
     </encoder\>
     

4. 查看输出的应用日志。

   例如，Log4j日志输出格式如下：

   2020-10-29T16:30:27,730-07:00][DEBUG][com.tingyun.Log-0][com.tingyun.Test][NBS.REQUEST_GUID:167d328d-b82a-4b8c-8049-7a3a13af158f][NBS.APPID:0017]
   
   Test Log Message
   

   其中，[%R]负责输出请求的NBS.REQUEST_GUID，配置后日志会增加NBS.REQUEST_GUID信息。在整个请求链路中，入口事务生成的NBS.REQUEST_GUID将作为整个请求链路的唯一标识，此值将在链路中不断传递直到链路的最后请求（如果遇到无法实现跨应用追踪的组件的情况除外），以实现全链路追踪。调用链所涉及的各个应用的日志都显示同一个NBS.REQUEST_GUID。[%A]负责输出应用的NBS.APPID，是应用与微服务系统为每一个监控的应用生成的唯一id，配置后日志会增加NBS.APPID信息。如果日志溯源功能是关闭的，即使用户配置了[%R]，NBS.REQUEST_GUID也不会被嵌入。

   

Java Agent 3.6.4及以上版本

一个事务往往会跨越很多个应用，事务的日志都分散在各个应用下，查找单次请求的所有日志较为困难。应用与微服务的日志溯源功能可以很好的解决这个问题。开启日志溯源功能后，APM探针可以自动在用户的日志内容中输出tingyun.app_id、tingyun.trace_id和tingyun.span_id属性，通过tingyun.trace_id属性可以关联不同应用和实例上单次请求的日志。当用户通过应用与微服务追踪到慢事务时，可以根据该次慢追踪的追踪ID在应用日志中查询该慢事务的所有日志信息。

说明：

• tingyun.trace_id即基调听云应用与微服务控制台页面中的追踪ID。
• 日志溯源默认是关闭状态。
• 只有对Java应用支持该功能。
• 日志溯源功能支持主流的Log4j和Logback日志框架。
• 要使用日志溯源功能，链路的所有应用都需要部署基调听云APM探针。

配置日志溯源，请按照以下步骤进行操作：

1. 登录应用与微服务控制台，在左侧导航栏中选择全局配置，在常规选项页签中开启日志溯源功能。

   

2. 默认情况下，探针采用自动注入方式在日志中增加tingyun.app_id、tingyun.trace_id和tingyun.span_id属性。该方式的优点是探针自动将数据写入应用日志，无需修改应用配置。缺点是您不能在日志配置文件中自定义上述属性输出的位置。

   日志输出示例：

   2022-03-24 16:43:52.302 [http-nio-8079-exec-1] INFO [tingyun.app_id:2503,tingyun.trace_id:77469a69f8b9fdce,tingyun.span_id:77469a69f8b9fdce] com.tyt.controller.LogbackController -Thread[http-nio-8079-exec-1,5,main]
   

3. 如果您的环境中对日志格式做了一些定义，日志溯源可能影响日志解析，此时如果您仍想使用日志溯源功能，可根据业务自定义输出位置。您可采用手动注入方式（不推荐），该方式需要配置被监控应用的日志配置文件。例如，您希望将上述属性输出在日志的最前面，可做如下配置：

   log4j.appender.order-file-appender.layout.ConversionPattern= [TINGYUN] [%d] [%-5p] [%t] [%c]%m%n
   

   日志输出示例：

   [tingyun.app_id:2503,tingyun.trace_id:77469a69f8b9fdce,tingyun.span_id:77469a69f8b9fdce] 2022-03-24 16:43:52.302 [http-nio-8079-exec-1] INFO  com.tyt.controller.LogbackController -Thread[http-nio-8079-exec-1,5,main]
   

   其中，[TINGYUN]负责输出请求的tingyun.app_id、tingyun.trace_id和tingyun.span_id。在整个请求链路中，入口事务生成的tingyun.trace_id将作为整个请求链路的唯一标识，此值将在链路中不断传递直到链路的最后请求（如果遇到无法实现跨应用追踪的组件的情况除外），以实现全链路追踪。调用链所涉及的各个应用的日志都显示同一个tingyun.trace_id。tingyun.app_id是应用与微服务为每一个监控的应用生成的唯一id。tingyun.span_id是应用与微服务为请求链路中每一段请求生成的唯一id。如果日志溯源功能是关闭的，即使用户配置了[TINGYUN]，上述3个属性也不会被嵌入。

   

采样

采样是针对链路追踪数据是否保留的一种策略。开启采样不会对指标数据造成影响。基调听云平台通过“调用链采样”和“请求采样”两种模式实现采样，两种模式只能开启其中一种。

调用链采样

默认情况下，应用与微服务探针提供全量的业务和性能数据采集。但是在应用访问量比较大时，为了让探针减少对CPU、内存等资源的消耗，可以对采集的调用链数据按照一定的比例进行保留，这样能够帮助您以较低的性能开销记录最有价值的链路数据。调用链采样适用于以下场景：

• 压测或大促期间流量过大，为了避免调用链数据全量上传影响客户端性能，可以考虑按需调整采样率的比例。
• 日常情况下，全量调用链数据上传导致网络带宽成本高，可以考虑按需调整采样率的比例。

调用链采样就是根据追踪ID记录一定比例的调用链数据。例如，固定比例为10‰，则每1000条调用链数据记录10条。采样不会导致调用链数据本身不完整，要么保留整条链路数据，要么丢弃整条链路数据。开启调用链采样后，Agent Collector在保障调用链完整的情况下，依据采样率保留事务追踪，性能汇总数据依然保持全量采集。默认调用链采样开关为关闭状态，开启后，默认采样率为5‰，请根据实际需要调整采样率。

说明：仅V3.6.1.2以上版本的Agent Collector支持调用链采样。

请求采样

开启请求采样后，基调听云平台将忽略调用链完整性诉求，依据作用在实例级上的采样配置，针对每次请求，保留其追踪数据。该模式下，链路完整性无法保证，请谨慎开启。

您可以根据固定比例或者固定个数两种模式来采集链路追踪数据。

• 默认情况下，每实例每分钟采集5‰的链路追踪数据，可根据实际需要进行配置。
• 默认情况下，每实例每分钟固定采集10000个链路追踪数据，可根据实际需要进行配置。

获取源代码

说明：仅私有化部署模式下支持使用该功能。

为了更快速地帮助用户找到代码问题，应用与微服务可通过获取用户应用的源代码进行问题分析。此处的源代码是指从JVM ClassLoader 中获取Java Classs文件，经反编译而转存的代码。基调听云不会主动获取任何Classes文件，只有当用户手动触发获取源文件时，才从JVM中动态获取。转存的Class文件，只供用户在线反编译使用，不会做其他用处。基调听云不会向任何第三方分发，暂存在磁盘上7天后会自动清理。

要获取源代码，请按以下步骤进行操作：

1. 实施人员配置Nacos组件的apm-api和apm-config，将applicaticonService.showSourceCode的值改为 1。默认值为0，报表上不显示获取源代码功能项。

2. 在报表上开启获取源代码功能。

3. 重启应用。

用户可在事务/服务接口/后台任务追踪页面的调用栈中，查看某个类的源代码。

组件钻取

填写第三方跳转链接地址，${ip}用来匹配您的跳转组件或者实例ip地址，${port}为端口，${type}用来匹配跳转过去的类型。${type}匹配的值为非必填，${ip}为必填，${port}为必填，${type}根据跳转时模块不同可分为APP、MySQL、Oracle、Redis、JMS等。

追踪选项

• 慢事务阈值：当请求的响应时间大于阈值时，会被应用与微服务标记为慢事务。事务追踪条目前会显示图标。

  

• 事务追踪明细：默认情况下，应用探针对业务系统中请求的所有事务保留各种跟踪记录数据，例如代码的调用堆栈和执行时间、HTTP请求参数、查询慢的SQL语句等等。开启该选项后，默认配置值为10ms，当事务响应时间大于等于10ms时，事务的追踪明细数据会被保留；响应时间小于10ms的事务请求调用栈详情会被丢弃，单次追踪拓扑、组件调用会受影响，请求参数、数据项不受影响，体现在非慢事务追踪详情页面中，只有参数信息和数据项会有数据。目前仅支持Agent Collector V3.6.1以上版本。该功能默认为关闭状态，当开启时，配置的值必须小于等于上方的慢事务阈值。

  

• 慢方法堆栈：对于事务涉及的方法、SQL语句、NoSQL操作、自定义方法，当执行时间大于阈值时才记录方法的堆栈、慢SQL详情和慢NoSQL操作详情。默认开启。

• 混淆SQL：指对跟踪到的SQL语句中的数字和字符串值进行混淆操作，以问号“?”替换。默认开启。仅对慢 SQL 追踪和请求追踪生效。

• 采集请求参数：采集HTTP的请求头和请求参数。默认开启。

• 忽略的参数列表：如果不想采集个别敏感的参数，可以进行设置，多个参数以英文逗号进行分隔。

错误及异常

• 采集错误和异常：开启时，应用探针将采集各业务系统中所有应用的错误和异常信息。默认为开启状态。

• 捕捉异常堆栈：启用后，事务追踪中的异常信息将包含堆栈信息。默认为关闭状态。

• 选择语言类型：目前支持Java、.NET和.NET Core三种语言。不同语言显示的配置项不同。

• 采集日志异常：勾选Log4j或Logback复选框后，可采集和统计日志组件输出的error及以上级别日志中的异常信息，例如应用输出了日志log.error("message","IOException")，那么IOException将会被采集。.NET和.NET Core还支持System日志组件。当勾选日志组件的复选框后，就可以勾选日志级别高于‘error’的’message‘和设置事务状态为错误复选框了。

  • 日志级别高于‘error’的’message‘：默认情况下，对于error及以上级别的日志，如果日志中只有message，而没有异常信息，是不会被统计为异常的。勾选该复选框后，上述日志也会被统计为异常。
  • 设置事务状态为错误：勾选后，error及以上级别的日志所对应的事务会被视为错误，否则只被视为异常。Logback只有error级别的日志。

• 根据Logged Message忽略：符合日志信息匹配规则的日志异常不会被视为异常或错误。单击添加按钮，选择信息匹配方式，输入异常信息，该处不支持正则表达式。规则可被编辑和删除。

• 根据异常类忽略：您可将不想计入错误和异常的异常类加入列表，后续统计错误时这些类将被忽略。单击添加按钮，输入包含包名的完整异常类名。可勾选Exception Message 过滤复选框，通过exception.getMessage() 打印出的异常信息忽略异常，如果匹配成功，则该Exception不会被认为是Exception。选择信息匹配方式，输入异常信息，该处不支持正则表达式。规则可被编辑和删除。

• 自定义HTTP状态码：默认情况下，基调听云会将 Status Code 400 ~ 505 的事务状态设置为错误。但是业务上的错误可能并不符合这个规则，如：900 在金融场景下可能代表“余额不足”，需要被作为事务错误，而401被认为是正常的事务请求。通过自定义HTTP状态码，可分别设置错误状态码和正常状态码来标识事务是否正常，以符合上述2种场景的需要。“错误状态码”类型的自定义HTTP Status code的名称在错误分析中会作为错误类型显示，格式为: HTTP Error Code: ${名称}。状态码规则可被编辑、删除和批量删除。

  说明：

  • 该选项必须在采集错误和异常选项开启的情况下才生效。
  • 当某个状态码同时被设置成了错误状态码和正常状态码时，基调听云将会根据配置项的优先级判定最终是错误状态码还是正常状态码，排列越靠上的优先级越高。

• 自定义业务错误：业务错误指业务上的一些非正常结果，通过对数据项的值进行规则定义，来识别业务错误。当满足业务错误的规则时，事务的状态会被设置为错误，错误的名称为自定义业务错误的描述。业务错误在错误模块中可以独立分析其趋势、堆栈、调用者、调用栈及请求上下文。单击添加按钮，输入业务错误描述，选择数据项（支持创建新的数据项），对值设置匹配规则后，单击确认。匹配规则最多可添加3条。自定义业务错误可被编辑、删除和批量删除。

• 自定义Redirect Pages：当用户在操作应用的过程中，经常遇到操作失败后跳转到一个错误提示页面的情况。您可以对应用中发生错误后重定向到的错误页面进行定义，当匹配成功后，操作对应的这个事务的状态会被设置为错误。单击添加按钮，输入名称，设置匹配条件和重定向页面的URL，单击确认。自定义Redirect Pages可被编辑、删除和批量删除。

探针熔断

Java Agent在运行过程中会消耗应用进程的资源，包括CPU和内存，当应用进程资源紧张时，为了应用进程稳定运行，Java Agent将触发熔断机制，关闭部分数据采集以减少对进程资源的消耗。

相关名词解释如下：

• Heap内存：JVM堆内存。

• Garbage Collection：JVM垃圾回收机制。

• Garbage Collection CPU时间占比：Garbage Collection消耗的CPU时间/CPU总时间。

触发探针熔断有两种情况：

1、当Heap内存使用率超过配置值时（默认值：70%）或者Garbage Collection CPU时间占比超过配置值时（默认值：10%），将对数据采集进行采样（默认值：50%）。

2、当Heap内存使用率超过配置值时（默认值：80%）或者Garbage Collection CPU时间占比超过配置值时（默认值：20%），将禁用数据采集，但仍保留探针心跳。

当应用进程的资源恢复后，恢复数据采集。