1. 常见数据报错类型

1.1. 属性类型错误  error_type: PROPERTY_WITH_WRONG_TYPE

上报的属性类型需要和系统内原有的属性类型一致,不一致系统会进行强转,强转失败就会报改错。例如: datatime 类型的属性,传值空字符串会报错。

1.2. 数据的time不在有效的数据时间区间内,error_type: EXPIRED_RECORD

原因:App 端的数据,默认认为当前时间 10 天前或 1 小时后的数据为过期数据。报错后该条数据整条不会入库。

解决办法:

(1)如果因延迟上报导致数据时间过期,无法入库的数据量较小,则属于正常情况。无需做相关处理。

(2)如果出现大量数据延迟上报,可以和客户确认下对应 APP 的使用场景,如果客户的 APP 确实会存在很多数据会超过 10 天才延迟上报,可以让神策运维修改下有效时间窗口期。注意:需要告知客户,窗口期修改之后,会存在查询多天之前的数据时,不同时间查询数据不一致的情况。

APP 端设置有效接收窗口期的原因:

(1)保证业务指标统计数据稳定:如果不限制延迟上报数据的时间范围,延迟上报的数据,会导致查询历史数据时,不同时刻查询,数据是不一样的。 默认设置接收过去 10 天之内和未来 1 小时的数据,是根据行业经验值得出的。这样既能保证合理时间范围内的数据都能发送到神策系统中,又能保证查询历史数据时,统计的数据是稳定的。
(2)实现上:神策底层存储数据的 HDFS 文件不支持追加写入,只能一次性写入,再追加数据需要添加新文件,如果不限制接收数据的有效期,会导致底层存储经常添加新文件用来存放延迟上报的数据,文件越多查询性能越差。

综上所述,设置数据的有效时间范围更合理。

1.3. 已存在与需新创建属性的属性名仅大小写不同的属性。error_type: PROPERTY_NAME_CASE_INSENSITIVE_DUPLICATE

提示已经有其他除了大小写不一致其他都一致的属性名,需要修改新上报的属性名,可以保持和已存在的完全一样,也可以用一个新的属性。

1.4. 预置属性(以 $ 开头的属性)不存在。 error_type:PRESET_PROPERTY_NAME_INVALID

自定义属性不能带 $,带 $ 开头的自定义属性会被抛弃(在报错的 json 中不提示),并在埋点管理中提示信息错误,其他字段会正常入库。可以看该 json 数据中 error_reason 字段中描述无法创建哪个属性名。

2. 批量导入多次使用相同目录

建议每次批量导入都使用不同目录,方便出现问题后重新导入。

3. 实时数据无法正常导入

  1. 请检查 SDK 或 LogAgent 发送数据目标机器是否填写正确,注意端口号和 sa,一般是:http://sa_host:8106/sa;
  2. 请检查数据是否符合 数据格式

4. 某个 property 在前端看不到

可能的原因:

  1. 类型不符:使用了与之前不同的数据类型;
  2. 数据过长:如字符串最长 255 字节;
  3. 非有效类型:使用了 数据格式 中未定义的数据类型,比如某个 property 是一个 JSON object。若如此,请将此对 JSON object 内含字段单独抽取出来作为 property 使用;
  4. 非固有字段加了$:只有 数据格式 中定义的固有字段的 key 可以以 $ 开头。

这些都可以到埋点管理内查看是否有报错数据,若报错,会有具体原因。

5. 如何清除某个事件?

将不需要的事件隐藏,然后使用新的事件名导入,已经有数据入库的事件无法删除事件名的定义。

6. track_signup 的作用是什么?

track_signup 的用途是关联匿名 id 和登录 id,当且仅当此时 original_id 为必须字段且有意义.
distinct_id 为必须字段,没有该字段会被认为是无效数据。

7. 数据导入 Token 的作用是什么?

自 Sensors Analytics 1.6 开始,我们增加了数据导入 Token。现在有两种类型的 Token:

  • Normal Token:使用该 Token 可以导入已经存在的事件(仅可包含已经存在的属性)和用户属性数据,若事件不存在或事件或用户的某个属性未在 Sensors Analytics 里建立,那么这条数据将被抛弃;
  • Super Token:用该 Token 除了可以导入数据,还可以在 Sensors Analytics 创建不存在的事件和属性;

其他:

  • 云版不支持自定义数据导入 Token;
  • 默认情况下 Normal Token 和 Super Token 值为空;
  • 不同项目可以设置不同的 Token;

7.1. 判断数据 Token 类型

判断一条数据使用哪一种 Token 将采取如下流程:

  1. 初始化,标记数据为 无效数据
  2. 将数据的 Token 与 Super Token 比较,若值相同或 Super Token 值为空,那么标记数据为 Super 数据
  3. 将数据的 Token 与 Normal Token 比较,若值相同或 Normal Token 值为空,那么标记数据为 Normal 数据

从上到下经过这 3 步流程,即一条数据将尝试获取能取到的最大的权限,若最终仍然是“无效数据”,那么这条数据将被抛弃。

举例如下:

  • Super 数据: 可根据数据创建事件、属性等;
  • Normal 数据: 可导入但不能创建事件、属性等。若数据中包含不存在的事件、属性,数据将被抛弃;
  • 无效数据: 抛弃这条数据;
Super TokenNormal Token数据 Token类型原因数据类型
(空)(空)(空)第三步中“Super Token 值为空”Super 数据
(空)(空)ABC第三步中“Super Token 值为空”Super 数据
(空)123(空)第三步中“Super Token 值为空”Super 数据
(空)123ABC第三步中“Super Token 值为空”Super 数据
(空)123123第三步中“Super Token 值为空”Super 数据
XYZ(空)(空)第二步中“Normal Token 值为空”Normal 数据
XYZ(空)ABC第二步中“Normal Token 值为空”Normal 数据
XYZ(空)XYZ第三步中“与 Super Token 值相同”Super 数据
XYZ123(空)第一步中标为无效数据无效数据
XYZ123ABC第一步中标为无效数据无效数据
XYZ123123第二步中“Normal Token 值为空”Normal 数据
XYZ123XYZ第三步中“与 Super Token 值相同”Super 数据

7.2. 取数据 Token

数据的 Token 获取流程如下:

  1. 取数据中的 'token' 字段(与 'type' 字段平级),如:

    {"distinct_id":"a","time":1471586368135,"type":"track","event":"ViewProduct","properties":{},"token":"my_token"}
    JS
  2. 若上一步没有取到,取数据接入地址中的 token 值,如:http://SA_HOST:8106/sa?token=my_token

  3. 若仍然没有取到,那么认为值为空。

7.3. 设置 Token

通过 多项目管理工具 设置 Normal Token 和 Super Token。

8. 使用sdk导入在埋点管理发现报错,如何找回错误的数据?

我们在系统的日志目录下保留了一段时间的错误日志,需要登录到机器上查看,具体方法是:

  1. 登录到机器上。切换到 sa_cluster 帐号,注意集群版需要登录每台机器才能获取全部错误数据。云版目前不支持登录后台机器,需要联系我们来操作。
  2. 获取日志目录。
    1. 若神策分析大版本 < 1.14,则执行 grep 'sensors_analytics.log_dir' ~/sa/conf/sensors_analytics.property 查看结果,然后进入结果中的目录后再 cd extractor,会发现有一系列 invalid_records 开头的文件,即为错误日志保留的文件。
    2. 若神策分析大版本 = 1.14,则执行 grep 'sensors_data.log_dir' ~/conf/sensors_data.property 查看结果,然后进入结果中的目录,cd sa/extractor,会发现有一系列 invalid_records 开头的文件,即为错误日志保留的文件。
    3. 若神策分析大版本 ≥ 1.15,则执行 grep 'sensors_data.log_dir' ~/conf/sensors_data.property 查看结果,然后进入结果中的目录,cd sp/extractor,会发现有一系列 invalid_records 开头的文件,即为错误日志保留的文件。
    4. 若神策分析大版本 ≥ 1.17,则执行 grep 'sensors_data.log_dir' ~/conf/sensors_data.property 查看结果,如果存在 sdf 目录则 cd sdf/extractor,若不存在则 cd sp/extractor,会发现有一系列 invalid_records 开头的文件,即为错误日志保留的文件。
    5. 若执行步骤 d 时找到的目录下没有 invalid_record 文件,是因为安装 SDF 2.2+ 以后将错误的数据都保存到了 kafka,可使用 sdfadmin invalid_record 命令进行查询。
      1. 读取(读完终端就退出)       sdfadmin invalid_record read [–start][–end]
        1. --start 可选,起始时间(yyyy-MM-dd HH:mm:ss / yyyy-MM-dd),默认从最早保存时间开始读取,最多保存 7 天。
        2. --end 可选,终止时间(yyyy-MM-dd HH:mm:ss / yyyy-MM-dd), 默认读取至最新。
        3. 示例:读取整个集群 2021-01-01 至今的 invalid_record(最多读取 7 天。)

          sdfadmin invalid_record read --start 2021-01-01 | grep xxx >  $SENSORS_DATAFLOW_LOG_DIR/kafka.log
          CODE

          xxx 为需要的筛选条件,按需要的筛选条件,然后把数据输出到 $SENSORS_DATAFLOW_LOG_DIR/kafka.log 中


      2. 持续读取(终端一直等待)   sdfadmin invalid_record tailf 
        1. 示例:持续消费整个集群的 invalid_record

          sdfadmin invalid_record tailf
          CODE

注意:

  1. 错误日志只会保留一段时间,默认是 14 天,但是如果磁盘报警可能会清理部分日志。
  2. 错误日志文件包含了所有项目的所有错误,请自行解析选择需要的日志。
  3. 注意:从 extractor 的 invalid_records 日志里拿出来的数据重新导入的时候,数据清理时需要要把 error_type 和 error_reason 字段去掉,否则重新导入数据时会报错
  4. 神策分析大版本号可以咨询值班同学获取
  5. sdfadmin invalid_record 工具最多保留最近 7 天的数据