Java应用自定义配置

前提条件

已为应用安装探针，具体操作，请参见应用监控接入概述。

功能入口

1. 登录ARMS控制台，在左侧导航栏选择应用监控 > 应用列表。

2. 在应用列表页面顶部选择目标地域，然后单击目标应用名称。

说明

语言列的图标含义如下：

：接入应用监控的Java应用。

：接入应用监控的Golang应用。

：接入应用监控的Python应用。

-：接入可观测链路 OpenTelemetry 版的应用。

3. 在上方导航栏选择应用配置 > 自定义配置。

4. 设置自定义配置参数，设置完成后，单击保存。

采样设置

在采样设置区域，可以为调用链设置采样策略和采样接口名称。更多信息，请参见调用链采样模式选择（3.2.8及以上探针版本）。

探针开关设置

在探针开关设置区域，可以控制应用监控的启停并调整各插件开关。

线程分析设置

在线程分析设置区域，可以打开或关闭线程分析总控开关、定期保存本地方法栈信息开关，并设置高耗时调用阈值。

应用日志关联配置

在应用日志关联配置区域，可以设置应用关联的日志源信息，自动填充TraceId、SpanId。更多信息，请参见日志分析。

• 自动填充TraceId、SpanId配置作用：开启后，无需手动修改日志配置文件即可往日志中自动注入Trace ID、Span ID。

  配置效果：

  如下图所示，在未修改日志配置文件情况下，log4j、log4j2、logback均自动在日志中打印了Trace ID和Span ID。

  

• 支持日志MDC中添加traceId：4.x探针中默认不再支持通过org.slf4j.MDC.get(“EagleEye-TraceID”)方式获取TraceId，如果仍需通过该方式获取，可以打开当前开关。

URL收敛设置

在URL收敛设置区域，可以打开或关闭收敛功能的开关，并设置收敛阈值、收敛规则。URL收敛是指将具有相似性的一系列URL作为一个单独的个体展示，例如将前半部分都为/service/demo/的一系列URL集中展示。收敛阈值是指要进行URL收敛的最低数量条件，例如当阈值为100时，则符合规则正则表达式的URL数量达到100才会对它们进行收敛。更多信息，请参见ARMS收敛机制说明。

Arthas监控

在Arthas监控区域，可以打开或关闭Arthas诊断功能，并设置生效IP。更多信息，请参见Arthas诊断。

持续剖析设置

在持续剖析设置区域，可以打开或关闭总开关、CPU热点、内存热点、代码热点功能，并设置生效IP或网段。更多信息，请参见Java应用持续剖析。

信息脱敏设置

在信息脱敏设置区域，通过设置脱敏规则，探针将对JVM系统参数、K8s Yaml、方法入参、Arthas环境变量和系统变量等内容在采集时进行脱敏处理。脱敏规则中各元素通过英文半角逗号分隔，每一个元素代表一个不区分大小写的正则表达式，以password为例，脱敏规则等同于正则表达式.*password.*。

探针在采集数据时会对数据的key按照对应的表达式进行过滤，如果满足条件，该key会被认为包含敏感数据进行脱敏处理。如下图所示，当脱敏规则为licenseKey时，其对-Darms.licenseKey为key的信息进行了脱敏处理。

接口调用配置

在接口调用配置区域，可以设置慢调用阈值、异常白名单、HTTP状态码白名单、无效接口调用过滤等策略。

• 慢调用阈值：默认为500，当接口响应时间大于该阈值的时候，该接口会被标记为慢调用。

• HTTP状态码白名单：

  默认情况下，HTTP 状态码大于 400 会被归类为错误调用。如果您不希望某类状态码被归类为错误，可以设置白名单来忽略这类错误。

  仅对应用监控当前支持的 HTTP 框架产生影响。

  影响数据：HTTP 服务端/客户端的错误数指标（arms_http_requests_error_count、arms_http_client_requests_error_count、arms_app_requests_error_count）、Span 状态。

  影响功能：应用概览、提供服务、依赖服务页签中的错误数，调用链分析页面的 Span 状态、错误数告警。

  内容格式：填写单一状态码，多个状态码用英文半角逗号（,）分隔，不支持模糊匹配。

  示例：403,502

  默认值：空

• 无效接口调用过滤：

  如果您不希望在提供服务页签看到这类调用，可以输入不需要查看调用情况的接口名，探针将不会上报相关接口产生的观测数据，从而将其从接口调用页面隐去。

  说明

  • 对于4.2.0以下版本Java 探针，该功能仅会对提供服务中出现的接口有效。

  • 对于4.2.0及以上版本Java 探针，该功能会对任意一个 LocalRootSpan 生效。

  影响数据：接口对应的所有指标、Span 都会被忽略。

  影响功能：应用概览、提供服务、依赖服务页签对应接口的所有指标，调用链分析页面的 Span 数量、对应接口的调用量、错误数、慢调用告警。

  内容格式：使用字符串或 AntPath 表达式匹配无效接口全名，多个规则请使用英文半角逗号（,）分隔。（默认值的 AntPath 表达式写法是为了兼容存量数据，不建议删除，新增配置请拼接在原有规则之后）。

  示例：/api/test/*,/api/playground/create

  默认值：/**/*.jpg,/**/*.png,/**/*.js,/**/*.jpeg,/**/*.pdf,/**/*.xlsx,/**/*.txt,/**/*.docs,/**/*.gif,/**/*.csv

• 接口调用指标是否记录上游接口名和接口调用指标是否记录上游应用名：

  配置作用：控制接口指标中是否记录调用该接口的上游应用和上游接口，主要影响提供服务中的链路上下游是否有数据。当应用的上游应用较多时，记录该信息可能导致指标上报量剧增，增加费用。

  配置效果：如图所示，关闭了接口指标记录上游应用和接口，可以看到相应的数据降为0。

  

• 接口调用指标是否记录原始状态码：

  配置作用：在HTTP接口相关指标中记录原始的响应码。

  配置效果：

  

数据库调用配置

在数据库调用配置区域，可以设置慢SQL阈值、采集SQL最大保留长度，并设置是否展示SQL中的变量绑定值以及常量值，是否记录MySQL查询返回值大小。

• 展示SQL中的变量绑定值：捕获PrepareStatement参数绑定的变量值，无需重启应用即可生效。

  记录PrepareStatement参数绑定的变量值，该值会存储在对应的数据库访问Span的Attribute中，Key为db.bindvalue，Value为逗号分隔的多个变量值，无需重启应用即可生效。

  • 当前ARMS支持的所有JDBC类框架均支持该设置。

  • 支持该设置的数据库变量类型：Boolean、Byte、Short、Int、Long、Float、Double、BigDecimal、Date。

  • 打开该开关会造成额外的开销，和SQL语句中变量的个数正相关，官方压测场景下（一个变量）打开该开关CPU额外开销0.5%以下，内存额外开销可忽略不计。

  打开开关实际效果如下图所示：

  

• 展示SQL中的常量值：仅对SQL截断，不做额外处理，无需重启应用即可生效。当不同SQL语句包含的常量取值不同时，可能导致SQL语句较为发散而被统一收敛为{ARMS_OTHERS}，不建议开启。

Trace上下文传播协议设置

在Trace上下文传播协议设置区域，您可以根据自己的需求选择使用的Trace上下文传播协议。

默认情况下，ARMS探针会根据一次请求的Header中是否包含指定协议头来选择对应的Trace上下文传播协议。更多信息，请参见ARMS Trace上下文传播协议选择策略。

您可以在该页面选择任一协议作为优先协议。选择并保存后，ARMS会优先探测是否存在该协议约定的请求头。例如，按照如下配置，当一次调用到来时，ARMS探针将会改为按照Jaeger、EagleEye、W3C、SkyWalking、Zipkin的顺序依次探测是否存在协议约定上下文。

您也可以选择强制使用某一种协议。例如，按照如下配置，当一次调用到来时，ARMS探针只会探测是否存在Jaeger协议约定的请求头，如果不存在，不会依次检测其他协议，而是重新生成新的Trace上下文。

配置作用：

支持选择优先或者强制使用的Trace上下文传播协议，一般有以下几种使用场景：

• 请求携带多种格式的Trace上下文，默认的解析顺序不满足要求，想要指定优先使用某种协议。比如同时携带W3C和Zipkin的Trace上下文，默认情况下优先解析W3C的Trace上下文，可以通过设置传播协议为Zipkin改为优先解析Zipkin协议。

• 请求携带Trace协议头，但是不想复用该协议头，想要按照另外一种协议生成新的Trace上下文。比如同时携带Zipkin的Trace上下文，默认情况下会解析Zipkin的Trace上下文，可以通过设置传播协议为W3C，并将传播模式改为强制，这样就会忽略Zipkin的Trace上下文，并按照W3C的协议规范生成新的上下文，需要注意，如果此时不将传播模式改为强制，则在优先按照W3C解析上下文失败后，仍然会按照Zipkin协议解析上下文。

配置效果：

配置后，在调用链的每一个LocalRootSpan中会有一个key为trace.protocol.type，value为当前链路trace协议的attribute。

消息队列配置

在消息队列配置区域，您可以自定义消费者信息。

• 自定义RabbitMQ消费者：通过设置自定义消费者的类名或者包含匿名内部消费者的类名，可以看到该消费者的调用链路。多个消费者以英文半角逗号（,）分隔。

• 自定义Kafka消费方法：通过自定义消费方法，可以在通过Kafka原生SDK消费消息的场景下看到链路以及指标数据。

• Kafka发送消息自动透传上下文：发送时自动往Kafka消息中添加若干个Header用于关联发送链路和消费链路。

探针采集配置

在探针采集配置区域，可以设置探针每秒最大链路采集量、最大可处理QPS阈值和探针日志级别。

• 是否采集调用链：控制调用链数据是否上报，默认开启，关闭后，调用链数据不再上报。

• 探针每秒最大链路采集量：探针每秒可上报的Span数量（出于性能考虑，实际生效阈值和用户配置阈值有5%以内偏差），超出部分的Span不会上报。

• 探针最大可处理QPS阈值： 探针每秒可处理的请求数量（出于性能考虑，实际生效阈值和用户配置阈值有5%以内偏差），超出该阈值的请求不会被监控，即不会对超出阈值的请求生成Span或者记录指标，日志关联TraceId功能也不会生效。

• 采集无入口内部调用数据：在ARMS中，应用提供的HTTP服务、RPC服务、应用被触发执行的定时任务和消息消费被认为是入口，在这些入口的业务逻辑中发生的数据库调用、HTTP请求发送等调用则被认为是有入口的内部调用。反之，如果是通过JDK线程池启动的一些定时执行的HTTP调用、数据库调用、NoSQL调用、消息发送、RPC调用等则被认为是无入口内部调用。在4.2.2及之后版本支持一键过滤该类数据，效果如下图所示，在Lettuce框架中会定期自动执行一些命令保证与Redis服务端的连接正常，这类调用就属于无入口内部调用，在如下图所示时间点关闭采集无入口内部调用数据后，相关数据消失。

  

• 探针日志级别：调整探针日志的打印级别，用于问题排查。

异常高级过滤配置

在异常高级过滤配置区域，可以设置异常采集规则。

• 采集插件异常：是否采集插件异常。

• 同类异常堆栈区分深度：默认为2。基于此堆栈深度识别同类型的异常。修改此配置会造成非预期的统计行为，请您谨慎操作。

• 异常过滤白名单：

  如果您不希望在异常分析页签看到这类异常，可以输入不需要统计为异常的异常全限定类名，从而将其从异常分析页面隐去。

  影响数据：异常数指标（arms_exception_requests_count_raw、arms_exception_requests_seconds_raw）、Span 中的异常信息。

  影响功能：异常分析页签对应异常的指标、调用链分析页面 Span 中的异常信息、对应异常的异常数告警。

  内容格式：使用异常全限定类名标识需要过滤的异常，多个异常请使用英文半角逗号（,）分隔。

  示例：java.lang.InterruptedException,java.lang.IndexOutOfBoundsException

  默认值：无

• 异常过滤父类继承：开启后，如果当前采集到异常是异常过滤白名单中配置的异常类的子类，则也会被过滤。

  配置效果：满足过滤条件的异常将不会展示在ARMS控制台。

• 异常message过滤：配置后，指定类型异常的message字段满足配置条件时也会被过滤。

  • 异常名称：指定对哪个异常生效。

  • message条件：异常message的条件、可以是startsWith、endsWith或contains。

  • message关键字：关键字字符串。

  配置效果：满足过滤条件的异常将不会展示在ARMS控制台。

池化监控配置

在池化监控配置区域，可以设置线程池、连接池相关采集规则。

• 线程池、连接池监控：支持Tomcat/Dubbo/HSF等框架的线程池指标监控，需升级探针至最新版本。

• 线程池线程名模式提取策略：该功能默认将线程池中任意一个运行线程的线程名中所有数字字符替换为*，您也可以调整为仅将线程名的结尾字符替换为*。一般在应用中启动了多个Dubbo Provider，且不同Dubbo Provider的监听端口不一致的情况下，如果按照默认策略，则两个Dubbo Provider中的两个线程池因为提取出来的线程名模板相同会被聚合成一个，此时可以通过调整该策略来区分为两个线程池。

  配置效果：以常见的Tomcat线程池为例，默认情况下展示的线程池线程名为http-nio-*-exec-*，调整后线程名为http-nio-9099-exec-*。

  

• 线程池使用场景过滤和线程池线程名模式过滤：按照线程池使用场景和线程池线程名模式过滤不上报某些线程池的监控指标。

  说明

  该配置仅对 4.2.0 及以上版本的Java探针生效。

  • 线程池使用场景：指该线程使用的场景，目前支持Tomcat、Vert.x、Undertow、Dubbo、Jetty、AliyunJavaAgent、default几种，其中AliyunJavaAgent代表探针使用的线程池，default代表未归类的其他线程池。

  • 线程池线程名模式：指该线程池中线程名经过处理得到的线程名模式，例如http-nio-*-exec-*一般是将实际线程中数字部分替换为*后得到线程名。

  影响数据：线程池指标

  影响功能：线程池监控页签、基于线程池监控指标配置的告警。

  内容格式：

  • 线程池使用场景过滤：线程池监控页签展示的使用场景，多个使用场景请使用英文半角逗号（,）分隔。

  • 线程池线程名模式过滤：线程池监控页签展示的线程名模式，多个使用场景请使用英文半角逗号（,）分隔。匹配方式为精确匹配，不支持规则匹配。

  示例：

  • 线程池使用场景过滤：AliyunJavaAgent,Jetty

  • 线程池线程名模式过滤：Catalina-utility-*,DubboServerHandler-*-thread-*

  代表 AliyunJavaAgent 这个场景下所有线程池数据不上报，其他场景下如果线程池模式名为 Catalina-utility-* 则也不上报。

  默认值：无

Span attributes配置

• 记录 OTel Spec 约定attributes：OpenTelemetry Specification中为每一种插件类型约定了其生成Span所应当包含的Attributes项，但ARMS探针出于数据上报量考虑，默认情况下在Span中并不会记录这些Attributes，您可以按照自身需求开启，开启后，各框架会增加的Attributes请参见OpenTelemetry Specification。

  以下示例是一个HTTP Server的Span，其中红框中的Attributes是开启当前开关后新增的Attributes。

  

• Span关联应用标签配置：用于控制当前在控制台应用列表页面为应用绑定的标签会被附在哪些Span上，默认情况下，所有Span都会包含应用标签。出于用量考虑，您可以将应用标签仅附在入口Span上（入口Span一般包括HTTP Server、RPC Server、MQ消费消息、定时任务）。

  配置为附在入口Span后效果如下图所示，例如，应用包含如下一对test1:value1的应用标签。

  

  对于入口Span，可以看到对应标签的Attributes。

  

  对于非入口Span，不包含test1：value的Attributes。

  

高级设置

在高级设置区域，可以设置需过滤的接口、方法堆栈最大长度等。

• 分位数统计：是否开启分位数统计功能。

• 方法堆栈最大保留长度：默认为128条，最大值为400条。

• 调用链压缩：是否将重复调用（例如for循环）简化。

• 请求入参最大展示长度：默认为512字符，支持的最大长度为2048字符。

• 异步透传扫描包名：添加异步透传扫描包实现异步任务监控。异步透传扫描包中的Runnable、Callable和Supplier接口在创建新对象时会自动捕获当前线程调用链的上下文，并在异步线程中执行时使用该调用链上下文，完成串联。

• HTTP返回结果中包含TraceId：仅针对HTTP类型的请求，在Response Header中返回字段为eagleeye-traceid。

将配置复制到其他应用

如果您需要为其他应用同步相同配置，可以将对应配置复制到其他应用上。

全局默认配置

您可以将当前配置保存为全局默认配置，在之后创建新应用时将会默认使用当前配置。

1. 在页面底部单击保存当前应用设置为全局默认配置。

2. 如果弹出当前设置未保存对话框，请单击确定保存本应用配置后，再单击保存当前应用设置为全局默认配置。

3. 在弹出的对话框中单击确认。

常见问题