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 使用文档介绍。