业务接入

1. 业务接入流程

XL-LightHouse并不涉及埋点以及数据采集细节等方面的功能，所有运算均基于业务通过调用SDK主动上报统计消息数据实现。

系统接入主要包括3个环节：

• 创建统计工程、创建相应的统计组并配置统计组的字段信息；
• 创建统计项；
• 按照配置的字段参数，上报消息数据；

2. 数据上报推荐方案

通用型流式数据统计可被应用在企业生产的众多环节，对于有条件的企业建议内部搭建统一的数据采集消息服务。

以互联网企业来说，统计原始消息数据的来源主要包括三类：

• 前端（App、PC、H5等）埋点数据

主要用于统计用户行为相关指标（比如：某个模块的点击量、用户数、点击率等）、前端技术层面数据指标（比如某个前端模块的接口耗时、页面渲染时间）等。

• 后端上报埋点数据

主要用于统计业务类指标（比如：订单量、交易额、下单用户数等）和后端技术层面指标（比如：接口耗时、接口异常量、推荐模型的准确率）等。

• 系统运维监控类数据

主要用于监控系统运行状况、集群负载等相关指标。

多种渠道的数据来源可以采用统一的数据采集消息服务，各接入端将相应的统计原始数据写入消息服务，在消费消息数据时调用LightHouseSDK上报数据。

这种方案的好处在于：

• 业务方接入更加便利；
• 统计服务与业务方自身服务没有代码侵入；
• 便于对统计原始数据进行备份，可用于数据恢复和重写。
• 便于将指定统计组的原始数据写入OLAP类引擎或离线存储引擎，可用于扩展数据分析等操作；

3. 统计工程划分原则

系统采用完全自助式指标获取方式，理论上对用户创建统计工程、统计组和统计项并不会进行任何干预，用户可根据自身需要随意指定。但为了使得系统的运算性能处于最佳状态以及在数据指标筛选和查阅等方面更加便捷，建议您遵循以下原则。

一个统计工程下包含的是具有相同属性的数据指标的合集。划分统计工程可以按照业务属性、接入人员、数据指标的类型、数据指标访问权限限制粒度等因素进行划分。

• （1）、依据业务属性划分统计工程

举例： Feed新闻推荐列表除了新闻帖子推荐外往往包含个性化广告推荐，广告相关数据指标和新闻推荐相关指标应该划分到不同的统计工程。

• （2）、依据数据指标的接入人员或后续维护人员不同划分统计工程；

系统以统计工程为单位对下面的统计指标进行管理维护，所以在划分统计工程时要充分考虑后续数据指标维护的便利性。

• （3）、依据数据指标类型划分统计工程

举例： 将基于前端埋点日志的数据指标和基于后端业务数据的指标分开管理； 将产品类指标、业务类指标、运营类指标、技术类指标、运维类指标分开管理； 将前端技术类指标和后端技术类指标分开管理；

• （4）、依据数据指标权限划分统计工程

举例：将保密等级高的数据指标和保密等级低的数据指标分开管理；

4. 统计组创建原则

+（1）、一般来说建议使用更少的统计组实现数据指标；

+（2）、只需要添加统计有关字段即可；

统计组字段只需要创建与统计有关字段即可，统计无关字段不需要添加。统计组字段目的只是为了完成统计指标，未必需要与自身业务表的字段一一对应。

+（3）、充分考虑可扩展性和后期维护的便利性；

+（4）、不建议使用太长的字符串字段；

5. 统计项创建原则

• （1）、避免重复创建；
• （2）、及时停止或删除已无实际业务价值的统计指标；
• （3）、建议使用网状结构管理数据指标；

一般来说数据指标可分为几种类型：核心数据指标、相关指标和上下游依赖指标。数据指标之间互相交叉印证，应避免单个孤立的指标的存在。

• （4）、除非必要，尽量减少大维度量、低时间周期的数据指标；

比如：电商业务中每个商品每分钟的点击用户量，此类大维度量、低周期的数据指标将要耗费更多的运算和存储资源，但实际业务价值往往较小，所以应尽量避免此类数据指标。

6. 线上使用注意事项

• 1、逗号和分号是系统内置分隔符，统计组字段值中不能包括逗号和分号，否则可能会与系统内置分割符冲突。

7. 防范数据泄露或数据丢失风险

• 线上环境请务必修改deploy.json中密码相关的参数配置。
• nodelist文件中包含root密码信息，部署完成后可将该文件删除。
• 部署完成后务必断开外网访问权限，防范各类网络攻击。
• 请不要使用过于简单的系统账号和密码，并定期修改密码信息。
• 建议有条件的企业自定义统计结果的Key生成逻辑。
• 建议有条件的企业将默认存储引擎替换为有专人维护的存储服务。
• 线上环境务必设置定时数据备份，有条件的企业可以采用双集群或多集群容灾方案。
• 可以在LightHouseSDK的基础上进行二次封装，将原始消息数据进行统一的离线存储，另外，如有必要可对数据指标查询API增加二次验签。

此外，如发现较为严重可能造成数据泄露风险的漏洞请及时通知开发者，开发者将会第一时间修复。

8. 引用SDK

目前LightHouse只对外提供Java版SDK，后续将面向中小企业提供Http版本的数据接入和查询接口。

jar包引用有三种方式：

8.1. 直接引用 lighthouse-shaded-client-x.x.x.jar（推荐使用）

该jar包包含LightHouseClient包以及所有相关第三方依赖包。

<!-- 使用MvnRepository中的最新版本即可，请使用2.2.3或以上版本 -->
<dependency>
    <groupId>com.dtstep.lighthouse</groupId>
    <artifactId>lighthouse-shaded-client</artifactId>
    <version>2.2.3</version>
</dependency>

8.2. 自定义打包（推荐使用）

如果lighthouse-shaded-client依赖的第三方jar包与您自身系统的jar包存在冲突，而导致无法直接使用时，您可以自定义打包。

操作流程如下：

• 1、使用git下载项目源码；
• 2、修改lighthouse-shaded-client模块的pom.xml中的冲突jar包的版本，请您的第三方jar包版本添加到配置中；
• 3、重新编译导出lighthouse-shaded-client包；

8.3. 使用分开引用的方式（不推荐使用）

<dependency>
    <groupId>com.dtstep.lighthouse</groupId>
    <artifactId>lighthouse-client</artifactId>
    <version>x.x.x</version>
    <exclusions>
        <exclusion>
            <artifactId>*</artifactId>
            <groupId>*</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>com.dtstep.lighthouse</groupId>
    <artifactId>lighthouse-common</artifactId>
    <version>x.x.x</version>
    <exclusions>
        <exclusion>
            <artifactId>*</artifactId>
            <groupId>*</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.javatuples</groupId>
    <artifactId>javatuples</artifactId>
    <version>1.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.11.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.11.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.11.0</version>
</dependency>
<dependency>
    <groupId>org.xerial.snappy</groupId>
    <artifactId>snappy-java</artifactId>
    <version>1.1.7.3</version>
</dependency>
<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
    <exclusions>
        <exclusion>
            <artifactId>*</artifactId>
            <groupId>*</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-all</artifactId>
        <version>4.1.84.Final</version>     
</dependency>
<dependency>
      <groupId>com.squareup.okhttp3</groupId>
      <artifactId>okhttp</artifactId>
      <version>3.6.0</version>
      <scope>compile</scope>
    </dependency>

如有问题，请随时联系开发者！