Java探针安装指引

Java探针

Java探针(FastTracker)是天眼FAST提供的一款基于Java 8 的探针产品,具有高性能、无侵入、易部署的特点。目前提供以下特性:

  • 内置HTTP、数据库、消息队列、缓存等日志采集。
  • 支持自定义日志上报。

探针的安装

安装前的准备

  • 在天眼平台创建产品/应用,获得产品/应用编码(ProductCode/AppCode)。
  • 在应用运行环境部署日志收集器Fluentbit,并获得日志收集器地址(SocketPath)

    安装探针

    安装Java探针步骤:

  • 下载Java探针包fast-tracker-java-v1.0.0.tar.gz,并解压到一个目录下,如/path/fast-tracker/

  • 将存放解压探针包的目录与要安装Java探针的应用代码放在同一台服务器上(能互相访问文件)。

  • 修改探针的主要配置信息,其中产品编码、应用编码、收集器地址等使用从天眼获取的信息。设置探针配置的方式有两种:修改探针配置文件FastTracker.json和设置环境变量,举例如下(更多探针配置项,参见探针的配置项):

    • 修改配置文件/path/fast-tracker/agent/config/FastTracker.json
      {
       "Enable": true,                                              // 开启探针
       "Debug": false,                                              // 开启探针日志
       "ProductCode": "fast-test",                            // 产品编码
       "AppCode": "tracker-test-java",                      // 应用编码
       "EnvCode": "test",                                          // 环境编码
       "ServiceName": {天眼平台},                             // 服务名称
       "SocketPath": "udp://127.0.0.1:5140",              // 收集器地址,
       "ReportMode": 1,                                          // Forward上报模式
       // 设置默认租户编码和用户编码 
       "TenantCode": {默认租户编码},                              // 租户编码
       "UserCode": {默认用户编码},                                // 用户编码
       // 如需要,可以设置动态获取租户编码、用户编码的方式,如下: 
       "TenantCodeReader": {"ReaderType": "RequestHeader", "ReaderKey": "tenant_code"},
       "UserCodeReader": {"ReaderType": "QueryString", "ReaderKey": "user_code"}, 
      }
      
    • 通过环境变量修改:
       FastTracker.Enable=true                       // 开启探针
       FastTracker.Debug=false                       // 开启探针日志
       FastTracker.ProductCode=fast-test                // 产品编码
       FastTracker.AppCode=tracker_java              // 应用编码
       FastTracker.EnvCode=prod                      // 环境编码
       FastTracker.ServiceName=serviceA              // 服务名称
       FastTracker.SocketPath=udp://127.0.0.1:5140   // 收集器地址,
       FastTracker.ReportMode=1                      // Forward上报模式
       // 注入租户、用户
       FastTracker.TenantCode={默认租户编码}              // 租户编码
       FastTracker.UserCode={默认用户编码}                // 租户编码      
       // 如需要,可以设置动态获取租户编码、用户编码的方式,如下: 
       FastTracker.TenantCodeReader.ReaderType=Cookie
       FastTracker.TenantCodeReader.ReaderKey=tenant-code
       FastTracker.UserCodeReader.ReaderType=QueryString
       FastTracker.UserCodeReader.ReaderKey=user-code
      
  • 添加-javaagent:/path/fast-tracker/agent/fast-tracker-agent.jar到JVM参数,并确保将其添加到-jar参数之前,如:

    java -javaagent:fast-tracker-agent.jar -jar app.jar
    
  • 访问应用,探针会随着应用的启动而运行,正常情况在您访问应用后就可以在天眼平台的SERVER模块查看到应用的链路日志。

探针的扩展特性

应用安装接入Java探针就完在了无侵入式的探针接入,即不修改任何代码就可以实现后端链路日志的自动采集上报。但一些特殊场景下应用可能需要上报自定义日志,或在运行时动态修改探针的配置信息,为此探针通过开放API接口的方式对这些场景进行支持。

添加探针SDK启用探针API调用

探针提供的API接口,只需在应用里添加探针SDK就可以在代码里调用。

  • 添加SDK前需先配置Maven(请参见Maven配置
  • 需要使用在目标工程pom文件中加入相关依赖

      <dependency>
          <groupId>cn.com.mypaas.fast</groupId>
          <artifactId>fast-agent-sdk</artifactId>
          <version>${version}</version>
      </dependency>
    
      注:${version} —— 默认填最新的版本号
    

配置实现跨线程链路追踪

要支持自定义线程类CallableRunnable的追踪,需要引入依赖,并添加注解@TraceCrossThread或使用包装类创建线程。(引入依赖需要先配置Maven,参见Maven配置)。

<dependency>
   <groupId>cn.com.mypaas.fast</groupId>
   <artifactId>fast-toolkit-trace</artifactId>
   <version>${version}</version>
</dependency>
探针在跨线程追踪上提供了以下几种方式:
  • 方式1:使用注解@TraceCrossThread

      @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:使用CallableWrapper.of()RunnableWrapper.of()创建线程

      ExecutorService executorService = Executors.newFixedThreadPool(1);
      executorService.submit(CallableWrapper.of(new Callable<String>() {
          @Override public String call() throws Exception {
              return null;
          }
      }));
    
      executorService.execute(RunnableWrapper.of(new Runnable() {
          @Override public void run() {
              //your code
          }
      }));
    

上报自定义日志

应用通过调用探针API可以上报两类自定义日志:一类是组件(Component)字段值为Logging的自定义Logging日志;一类是组件(Component)值支持应用设置的自定义组件日志。

上报自定义Logging日志

上报Logging类日志通过调用FastTracker类的静态方法实现,上报日志的component字段的值为Logging,上报的自定义日志内容被放到日志的Logs字段。Java探针目前提供5个方法分别对应五个级别的自定义日志:

FastTracker.info("普通信息");
FastTracker.debug("普通信息");
FastTracker.warning("警告信息");
FastTracker.error("错误信息");
FastTracker.fatal("致命信息");

上报的自定义Logging日志结构为:

    {
        ...
        "t":2,                                 -- span_type:2 -本地调用
        "y":0,                                 -- span_layer:0 -LOCAL
        "c":"logging"                          -- component:logging
        "o":"logging:<log-level>"              -- operation:logging:log-level
        "l":[                                  -- logs
            {
                "Timestamp":"UTC毫秒时间戳",
                "Data":{
                    "event":"log-level",
                    "message":"日志信息",
                }
            ]

    }
上报自定义Logging日志示例:
  • 调用方法:
    FastTracker.error("错误信息");
    
  • 日志内容:
      {
        ...    
        "t": 2,
        "y": 0,
        "d": 1,
        "c": "logging",
        "o": "logging:error",
        "l": [
          {
            "Timestamp": 1620379792295,
            "Data": {
              "event": "error",
              "message": "错误信息"
            }
          }
        ]
      }
    

上报自定义组件日志

上报日志自定义组件日志通过调用FastTracker类的FastTracker.beginSpan()开启自定义组件日志上报,提供的方法和伪代码如下:

//自定义span
span = FastTracker.beginSpan(operation);   //开启自定义组件类日志上报,operation必填
span.setComponent(name);                   //设置component,默认值CustomEvent
span.setTags(tags);                        //更新tags
span.addTag(key,value);                    //追加一个键值对到tags
span.addLog(message);                      //追加一个object到logs
span.errorOccurred(error);                 //追加一个错误信息object到Logs,同时将日志记录的is_error(er)字段设置为true
span.endSpan();                            //结束自定义组件类日志上报

上报的自定义组件类日志结构为:

{
    ...
    "t":2,                                 -- span_type:2 -本地调用
    "y":0,                                 -- span_layer:0 -LOCAL
    "c":"CustomEvent"                      -- component:默认值为CustomEvent,可修改
    "o":"operation"                        -- operation:传入参数
    "g":
        {
            "tag.key1":"tag.value1",
            "tag.key2":"tag.value2"
        }
    "l":[                                  -- logs
        {                                  -- addLog
            "Timestamp":"UTC毫秒时间戳",
            "Data":{
                "event":"logging",
                "message":"日志信息",
            }
        },
        {                                  -- errorOccurred(error)
          "Timestamp": "UTC毫秒时间戳",  
          "Data": {
            "event": "error",
            "message": "test exception",
            "error_kind": "java.lang.RuntimeException",
            "stack": "java.lang.RuntimeException: test exception\r\nat cn.com.mypaas.fast.tracker.test.controller.SDKController.customEvent$original$pwcA1rmi(SDKController.java:64)\r\n"
          }
    ]

}
上报自定义组件日志示例:
  • 调用方法:

    // 创建外层span
    CustomSpan customSpan = FastTracker.beginSpan("/sdk/customEvent");
    try {
      Map tags = new HashMap();
      tags.put("request.path", "/sdk/customEvent");
      customSpan.setComponent("AppService")
          .setTags(tags)
          .addTag("tag.key", "tag.value")
          .addLog("no event log")
      // 创建嵌套span
      CustomSpan innerSpan = FastTracker.beginSpan("inner-span");
      try {
          innerSpan.setComponent("DomainService");
          innerSpan.addLog("domain log");
          innerSpan.addTag("domain.tag", "domain.value");
          throw new RuntimeException("test exception");
      } catch (Throwable t) {
          // 添加错误信息
          innerSpan.errorOccurred(t);
      } finally {
          // 结束span
          innerSpan.endSpan();
      }
    } catch (Throwable t) {
      customSpan.errorOccurred(t);
    } finally {
      customSpan.endSpan();
    }
    
  • 日志内容:

主日志记录:
{
  ...
  "s": "16380.0.1620466027616.0",  
  "t": 2,
  "y": 0,
  "c": "AppService",
  "o": "/sdk/customEvent",
  "g": {
    "request.path": "/sdk/customEvent"
    "tag.key": "tag.value",
  },
  "l": [
    {
      "Timestamp": 1620450350783,
      "Data": {
        "event": "logging",
        "message": "no event log"
      }
    }
  ]
}
子(嵌套)日志记录:
{
  ...
  "p": "16380.0.1620466027616.0",     --为主日志记录的"s"
  "s": "16380.2.1620466027711.2",  
  "t": 2,
  "y": 0,
  "c": "DomainService",
  "o": "inner-span",
  "er": true,
  "g": {
    "domain.tag": "domain.value"
  },
  "l": [
    {
      "Timestamp": 1620451245917,
      "Data": {
        "event": "logging",
        "message": "domain log"
      }
    },
    {
      "Timestamp": 1620451245919,
      "Data": {
        "event": "error",
        "message": "test exception",
        "error_kind": "java.lang.RuntimeException",
        "stack": "java.lang.RuntimeException: test exception\r\nat cn.com.mypaas.fast.tracker.test.controller.SDKController.customEvent$original$pwcA1rmi(SDKController.java:64)\r\n"
      }
    }
  ]
}

Maven配置

默认情况下,接入探针采集日志,仅需在jvm启动命令中添加`-javaagent参数即可,无需引入依赖项。如果需要接入sdk和自定义线程追踪,则需要配置maven私服下载依赖。

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <pluginGroups></pluginGroups>
    <proxies></proxies>
    <mirrors>
        <mirror>
            <id>snapshot</id>
            <mirrorOf>snapshots</mirrorOf>
            <name>snapshot</name>
            <url>https://nexus.mypaas.com.cn/repository/fast-maven-snapshot/</url>
        </mirror>
        <mirror>
            <id>mypaas</id>
            <mirrorOf>*</mirrorOf>
            <name>mypaas</name>
            <url>https://nexus.mypaas.com.cn/repository/maven/</url>
        </mirror>
    </mirrors>
    <profiles>
        <profile>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <id>mypaas</id>
            <repositories>
                <repository>
                    <id>release</id>
                    <name>release</name>
                    <url>https://nexus.mypaas.com.cn/repository/fast-maven-release/</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </repository>
                <repository>
                    <id>snapshots</id>
                    <name>snapshots</name>
                    <url>https://nexus.mypaas.com.cn/repository/fast-maven-snapshot/</url>
                    <snapshots>
                        <updatePolicy>always</updatePolicy>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>
</settings>

探针的配置项

本章节介绍Java探针支持的配置项信息和各配置项的默认值,以及如何设置和修改默认的配置信息。 Java探针支持的配置项和默认值见探针默认配置信息章节的列表,您可以通过添加探针配置文件(FastTracker.json)用户自定义配置用户环境变量配置运行时调用API接口配置几种方式设置和修改配置项的值,这几种方式的优先级为:默认配置 < 用户自定义配置(FastTracker.json)< 用户环境变量配置 < 运行时调用API接口配置

1、探针默认配置信息

字段名 类型 描述 示例数据 必填
Enable boolean 全局开关,默认为false true
Debug boolean 探针日志开关,默认为false true
ProductCode String 产品编码,默认为空 fast
AppCode String 应用编码,默认为空 analysis
EnvCode String 环境编码,默认为test test
TenantCode String 租户编码,默认为空 zsdc
UserCode String 业务用户ID,一般 用于用户细查的过 滤条件 zhangsan
ServiceName String 服务名称 天眼平台
SocketPath String 上报地址 udp://127.0. 0.1:5140
QueueSize int 上报队列大小默认值:1000 1024
BatchSize int 单次上报数量,默认值:1 1
IntervalInMs long 上报间隔,默认值:1000 1000
ReportMode int 上报模式,直接上报模式=0,转发模式=1,本地模式=2,当前仅支持转发模式 1
LoggingLevel String logging组件上报日志等级,默认值:ERROR ERROR
Event.Components.SqlClient boolean sql采集开关,默认值:true true
Event.Components.HttpClient boolean http采集开关,默认值:true true
TenantCodeReader.ReaderType String 租户编码读取类型,支持类型:QueryString、Cookie、RequestHeader RequestHeader
TenantCodeReader.ReaderKey String 租户编码读取字段 tenant_code
UserCodeReader.ReaderType String 用户编码读取类型,支持类型:QueryString、Cookie、RequestHeader RequestHeader
UserCodeReader.ReaderKey String 用户编码读取字段 user_code
CarrierHeader.TrackerName String 链路信息传输字段,默认值:fast-tracker fast-tracker
CarrierHeader.TraceIdName String 用户自定义TraceId,默认值:x-fast-trace-id x-fast-trace-id

2、用户自定义配置(FastTracker.json)

用户自定义配置是通过将探针配置文件FastTracker.json添加到探针agent/config目录下实现对配置信息的设置。 用户可自定义配置文件的读取路径,探针优先读取用户自定义路径的配置文件,未配置则读取默 认路径。例如:FastTracker.ConfigPath=/path/to/fast-tracker/agent/config/FastTracker.json
FastTracker.json文件的格式如下所示:

{
  "Enable": false,
  "Debug": false,
  "ProductCode": "fast‐test",
  "AppCode": "tracker‐test‐java",
  "EnvCode": "test",
  "TenantCode": "",
  "UserCode": "",
  "ServiceName": "天眼平台",
  "SocketPath": "udp://127.0.0.1:5140",
  "QueueSize": 1024,
  "BatchSize": 1,
  "IntervalInMs": 1000,
  "ReportMode": 1,
  "LoggingLevel": "ERROR",
  "Event": {
    "Components": {
      "SqlClient": true,
      "HttpClient": true
    }
  },
  "TenantCodeReader": {
    "ReaderType": "Cookie",
    "ReaderKey": "tenant_code"
  },
  "UserCodeReader": {
    "ReaderType": "Cookie",
    "ReaderKey": "user_code"
  },
  "CarrierHeader": {
    "TrackerName": "fast-tracker",
    "TraceIdName": "x-fast-trace-id"
  }
}

3、用户环境变量配置

用户可以通过自定义配置覆盖探针默认的配置项,自定义配置文件的字段和默认配置的字段保持一致,为方便用户部署,同时提供以环境变量的方式来配置探针。为了避免变量名称冲突探针配置项统一以FastTracker开头。

例如:

FastTracker.Enable=true
FastTracker.Event.Components.SqlClient=true
FastTracker.TenantCodeReader.ReaderType=RequestHeader
...

or

java -DFastTracker.Enable=true -DFastTracker.ServiceName=TEST -javaagent:fast-tracker-agent.jar -jar app.jar

or

export FastTracker.Enable=true
export FastTracker.ServiceName=TEST

4、运行时调用API接口配置

  • 动态设置租户编码

    FastTracker.setTenantCode(String code);
    
  • 动态设置用户编码

    FastTracker.setUserCode(String code);
    
  • 设置指定配置字段(不推荐)

    FastTracker.setConfig(String fieldName, Object fieldValue);
    

Java探针提供的API接口

  • FastTracker类的静态方法
      FastTracker.getTenantCode() // 获取租户编码
      FastTracker.setTenantCode(String tenantCode) // 设置租户编码
      FastTracker.getUserCode()// 获取用户编码
      FastTracker.setUserCode(String userCode)  // 设置用户编码
      FastTracker.getConfig() // 获取探针配置信息
      FastTracker.setConfig(String fieldName, Object fieldValue) // 设置探针配置
      FastTracker.getConfig(String fieldName)
      FastTracker.beginLog() // TrackerLog 开启自定义日志上报
      FastTracker.endLog()  关闭自定义日志上报
    
  • 编程接口伪代码举例:

      //静态方法调用   component使用Logging
      FastTracker.info("普通信息");
      FastTracker.debug("Debug信息");
      FastTracker.warning("警告信息");
      FastTracker.error("错误信息");
      FastTracker.fatal("致命信息");
    
      //自定义span
      span = FastTracker.beginSpan(operation);  //operation必填    
      span.setComponent(name);                   //设置component,默认值CustomEvent
      span.setTags(tags);                        //更新tags
      span.addTag(key,value);                    //追加一个键值对到tags
      span.addLog(message);                      //追加一个object到logs
      span.errorOccurred(error);                 //追加一个错误信息object到Logs,同时将日志记录的is_error(er)字段设置为true
      span.endSpan();                            //结束自定义组件类日志上报
    

附1:Java探针编译包目录结构

+-- agent
    +-- activations
         fast-toolkit-log4j-1.x-activation-1.0.0.jar
         fast-toolkit-log4j-2.x-activation-1.0.0.jar
         fast-toolkit-logback-1.x-activation-1.0.0.jar
         ...
    +-- config
         agent.config
         FastTracker.json
    +-- plugins
         fast-mysql-8.x-plugin-1.0.0.jar
         fast-httpClient-4.x-plugin-1.0.0.jar
         fast-pulsar-plugin-1.0.0.jar
         .....
    +-- optional-plugins
         fast-ignore-plugin-1.0.0.jar
         .....
    +-- bootstrap-plugins
         fast-jdk-threading-plugin-1.0.0.jar
         .....
    +-- logs
    fast-tracker-agent.jar

附2:Java探针支持采集列表

通信类
  • HTTP
数据库
  • mysql
  • sqlserver
  • mongodb
消息队列
  • pulsar
  • rabbitmq
  • rocketmq
  • kafka
缓存
  • redis
  • memcached

results matching ""

    No results matching ""