1. Python SDK 使用说明

在使用前,请先阅读 数据模型 的介绍。

2. 集成神策分析 SDK

在 Python 代码中集成神策分析 SDK,使用神策分析采集并分析用户数据。

我们推荐使用 pip 管理 Python 项目并获取神策分析 SDK:

pip install SensorsAnalyticsSDK
BASH

如果不使用 pip,也可以从 GitHub 下载 神策分析 SDK 的源代码。

SDK 兼容 Python 2.6+ 和 Python3 3.X,不依赖第三方库。

2.1. 初始化神策分析 SDK

2.1.1. 获取配置信息

如下图所示获取数据接收地址:

2.1.2. 在程序中初始化 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例,在生产环境中使用 ConcurrentLoggingConsumer,并结合 LogAgent 工具完成数据采集。

import sensorsanalytics

# 初始化一个 Consumer,用于数据发送
# ConcurrentLoggingConsumer 是将数据写在日志文件中,再利用神策提供的 LogAgent 工具发送数据
consumer = sensorsanalytics.ConcurrentLoggingConsumer('您的日志文件路径')
# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)

# 记录用户登录事件
distinct_id = 'ABCDEF123456789'
sa.track(distinct_id, 'UserLogin', is_login_id=True)

# 上报所有缓存数据,测试时可以调用调试数据,线上环境一般可以不调用
sa.flush()

sa.close()
PY

程序退出前,需要使用 close() 方法显式关闭,否则可能丢失部分缓存的数据。至此,我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法,可以跳到本文末尾的控制神策分析 SDK 一节。

3. 设置神策分析 SDK

Golang SDK 主要由以下两个组件构成:

  • SensorsAnalytics:用于发送数据的接口对象,构造函数需要传入一个 Consumer 实例
  • Consumer:Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据,神策分析 SDK 实现了以下 Consumer:

  • LoggingConsumer
  • ConcurrentLoggingConsumer(推荐)
  • DebugConsumer(测试使用)
  • ConsoleConsumer
  • DefaultConsumer
  • BatchConsumer
  • AsyncBatchConsumer

3.1. LoggingConsumer

用于将数据输出到指定目录并按天切割文件,一般用于在 Python 脚本中处理实时数据,生成日志文件并使用 LogAgent 等工具导入。适用于单进程程序。

import sensorsanalytics

# 初始化 LoggingConsumer
consumer = sensorsanalytics.LoggingConsumer('/data/sa/access.log')

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)
PYTHON

可以通过参数配置切分间隔和保留的文件数,默认是每天0点切割,保留所有文件。具体参数含义参考 Python 标准库 logging.handlers.TimedRotatingFileHandler 文档

# 按小时切分,保留最近10个文件
consumer = sensorsanalytics.LoggingConsumer('/data/sa/access.log', backupCount=10, when='H')
PYTHON


请不要使用多进程写入同一个日志文件,可能会造成数据丢失或者错乱。如果需要多进程写入,请使用 ConcurrentLoggingConsumer。

3.2. ConcurrentLoggingConsumer(推荐)

用于将数据输出到指定目录,并自动按 天 切割文件,与 LoggingConsumer 不同的是,它支持多进程写入同一个文件。一般用于 Django、uWSGI 等特殊的多进程场景。

import sensorsanalytics

# 当缓存的数据量达到参数值时,批量向文件中写入数据
SA_BULK_SIZE = 1024

# 初始化 ConcurrentLoggingConsumer,写入文件 '/data/sa/access.log.YYYY-MM-DD' 中,日志缓冲区长度为 1024 条
consumer = sensorsanalytics.ConcurrentLoggingConsumer('/data/sa/access.log', SA_BULK_SIZE)

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)

# ...

# 上报所有缓存数据,测试时可以调用调试数据,线上环境一般可以不调用
sa.flush()
PYTHON

LogAgent 配置文件中一定要注释掉 real_time_file_name 参数,否则无法正常导入数据。已使用 LoggingConsumer 的客户建议按照如下步骤切换到 ConcurrentLoggingConsumer:

第 1 步 停掉 LogAgent,并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步 将日志目录下的 real_time_file_name 的文件加上当前时间的后缀 ".YYYY-MM-DD"。
第 3 步 后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步 重新启动 LogAgent。


3.3. DebugConsumer(测试使用)

用于校验数据导入是否正确,关于 调试模式 的详细信息,请进入相关页面查看。请注意:Debug 模式是为方便开发者调试而设置的模式,该模式会逐条校验数据并在校验失败时抛出异常,性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险,产品上线前请务必替换掉/关闭 Debug 模式。

import sensorsanalytics

# 神策分析数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'
# 发送数据的超时时间,单位秒
SA_REQUEST_TIMEOUT = 1
# Debug 模式下,是否将数据导入神策分析
# True - 校验数据,并将数据导入到神策分析中
# False - 校验数据,但不进行数据导入
SA_DEBUG_WRITE_DATA = True

# 初始化 DebugConsumer
consumer = sensorsanalytics.DebugConsumer(SA_SERVER_URL, SA_DEBUG_WRITE_DATA, SA_REQUEST_TIMEOUT)

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)
PYTHON

3.4. ConsoleConsumer

用于将数据输出到标准输出,一般用于在 Python 脚本中处理历史数据,生成日志文件并使用 Integrator Importer 等工具导入。

import sensorsanalytics

# 初始化 ConsoleConsumer
consumer = sensorsanalytics.ConsoleConsumer()

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)
PYTHON

3.5. DefaultConsumer

通常用于导入小规模历史数据的场景。由于是网络直接发送数据,如果网络出现异常可能会导致数据重发或丢失,因此不要用在任何线上服务中。普通 Consumer,实现,逐条、同步的发送数据给接收服务器。

import sensorsanalytics

# 神策分析数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'
# 发送数据的超时时间,单位秒
SA_REQUEST_TIMEOUT = 1

# 初始化 DefaultConsumer
consumer = sensorsanalytics.DefaultConsumer(SA_SERVER_URL, SA_REQUEST_TIMEOUT)

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)
PYTHON

3.6. BatchConsumer

通常用于导入小规模历史数据,或者离线 / 旁路导入数据的场景。由于是网络直接发送数据,如果网络出现异常可能会导致数据重发或丢失,因此不要用在任何线上服务中。批量发送数据的 Consumer,当且仅当数据达到指定的量时,才将数据进行发送。

import sensorsanalytics

# 神策分析数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'
# 发送数据的超时时间,单位秒
SA_REQUEST_TIMEOUT = 1
# 当缓存的数据量达到参数值时,批量发送数据
SA_BULK_SIZE = 100

# 初始化 BatchConsumer
consumer = sensorsanalytics.BatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, SA_REQUEST_TIMEOUT)

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)

# 程序结束前调用 close() ,通知 Consumer 发送所有缓存数据
sa.close()
PYTHON

3.7. AsyncBatchConsumer

通常用于导入小规模历史数据。使用独立的线程进行数据发送,利用网络异步、批量发送数据的 Consumer。

import sensorsanalytics

# 神策分析数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'

# 初始化 AsyncBatchConsumer
consumer = sensorsanalytics.AsyncBatchConsumer(SA_SERVER_URL)

# 使用 Consumer 来构造 SensorsAnalytics 对象
sa = sensorsanalytics.SensorsAnalytics(consumer)

# 程序结束前调用 close() ,通知 Consumer 发送所有缓存数据
sa.close()
PYTHON

3.8. 其它设置

导入历史数据:默认情况下,神策会过滤发生时间比较久远数据(例如 10 天之前,具体取决于服务端设置),如果想导入历史数据,可以通过开启 Time Free,不受此限制。

# 使用 Consumer 来构造 SensorsAnalytics 对象时,开启 Time Free
sa = sensorsanalytics.SensorsAnalytics(consumer,enable_time_free = True)
PYTHON

4. API 接口

针对 API 接口的使用文档,参照基础 API 使用文档介绍