用测试日志验证采集结构与指标：事件日志发送 第2篇

为什么要在开发事件发送功能之前验证数据

《用事件模板定义日志采集结构：事件日志发送 第1篇》介绍了如何定义要分析的事件与属性，并准备用于发送日志的源代码。本篇将在正式提出开发需求之前发送测试日志，验证事件的采集结构以及能否用于指标分析。

在开发事件发送功能之前，需要确认数据能否正常采集，以及能否用这一结构构建所需的指标。即使事件名称和属性已经确定，如果实际值的格式或数据类型与分析口径不一致，往往要等开发完成后才会发现属性缺失或指标计算方面的问题。

数据分析人员发送测试日志后，需要确认事件与属性是否按预期的结构采集，指标所需的属性是否全部包含在内；同时检查各属性的数据类型和值的格式，并确认对采集到的数据应用运算与维度后，能否构建出所需的指标。

例如，如果内容完成事件中不包含用户标识符，就无法计算完成用户数。如果游玩时长被设置为字符串类型，或者没有约定值的单位，平均游玩时长也很难按预期的口径查看。在开发前发送样本数据，检查实际的采集形态和指标结果，就能把事件结构和发送规范进一步明确下来。

在 Hive Analytics 中验证测试日志的方法

在 Hive Analytics 的 Data > Event 中，可以查看已注册的事件与属性，并通过 ETL Simulation 或代码实现来发送测试日志。为各属性填入符合分析场景的样本值，就能在开发实际的日志发送功能之前，确认数据采集结果以及能否用于指标分析。

测试日志的验证按以下顺序进行：先准备发送环境和 App ID 并发送日志，再确认采集结果和指标构建。

1. 选择环境
   根据验证目的，选择发送测试日志的沙箱环境或正式环境。在 Data Preview 和 BigQuery 中确认结果时，也必须查询发送日志所在环境的数据。
2. 准备 App ID
   准备已在 Hive 控制台的 App Center（应用中心）或项目设置中注册的 App ID。

   在正式环境中区分测试数据
   如果要在正式环境中明确区分测试数据和实际运营数据，建议单独注册并使用测试用 App ID。如果在游戏上线前测试，可以在 Time Settings（时间设置）中将正式上线日设为指标起始日，把上线前采集的数据排除在指标统计之外。如果游戏已经在运营中，可以在 Metric Filters（指标筛选）中注册测试用 App ID，或在 Excluded User Management（指标排除用户管理）中注册测试账号，将相应数据排除在指标统计之外。请根据测试数据的区分口径和运营状态选择合适的方法。

3. 发送测试日志
   可以由分析人员在 ETL Simulation 中直接发送，也可以由开发人员实现在 Source Generation（源码生成）中确认的代码后发送。在事件属性中填入模拟分析场景的样本值，并在发送前确认用户标识符、内容信息、数值型属性等是否符合所定义的数据类型和值的格式。
4. 确认采集结果
   在 Data Preview 中确认事件是否已接收，以及传入的属性值。如果需要详细查看原始数据，可以在 BigQuery 中直接查询事件数据，检查输入的值是否以正确的属性名称和数据类型存储。

   申请 BigQuery 查询权限
   采集到的事件与属性的原始数据可以在 BigQuery 中直接查询。如需使用 BigQuery，请先获取 Hive Analytics 管理员权限，再在 Hive Analytics 的账号菜单中申请 BigQuery 查询权限。

5. 确认指标构建
   在 Create 中选择采集到的事件作为度量值，并应用所需的运算与维度。确认计算出的数值是否与预期一致、结果是否按属性值以预期的口径区分，以验证能否用这些数据构建符合分析目的的指标。

用 contents_success 测试日志验证事件

如果要分析内容完成用户数、平均游玩时长和最高分数，就需要验证 contents_success 事件是否按预期的结构采集。从选择环境到确认指标构建的流程如下。

1. 选择环境

为了确认实际运营中要使用的数据结构，在正式环境中进行验证。登录正式环境的 Hive Analytics 控制台，在 Data > Event 中选择 contents_success 事件，并切换到 ETL Simulation 标签页。

2. 准备 App ID

确认正式环境中要使用的测试用 App ID 已在 Hive 控制台的 App Center 或项目设置中注册。

3. 发送测试日志

测试日志可以由分析人员在 ETL Simulation 中直接发送，也可以由开发人员将 Source Generation 提供的代码接入游戏后发送。无论采用哪种方法，都必须填写发送日志所需的必填属性 userId、deviceId、identifierProvider、appId、eventTime、eventName。identifierProvider 填写 hive，appId 填写前面准备好的测试用 App ID。appIdGroup 会在填写 appId 后自动生成，无需另外填写。

3.1 通过 ETL Simulation 发送

查看事件预先定义的属性和数据类型，修改 6 个必填属性的值。接着将 characterLv、modeTypeId、modeTypeName、score、playTimeSec 改为符合分析场景的样本值，然后发送测试日志。

3.2 用生成的源代码发送

开发人员在 Source Generation 中查看适合自身开发环境的代码，将 6 个必填属性和事件的详细属性值与实际游戏数据关联起来。接入代码，使 contents_success 事件在内容完成被确认时触发，然后运行已实现的功能发送测试日志。具体的实现方法请参考 Hive 开发者网站的事件发送指南。

发送日志时的注意事项
如果不遵守以下规则，日志将无法正常采集，而会被存入单独的隔离表 t_raw_event_log_rescue。

• eventTime 须以包含时区的 RFC 3339 格式填写，并设置在以当前时间为基准的过去 10 年至未来 5 年范围内。格式不正确或超出允许范围时，日志会被隔离。
• appId 须填写已在 Hive 控制台的 App Center 或项目设置中注册的 App ID。填写未注册或错误的值时，日志会被隔离。

4. 确认采集结果

4.1 在 Data Preview 中确认

发送后，在 Data Preview 中确认是否已接收 contents_success，同时查看用户和设备标识符、App ID、事件名称，以及 attributes 中包含的属性值。

4.2 在 BigQuery 中确认

如果要更详细地查看原始数据，可以在 BigQuery 中以测试用 App ID 和事件名称为条件查询数据，确认发送的 characterLv、modeTypeId、modeTypeName、score、playTimeSec 是否以预期的值和数据类型存储。

5. 确认指标构建

如果采集结果没有问题，就在 Create 中选择 contents_success 事件，按以下方式构建指标。

• 对 userId 应用 COUNT DISTINCT 运算，查看内容完成用户数。
• 对 playTimeSec 应用 AVG 运算，查看平均游玩时长。
• 对 score 应用 MAX 运算，查看最高分数。
• 选择 characterLv 和 modeTypeName 作为维度，按角色等级、按内容对比结果。

如果能够构建完成用户数、平均游玩时长和最高分数，并且结果能按角色等级和内容区分，就说明该事件已按分析目的准备就绪。如果出现值缺失或结果与预期不符，请重新检查属性名称、数据类型和样本值。修改必要内容后重新发送测试日志，并根据变更后的事件设置重新生成开发用源代码。

验证完成后，将确定的源代码、事件触发时机以及各属性要传入的值交给开发人员，提出实际日志发送功能的开发需求。

在实际游戏中接入事件发送代码并发送数据的方法，请参阅下一篇《将游戏数据作为事件日志发送：事件日志发送 第3篇》。

开始使用 Hive Analytics

配置好事件与属性后发送测试日志，就能在提出开发需求之前，确认数据采集结构以及能否用于指标分析。根据验证过程中发现的问题确定事件设置和源代码后，再交给开发人员。

Hive Analytics 是一款面向游戏的专业分析解决方案，可基于通过 Hive SDK 采集的游戏事件，分析用户行为和游戏指标。现在就在 Hive Analytics 中发送测试日志，确认能否用采集到的数据构建所需的指标吧。