调试模式

最后更新于：2018-08-08 16:59:43

1. 适用场景

为了更加方便使用者调试代码和调整数据格式，我们为各个语言的 SDK 以及 LogAgent、BatchImporter 等导入工具，增加了调试模式的选项，主要用于：

1. 在开发人员调试代码和数据时使用；
2. 以同步、阻塞的方式，向后端发送数据；部分语言由于语言特性，这一机制可能略有不同；
3. 实时地展示服务端的校验结果，当校验失败时，不仅仅会展示具体的错误原因，并且会以抛异常等形式（具体实现取决于具体语言），显示地提醒使用者；
4. 对于校验成功的数据，在导入辅助工具中，可以实时看到最终入库的的各条数据的各个字段的值与类型。

请注意，不要在生产环境或正式发布的 App 中使用 Debug 模式。

2. 使用

2.1 SDK 使用调试模式

各个语言的 SDK 使用调试模式，主要是在初始化时，加上相关的参数。由于不同语言的实现机制不同，我们分别进行说明。

2.1.1 Python SDK

在 Python SDK 中，使用调试模式，需要初始化一个专门的 DebugConsumer 对象，然后用这个 DebugConsumer 对象来初始化对应的 SensorsAnalytics 对象。

DebugConsumer 的构造函数的定义如下：

def __init__(self, url_prefix, write_data=True, request_timeout=None):
        """
        初始化Consumer
        :param url_prefix: 神策分析用于数据接收的 URL
        :param write_data: 发送过去的数据是真正写入，还是仅仅进行检查
        :param request_timeout:请求的超时时间,单位毫秒
        :return:
        """

各个参数含义在注释上已经写明了。特别需要强调几点：

1. url_prefix：该参数与其他 Consumer 一样，为神策分析用于数据接收的 URL
2. write_data：这个参数默认为 True，也即发送过去的数据会真正地写入后端；如果这个参数设置为 False，则说明数据只发送过去进行校验，不会真正地写入。

2.1.2 PHP SDK

PHP SDK 的调试模式的使用方式和 Python SDK 类似，也是构造一个 DebugConsumer 的对象，然后用它来初始化 SensorsAnalytics 对象。

DebugConsumer 的构造函数如下：

    /**
     * DebugConsumer constructor,用于调试模式.
     * 具体说明可以参照: http://www.sensorsdata.cn/manual/debug_mode.html
     * 
     * @param string $url_prefix 神策分析用于数据接收的 URL
     * @param bool $write_data 是否把发送的数据真正写入
     * @param int $request_timeout 请求服务器的超时时间,单位毫秒.
     * @throws SensorsAnalyticsDebugException
     */
    public function __construct($url_prefix, $write_data = True, $request_timeout = 1000)

各个参数的含义与 Phthon SDK 基本一致，不再赘述。

2.1.3 Java SDK

在 Java SDK 中使用调试模式，需要初始化一个专门的 DebugConsumer 对象，然后用这个 DebugConsumer 对象来初始化对应的 SensorsAnalytics 对象。DebugConsumer 的构造函数的定义如下：

    /**
     * DebugConsumer，用于调试模式
     *
     * @param serverUrl 神策分析采集数据的 URL
     * @param writeData 是否把发送的数据真正写入神策分析
     */
    public DebugConsumer(final String serverUrl, final boolean writeData)

各个参数的含义与 Phthon SDK 基本一致，不再赘述。

2.1.4 iOS SDK

iOS SDK 提供 Debug 模式，用于校验数据导入，用户使用时，请小心该设置，不要带到正式发布的 App 中。它将可能影响用户体验。

iOS SDK 中通过 SensorsAnalyticsSDK 的参数初始化，指定 Debug 模式:

/**
 * @abstract
 * 根据传入的所部署的 SensorsAnalytics 服务器的 URL，返回一个<code>SensorsAnalyticsSDK</code>的单例
 *
 * @param serverURL 神策分析用数据接收的 URL
 * @param configureURL 获取配置信息的 URL
 * @param vtrackServerURL 可视化埋点配置系统的 URL
 * @param debugMode 是否打开 Debug 模式
 *
 * @return 返回的单例
 */
+ (SensorsAnalyticsSDK *)sharedInstanceWithServerURL:(NSString *)serverURL
                                     andConfigureURL:(NSString *)configureURL
                                  andVTrackServerURL:(NSString *)vtrackServerURL
                                        andDebugMode:(SensorsAnalyticsDebugMode)debugMode;

其中 SensorsAnalyticsDebugMode 为枚举类型，定义如下:

/**
 * @abstract
 * Debug 模式，用于检验数据导入是否正确。该模式下，事件会逐条实时发送到 SensorsAnalytics，并根据返回值检查
 * 数据导入是否正确。
 *
 * @discussion
 * Debug 模式的具体使用方式，请参考:
 *  http://www.sensorsdata.cn/manual/debug_mode.html
 *
 * Debug 模式有三种选项:
 *   SensorsAnalyticsDebugModeOff - 关闭 DEBUG 模式
 *   DebugOnly - 打开 DEBUG 模式，但该模式下发送的数据仅用于调试，不进行数据导入
 *   DebugAndTrack - 打开 DEBUG 模式，并将数据导入到 SensorsAnalytics 中
 */
typedef NS_ENUM(NSInteger, SensorsAnalyticsDebugMode) {
    SensorsAnalyticsDebugOff,
    SensorsAnalyticsDebugOnly,
    SensorsAnalyticsDebugAndTrack,
};

SensorsAnalyticsDebugOnly 模式下，数据不会真正写入后端，只用于调试数据导入。 SensorsAnalyticsDebugAndTrack 下，数据不仅用于调试，也会真正导入后端。

一个使用 Debug 模式初始化 SensorsAnalyticsSDK 的样例如下：

    [SensorsAnalyticsSDK sharedInstanceWithServerURL:@"http://sa_host:8006/sa"
                                     andConfigureURL:@"http://sa_host:8006/config"
                                  andVTrackServerURL:@"ws://sa_host:8007/api/ws"
                                        andDebugMode:SensorsAnalyticsDebugOnly];

它初始化 SensorsAnalyticsSDK 实例，并定义 Debug 模式为 SensorsAnalyticsDebugOnly，校验埋点的事件，但事件不会真正导入后端。

2.1.5 Android SDK

Android SDK 提供 Debug 模式，用于校验数据导入，用户使用时，请小心该设置，不要带到正式发布的 App 中。它将可能影响用户体验。

Android SDK 的调试模式在 SensorsDataAPI 实例初始化时设置，SensorsDataAPI初始化有五个参数，最后一个 debugMode 用于指定 Debug 模式的类型，其中 DebugMode 为枚举类型，初始化方法和 DebugMode 的定义如下

public class SensorsDataAPI {

  /**
   * Debug 模式，用于检验数据导入是否正确。该模式下，事件会逐条实时发送到 SensorsAnalytics，并根据返回值检查
   * 数据导入是否正确。
   * <p/>
   * Debug 模式的具体使用方式，请参考:
   * http://www.sensorsdata.cn/manual/debug_mode.html
   * <p/>
   * Debug 模式有三种：
   * DEBUG_OFF - 关闭 DEBUG 模式
   * DEBUG_ONLY - 打开 DEBUG 模式，但该模式下发送的数据仅用于调试，不进行数据导入
   * DEBUG_AND_TRACK - 打开 DEBUG 模式，并将数据导入到 SensorsAnalytics 中
   */
  public enum DebugMode {
    DEBUG_OFF(false, false),
    DEBUG_ONLY(true, false),
    DEBUG_AND_TRACK(true, true);
    // ...
  }

  /**
   * 初始化并获取 SensorsDataAPI 单例
   *
   * @param context App 的Context
   * @param serverURL 神策分析用于收集事件的服务地址
   * @param configureURL 用于获取可视化埋点配置的服务地址
   * @param debugMode Debug 模式
   *
   * @return an instance of SensorsDataAPI associated with your project
   */
  public static SensorsDataAPI sharedInstance(Context context, String serverURL,
      String configureURL, DebugMode debugMode) {
    // ...
  }

  // ...
}

当 Debug 模式设为 DEBUG_ONLY 时，数据不会真正写入后端，只用于调试数据导入。 当 Debug 模式设置为DEBUG_AND_TRACK 时，数据不仅用于调试，也会真正导入后端。

一个使用 Debug 模式初始化 SensorsDataAPI 的样例如下：

SensorsDataAPI sa = SensorsDataAPI.sharedInstance(
          this,
          "http://sa_host:8006/sa",
          "http://sa_host:8006/config",
          SensorsDataAPI.DebugMode.DEBUG_OFF);

它初始化 SensorsDataAPI 实例，并定义 Debug 模式为 DEBUG_ONLY，校验埋点的事件，但事件不会真正导入后端。

2.1.6 JavaScript SDK

JavaScript SDK 的 debug 通过 控制台 + 埋点管理来查看。

确认数据发送是否发送成功的步骤：

1 浏览器控制台查看发送是否正常（步骤1）。

js-sdk 默认配置了 show_log:true。打开浏览器的控制台，会在触发埋点信息时，在控制台打印一条数据。 如果有错误信息，会显示错误的原因。 如下图：

如果数据正常发送，会打印发送的数据。如下图：

2 埋点管理查看数据接收是否正常（步骤2）

埋点管理查看主要分两种查看方式：已经导入数据查看，导入实时查看。

2.1 已经导入数据查看

点击「埋点」 --> 「埋点管理」，选择「时间区间」（「来源端」和「应用版本」可以根据需要选择），可以查询到数据导入情况。如下图：

说明：
「位置1」：整体的导入情况；
「位置2」：单个埋点导入情况；
「位置3」：如果导入数据有问题，这里会是红色的文字。点击数字，可以看到具体的报错信息。

2.2 导入实时查看

点击「埋点」--> 「导入实时查看」--> 「导入中数据」。可以监测具体的事件名和具体的用户（distinct_id）。点击「开始刷新」按钮。

这时候，前端发送数据，这里就可以看到接收到的数据。看到了接收数据，说明数据接收正常。如下图：

注意 ：debug 数据 是查看 debug 模式发送的不入库数据。debug 模式入库数据使用「导入实时查看」查看。

3 事件分析查看具体的事件（步骤3）

事件数据正常入库后，就可以在事件分析页面查看具体事件的统计数据。
「步骤1」正常以后，就可以直接跳过「步骤2」，进行「步骤3」查看。如果「步骤3」查看不到数据，可以再通过「步骤2」查找原因。

常见问题：

1「步骤1」正常，「步骤2」和「步骤3」看不到数据：
检查 sdk 初始化代码里面的 server_url 是否正确。主要是“数据接收地址”和“项目”是否与神策后台“代码生成工具”生成的一直。

2.2 LogAgent 和 BatchImporter 使用调试模式

LogAgent 和 BatchImporter 的调试模式主要是对数据正确性的校验，详情请参考：

• BatchImporter 使用说明 中 4.2.校验数据模式
• LogAgent 使用说明 中 5.使用 LogAgent 校验数据
• FormatImporter 使用说明 中 4.2.公共参数