sribd-analytics-sdk 0.1.1

Python SDK for SRIBD Analytics event ingestion

SRIBD Analytics Python SDK

Python 后端接入 analytics-service 事件采集接口的轻量 SDK。

安装

本地开发：

pip install -e /Users/dongbucheng/workspace/projects/sribd-analytics/analytics-python-sdk

作为 Git 依赖接入时，将仓库地址替换为实际地址：

pip install "sribd-analytics-sdk @ git+ssh://git.example.com/sribd-analytics.git#subdirectory=analytics-python-sdk"

环境变量

ANALYTICS_ENABLED=true
ANALYTICS_BASE_URL=http://127.0.0.1:18080
ANALYTICS_SOURCE_SYSTEM=aiplatform
ANALYTICS_INGEST_API_KEY=dev-aiplatform-key
ANALYTICS_TIMEOUT_SECONDS=3
ANALYTICS_STRICT=false

ANALYTICS_SOURCE_SYSTEM 仅支持：

• aiplatform
• aihub

ANALYTICS_STRICT=false 是推荐默认值。采集服务异常时 SDK 会返回失败结果并记录 warning，不阻塞主业务。需要让业务显式感知失败时再设置为 true。

快速使用

from sribd_analytics_sdk import AnalyticsClient

analytics = AnalyticsClient.from_env()

result = analytics.track(
    event_type="chat_completed",
    user_key=str(user.id),
    user_id=str(user.id),
    user_email=user.email,
    user_name=user.name,
    session_key=session_id,
    payload={
        "model": model_name,
        "prompt_tokens": 1200,
        "completion_tokens": 300,
    },
)

if not result.ok:
    logger.warning("analytics track failed: %s", result.error)

显式配置

from sribd_analytics_sdk import AnalyticsClient

analytics = AnalyticsClient(
    base_url="http://127.0.0.1:18080",
    source_system="aihub",
    api_key="dev-aihub-key",
    timeout_seconds=2,
)

SDK 会自动补齐：

• POST /v1/ingest/events
• X-API-Key
• schema_version=v1
• event_id
• occurred_at

base_url 可以传服务根地址，也可以传已经带 /v1 的 API 前缀；SDK 不会重复拼接 /v1。

前后端调用边界

浏览器前端不要直接使用该 SDK，也不要持有 ANALYTICS_INGEST_API_KEY。前端需要埋点时，应调用本系统已有 Python 后端接口，由 Python 后端使用 SDK 上报 analytics-service。

目标源配置示例

aiplatform 后端：

ANALYTICS_SOURCE_SYSTEM=aiplatform
ANALYTICS_INGEST_API_KEY=dev-aiplatform-key

aihub 后端：

ANALYTICS_SOURCE_SYSTEM=aihub
ANALYTICS_INGEST_API_KEY=dev-aihub-key

返回值

track() 返回 TrackResult：

TrackResult(
    ok=True,
    skipped=False,
    status_code=200,
    data={"code": 0, "message": "OK", "data": {...}},
    error=None,
)

关闭采集：

ANALYTICS_ENABLED=false

此时 track() 返回 ok=True, skipped=True，不会发起网络请求。