Skywalking集成

配置说明

属性键	描述	默认
`agent.namespace`	命名空间在跨进程传播中隔离头。HEADER 名称将为`HeaderName:Namespace`.	没有设置
`agent.service_name`	表示提供相同功能/逻辑的逻辑组的服务名称。建议：为每个逻辑服务组设置一个唯一的名称，服务实例节点共享相同的代码，最大长度为 50（UTF-8 字符）。可选，一旦`service_name`遵循`<group name>::<logic name>`格式，OAP 服务器将组名分配给服务元数据。	`Your_ApplicationName`
`agent.sample_n_per_3_secs`	负或零表示关闭，默认情况下。SAMPLE_N_PER_3_SECS 表示在 3 秒内采样 N TraceSegment。	没有设置
`agent.authentication`	Authentication active 是基于后端设置的，更多细节参见application.yml。对于大多数场景，这需要后端扩展，默认实现中只提供基本匹配身份验证。	没有设置
`agent.trace_segment_ref_limit_per_span`	单个跨度中 TraceSegmentRef 的最大数量，以保持内存成本可估计。	500
`agent.span_limit_per_segment`	单个段中的最大跨度数。通过此配置项，SkyWalking 可以估算您的应用程序内存成本。	300
`agent.ignore_suffix`	如果该集合中包含第一个跨度的操作名称，则应忽略该段。	没有设置
`agent.is_open_debugging_class`	如果为 true，skywalking 代理会将所有检测的类文件保存在`/debugging`文件夹中。SkyWalking 团队可能会要求提供这些文件以解决兼容问题。	没有设置
`agent.is_cache_enhanced_class`	如果为 true，SkyWalking 代理会将所有检测的类文件缓存到内存或磁盘文件（由类缓存模式决定），允许另一个 java 代理增强那些由 SkyWalking 代理增强的类。要使用一些 Java 诊断工具（如 BTrace、Arthas）来诊断应用程序或添加自定义 Java 代理以增强类，您需要启用此功能。	`false`
`agent.class_cache_mode`	检测类缓存模式：`MEMORY`或`FILE`. `MEMORY`: 将类字节缓存到内存中，如果检测的类过多或过大，可能会占用更多内存。`FILE`: 在`/class-cache`文件夹中缓存类字节，在应用程序退出时自动清理缓存的类文件。	`MEMORY`
`agent.instance_name`	实例名是一个实例的标识，在服务中应该是唯一的。如果为空，SkyWalking 代理将生成 32 位 uuid。默认情况下，使用`UUID`@`hostname`作为实例名称。最大长度为 50（UTF-8 字符）	`""`
`agent.instance_properties[key]=value`	添加服务实例自定义属性。	没有设置
`agent.cause_exception_depth`	代理的深度，何时记录都会导致异常。	`5`
`agent.force_reconnection_period`	基于 grpc_channel_check_interval 强制重新连接 grpc 的周期。	`1`
`agent.operation_name_threshold`	operationName 最大长度，不建议将此值设置为 > 190。	`150`
`agent.keep_tracing`	如果此值为，即使后端不可用，也要继续跟踪`true`。	`false`
`agent.force_tls`	如果此值为，则强制为 gRPC 通道打开 TLS `true`。	`false`
`agent.ssl_trusted_ca_path`	gRPC SSL 可信 ca 文件。	`/ca/ca.crt`
`agent.ssl_key_path`	私钥文件。当 ssl_key_path 和 ssl_cert_chain_path 存在时启用 mTLS。	`""`
`agent.ssl_cert_chain_path`	证书文件。当 ssl_key_path 和 ssl_cert_chain_path 存在时启用 mTLS。	`""`
`osinfo.ipv4_list_size`	限制 ipv4 列表大小的长度。	`10`
`collector.grpc_channel_check_interval`	grpc 通道状态检查间隔。	`30`
`collector.heartbeat_period`	代理心跳报告期。单位，第二。	`30`
`collector.properties_report_period_factor`	所述代理将实例属性到后端每`collector.heartbeat_period * collector.properties_report_period_factor`秒	`10`
`collector.backend_service`	收集器 SkyWalking 跟踪接收器服务地址。	`127.0.0.1:11800`
`collector.grpc_upstream_timeout`	grpc 客户端将数据发送到上游时会超时多长时间。单位是第二。	`30` 秒
`collector.get_profile_task_interval`	嗅探器获取配置文件任务列表间隔。	`20`
`collector.get_agent_dynamic_config_interval`	嗅探器获取代理动态配置间隔	`20`
`collector.is_resolve_dns_periodically`	如果为 true，skywalking 代理将启用定期解析 DNS 以更新接收器服务地址。	`false`
`logging.level`	日志级别：跟踪、调试、信息、警告、错误、关闭。默认为信息。	`INFO`
`logging.file_name`	日志文件名。	`skywalking-api.log`
`logging.output`	日志输出。默认为文件。使用 CONSOLE 意味着输出到标准输出。	`FILE`
`logging.dir`	日志文件目录。默认为空字符串，表示使用“{theSkywalkingAgentJarDir}/logs”输出日志。{theSkywalkingAgentJarDir}为skywalking代理jar文件所在目录	`""`
`logging.resolver`	记录器解析器：`PATTERN`或`JSON`. 默认为`PATTERN`，`logging.pattern`用于打印传统的文本日志。`JSON`解析器以 JSON 格式打印日志。	`PATTERN`
`logging.pattern`	日志格式。有所有转换说明符： `%level`表示日志级别。 `%timestamp`表示现在的时间格式`yyyy-MM-dd HH:mm:ss:SSS`。 * `%thread`表示当前线程的名称。 * `%msg`表示用户登录的一些消息。 * `%class`表示 TargetClass 的 SimpleName。 * `%throwable`表示用户调用的 throwable。 * `%agent_name`表示`agent.service_name`. 仅适用于`PatternLogger`.	`%level %timestamp %thread %class : %msg %throwable`
`logging.max_file_size`	日志文件的最大大小。如果大小大于此，则归档当前文件，并写入新文件。	`300 * 1024 * 1024`
`logging.max_history_files`	最大历史日志文件。当发生翻转时，如果日志文件超过这个数量，那么最旧的文件将被删除。默认情况下，负数或零表示关闭。	`-1`
`statuscheck.ignored_exceptions`	列出的异常不会被视为错误。因为在某些代码中，异常被用作控制业务流程的一种方式。	`""`
`statuscheck.max_recursive_depth`	检查代理跟踪的异常时的最大递归深度。通常，我们不建议将此值设置为超过 10，这可能会导致性能问题。负值和 0 将被忽略，这意味着所有异常都会使跨度标记为错误状态。	`1`
`correlation.element_max_number`	关联上下文中的最大元素数。	3
`correlation.value_max_length`	每个元素的最大值长度。	`128`
`correlation.auto_tag_keys`	当此处列出的键存在时，通过关联上下文中的键/值标记跨度。	`""`
`jvm.buffer_size`	收集的 JVM 信息的缓冲区大小。	`60 * 10`
`buffer.channel_size`	缓冲区通道大小。	`5`
`buffer.buffer_size`	缓冲区大小。	`300`
`profile.active`	如果为 true，skywalking 代理将在用户创建新的配置文件任务时启用配置文件。否则禁用配置文件。	`true`
`profile.max_parallel`	并行监视器段数	`5`
`profile.duration`	最大监控段时间（分钟），如果当前段监控时间超出限制，则停止。	`10`
`profile.dump_max_stack_depth`	最大转储线程堆栈深度	`500`
`profile.snapshot_transport_buffer_size`	快照传输到后端缓冲区大小	`50`
`meter.active`	如果为 true，代理会收集指标并将其报告给后端。	`true`
`meter.report_interval`	报告仪表间隔。单位为秒	`20`
`meter.max_meter_size`	仪表池的最大大小	`500`
`log.max_message_size`	发送到服务器的消息的最大大小。默认为 10 MB。	`10485760`
`plugin.mount`	挂载插件的特定文件夹。已安装文件夹中的插件将起作用。	`plugins,activations`
`plugin.peer_max_length`	对等最大描述限制。	`200`
`plugin.exclude_plugins`	排除插件目录中定义的一些插件。插件名称在代理插件列表中定义	`""`
`plugin.mongodb.trace_param`	如果为true，则跟踪MongoDB访问中的所有参数，默认为false。只跟踪操作，不包括参数。	`false`
`plugin.mongodb.filter_length_limit`	如果设置为正数，`WriteRequest.params`将被截断到这个长度，否则会被完全保存，这可能会导致性能问题。	`256`
`plugin.elasticsearch.trace_dsl`	如果为 true，则跟踪 ElasticSearch 访问中的所有 DSL（Domain Specific Language），默认为 false。	`false`
`plugin.springmvc.use_qualified_name_as_endpoint_name`	如果为 true，则完全限定的方法名称将用作端点名称而不是请求 URL，默认值为 false。	`false`
`plugin.toolit.use_qualified_name_as_operation_name`	如果为 true，则完全限定的方法名称将用作操作名称而不是给定的操作名称，默认为 false。	`false`
`plugin.jdbc.trace_sql_parameters`	如果设置为 true，`java.sql.PreparedStatement`则将收集sql 的参数（通常为）。	`false`
`plugin.jdbc.sql_parameters_max_length`	如果设置为正数，`db.sql.parameters`将被截断到这个长度，否则会被完全保存，这可能会导致性能问题。	`512`
`plugin.jdbc.sql_body_max_length`	如果设置为正数，`db.statement`将被截断到这个长度，否则会被完全保存，这可能会导致性能问题。	`2048`
`plugin.solrj.trace_statement`	如果为 true，则跟踪 Solr 查询请求中的所有查询参数（包括 deleteByIds 和 deleteByQuery），默认为 false。	`false`
`plugin.solrj.trace_ops_params`	如果为 true，则跟踪 Solr 请求中的所有操作参数，默认为 false。	`false`
`plugin.light4j.trace_handler_chain`	如果为 true，则跟踪作为请求的 Light4J 处理程序链一部分的所有中间件/业务处理程序。	错误的
`plugin.springtransaction.simplify_transaction_definition_name`	如果为 true，则事务定义名称将被简化。	错误的
`plugin.jdkthreading.threading_class_prefixes`	线程类（`java.lang.Runnable`和`java.util.concurrent.Callable`）和它们的子类，包括匿名内部类，它们的名称相匹配的任何一个`THREADING_CLASS_PREFIXES`（由分裂`,`）将被仪器，确保只有窄前缀指定为你期待什么样的仪器，（`java.`和`javax.`将被忽略由于安全问题）	没有设置
`plugin.tomcat.collect_http_params`	该配置项控制Tomcat插件是否应该收集请求的参数。此外，在分析跟踪中隐式激活。	`false`
`plugin.springmvc.collect_http_params`	这个配置项控制SpringMVC插件是否应该收集请求的参数，当你的Spring应用基于Tomcat时，只考虑设置`plugin.tomcat.collect_http_params`或`plugin.springmvc.collect_http_params`。此外，在分析跟踪中隐式激活。	`false`
`plugin.httpclient.collect_http_params`	这个配置项控制HttpClient插件是否应该收集请求的参数	`false`
`plugin.http.http_params_length_threshold`	当`COLLECT_HTTP_PARAMS`启用时，有多少个字符，以保持并传送到后端OAP，使用负值，以保持和发送完整的参数，NB。添加此配置项是为了性能。	`1024`
`plugin.http.http_headers_length_threshold`	当`include_http_headers`声明的标题名称，该阈值控制所有标头值的长度的限制。使用负值来保存和发送完整的标头。笔记。添加此配置项是为了性能。	`2048`
`plugin.http.include_http_headers`	设置标题名称，应由插件收集。标题名称必须遵循`javax.servlet.http`定义。多个名称应以逗号分隔。	``(不会收集标题) \|
`plugin.feign.collect_request_body`	此配置项控制 Feign 插件是否应收集请求的 http 正文。	`false`
`plugin.feign.filter_length_limit`	当`COLLECT_REQUEST_BODY`启用时，有多少个字符，以保持并传送到后端OAP，使用负值，以保持和发送完整的身体。	`1024`
`plugin.feign.supported_content_types_prefix`	当`COLLECT_REQUEST_BODY`启用并且内容类型以 SUPPORTED_CONTENT_TYPES_PREFIX 开头时，收集请求的正文，多个路径应以`,`	`application/json,text/`
`plugin.influxdb.trace_influxql`	如果为 true，则跟踪 InfluxDB 访问中的所有 influxql（查询和写入），默认为 true。	`true`
`plugin.dubbo.collect_consumer_arguments`	Apache Dubbo 消费者`arguments`在 RPC 调用`Object#toString`中收集，用于收集`arguments`.	`false`
`plugin.dubbo.consumer_arguments_length_threshold`	当`plugin.dubbo.collect_consumer_arguments`是时`true`，从前端到 OAP 后端的长度参数	`256`
`plugin.dubbo.collect_provider_arguments`	Apache Dubbo 提供程序`arguments`在 RPC 调用`Object#toString`中收集，用于收集`arguments`.	`false`
`plugin.dubbo.provider_arguments_length_threshold`	当`plugin.dubbo.collect_provider_arguments`是时`true`，从前端到 OAP 后端的长度参数	`256`
`plugin.kafka.bootstrap_servers`	用于建立与 Kafka 集群的初始连接的主机/端口对列表。	`localhost:9092`
`plugin.kafka.get_topic_timeout`	从Kafka服务器读取topic的超时时间，单位为秒。	`10`
`plugin.kafka.producer_config`	Kafka生产者配置。阅读生产者配置以获取更多详细信息。查看Kafka 报告文档以获取更多详细信息和示例。
`plugin.kafka.producer_config_json`	以 JSON 格式配置 Kafka Producer 配置。请注意`plugin.kafka.producer_config[key]`，如果密钥重复，它将被 , 覆盖。
`plugin.kafka.topic_meter`	指定仪表系统数据要报告给哪个 Kafka 主题名称。	`skywalking-meters`
`plugin.kafka.topic_metrics`	指定要向其报告 JVM 指标数据的 Kafka 主题名称。	`skywalking-metrics`
`plugin.kafka.topic_segment`	指定要向其报告的跟踪数据的 Kafka 主题名称。	`skywalking-segments`
`plugin.kafka.topic_profiling`	指定要向其报告的线程分析快照的 Kafka 主题名称。	`skywalking-profilings`
`plugin.kafka.topic_management`	指定服务实例的注册数据或心跳数据上报到哪个Kafka主题名。	`skywalking-managements`
`plugin.kafka.topic_logging`	指定要向其报告的日志数据的 Kafka 主题名称。	`skywalking-logging`
`plugin.kafka.namespace`	使用相同的 Kafka 集群时隔离多个 OAP 服务器（最终主题名称将在 Kafka 主题之前附加命名空间`-`）。	`` \|
`plugin.springannotation.classname_match_regex`	将 spring beans 与类名的正则表达式匹配。多个表达式可以用逗号分隔。这仅在`Spring annotation plugin`已激活时有效。	`All the spring beans tagged with @Bean,@Service,@Dao, or @Repository.`
`plugin.toolkit.log.transmit_formatted`	是否以格式化或未格式化的形式传输记录数据。	`true`
`plugin.lettuce.trace_redis_parameters`	如果设置为true，Redis 命令的参数将由Lettuce 代理收集。	`false`
`plugin.lettuce.redis_parameter_max_length`	如果设置为正数并`plugin.lettuce.trace_redis_parameters`设置为`true`，Redis 命令参数将被收集并截断到此长度。	`128`
`plugin.neo4j.trace_cypher_parameters`	如果设置为true，将收集密码的参数。	`false`
`plugin.neo4j.cypher_parameters_max_length`	如果设置为正数，`db.cypher.parameters`将被截断到这个长度，否则会被完全保存，这可能会导致性能问题。	`512`
`plugin.neo4j.cypher_body_max_length`	如果设置为正数，`db.statement`将被截断到这个长度，否则会被完全保存，这可能会导致性能问题。	`2048`

关键参数

属性名	描述	设置值
agent.namespace	SkyWalking是一个监控工具，会从分布式系统中收集度量值。在真实世界中，大型分布式系统包含了成百上千的服务和服务实例。在这种情况下，很有可能不止一个小组，甚至不止一个公司在维护和监控分布式系统。每个小组或公司掌管着不同的部分，他们不希望也不应该共享他们的度量值。命名空间正是基于以上背景提出的，用于追踪监控系统的隔离	Skywalking的默认header的key是sw6，当设置agent.namespace之后，header的key变为设置的namespace+“sw6”。例如namespace为test，则header的key为test-sw6。
agent.service_name	${服务名称} = [$ {组名称}::]${逻辑名称}	APP_ID
agent.sample_n_per_3_secs	负数或0表示不采样，默认不采样。SAMPLE_N_PER_3_SECS表示每3秒采样30条。	30
logging.level	日志级别	`info`
logging.max_file_size	日志文件的最大大小。当日志文件大小超过这个数，归档当前的日志文件，将日志写入到新文件	104857600（100M）
logging.max_history_files	最大历史记录日志文件。发生翻转时，如果日志文件超过此数目，则最早的文件将被删除。	2

集成方式

-javaagent:/usr/local/agents/skywalking/skywalking-agent.jar -DSW_AGENT_NAME=td-ba-coding-devops-guide-prod -DSW_AGENT_COLLECTOR_BACKEND_SERVICES=skywalking-oap.teddymobile.net:11800

关键参数

属性名	描述	设置值
`SW_AGENT_NAME`	指定微服务实例名称，用于展示在SkyWalking的web监控界面	`td-xx-xx-prod`
`SW_AGENT_COLLECTOR_BACKEND_SERVICE`	skywalking后端接收服务	`skywalking-oapa.teddymobile.net:11800`

其中，-javaagent参数指定skywalking-agent.jar的全路径

Toolkit

toolkit-trace

依赖工具包，比如使用maven或者gradle

   <dependency>
      <groupId>org.apache.skywalking</groupId>
      <artifactId>apm-toolkit-trace</artifactId>
      <version>${skywalking.version}</version>
   </dependency>

通过TraceContext.traceId()API获取traceId。

import TraceContext;
...

modelAndView.addObject("traceId", TraceContext.traceId());

使用TraceContext.segmentId()API 获取segmentId。

import TraceContext;
...

modelAndView.addObject("segmentId", TraceContext.segmentId());

使用TraceContext.spanId()API 获取spanId。

import TraceContext;
...

modelAndView.addObject("spanId", TraceContext.spanId());

仅示例代码

添加@Trace到您要跟踪的任何方法。之后，您可以在堆栈中看到跨度。
带有注释的方法@Tag将尝试使用给定的键 ( ) 和 ( )标记当前活动跨度，如果根本没有活动跨度，则此注释无效。可以重复，并且可以与一起使用，请参见下面的示例。该的是一样的东西在支持自定义增强跟踪。Tag#key()``Tag#value()``@Tag``@Trace``value``Tag
在跟踪方法的上下文中添加自定义标记，ActiveSpan.tag("key", "val").
ActiveSpan.error() 将当前跨度标记为错误状态。
ActiveSpan.error(String errorMsg) 使用消息将当前跨度标记为错误状态。
ActiveSpan.error(Throwable throwable) 使用 Throwable 将当前跨度标记为错误状态。
ActiveSpan.debug(String debugMsg) 在当前跨度中添加调试级别日志消息。
ActiveSpan.info(String infoMsg) 在当前跨度中添加信息级别日志消息。
ActiveSpan.setOperationName(String operationName) 自定义操作名称。

ActiveSpan.tag("my_tag", "my_value");
ActiveSpan.error();
ActiveSpan.error("Test-Error-Reason");

ActiveSpan.error(new RuntimeException("Test-Error-Throwable"));
ActiveSpan.info("Test-Info-Msg");
ActiveSpan.debug("Test-debug-Msg");

/**
 * The codes below will generate a span,
 * and two types of tags, 
      one type tag: keys are `tag1` and `tag2`, values are the passed-in parameters, respectively, 
      the other type tag: keys are `username`  and `age`, values are the return value in User, respectively
 */
@Trace
@Tag(key = "tag1", value = "arg[0]")
@Tag(key = "tag2", value = "arg[1]")
@Tag(key = "username", value = "returnedObj.username")
@Tag(key = "age", value = "returnedObj.age")
public User methodYouWantToTrace(String param1, String param2) {
    // ActiveSpan.setOperationName("Customize your own operation name, if this is an entry span, this would be an endpoint name");
    // ...
}

使用TraceContext.putCorrelation()API 将自定义数据放入跟踪上下文中。

Optional<String> previous = TraceContext.putCorrelation("customKey", "customValue");

当值为null或为空时，CorrelationContext 将删除该项目。

使用TraceContext.getCorrelation()API 获取自定义数据。

Optional<String> value = TraceContext.getCorrelation("customKey");

CorrelationContext 配置描述可以在代理配置文档中找到，correlation.前缀为。

跨线程追踪

用法 1.

    @TraceCrossThread
    public static class MyCallable<String> implements Callable<String> {
        @Override
        public String call() throws Exception {
            return null;
        }
    }
...
    ExecutorService executorService = Executors.newFixedThreadPool(1);
    executorService.submit(new MyCallable());

用法 2.

    ExecutorService executorService = Executors.newFixedThreadPool(1);
    executorService.submit(CallableWrapper.of(new Callable<String>() {
        @Override public String call() throws Exception {
            return null;
        }
    }));

或者

    ExecutorService executorService = Executors.newFixedThreadPool(1);
    executorService.execute(RunnableWrapper.of(new Runnable() {
        @Override public void run() {
            //your code
        }
    }));

用法 3.

    @TraceCrossThread
    public class MySupplier<String> implements Supplier<String> {
        @Override
        public String get() {
            return null;
        }
    }
...
    CompletableFuture.supplyAsync(new MySupplier<String>());

或者

    CompletableFuture.supplyAsync(SupplierWrapper.of(()->{
            return "SupplierWrapper";
    })).thenAccept(System.out::println);

toolkit-logback

依赖工具包，比如使用maven或者gradle

    <dependency>
         <groupId>org.apache.skywalking</groupId>
         <artifactId>apm-toolkit-logback-1.x</artifactId>
         <version>{project.release.version}</version>
     </dependency>

在日志中打印跟踪 ID

设置%tid在Patternlogback.xml的部分

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} -%msg%n</Pattern>
            </layout>
        </encoder>
    </appender>

使用 MDC，%X{tid}在Patternlogback.xml 的部分中设置

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} -%msg%n</Pattern>
            </layout>
        </encoder>
    </appender>

支持 logback AsyncAppender（MDC 也支持），无需额外配置。参考下面logback.xml的demo。详情：Logback AsyncAppender

    <configuration scan="true" scanPeriod=" 5 seconds">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
                <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
                    <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} -%msg%n</Pattern>
                </layout>
            </encoder>
        </appender>
    
        <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
            <discardingThreshold>0</discardingThreshold>
            <queueSize>1024</queueSize>
            <neverBlock>true</neverBlock>
            <appender-ref ref="STDOUT"/>
        </appender>
    
        <root level="INFO">
            <appender-ref ref="ASYNC"/>
        </root>
    </configuration>

当您使用-javaagent激活 SkyWalking 跟踪器时，如果存在，logback 将输出traceId。如果跟踪器处于非活动状态，则输出将为TID: N/A。