@cherrystudio/分析-客户
樱桃工作室应用的分析客户SDK. 支持以自动缓冲和冲出来进行批量事件跟踪.
安装
npm install @cherrystudio/analytics-client
# or
pnpm add @cherrystudio/analytics-client
# or
yarn add @cherrystudio/analytics-client
快速启动
import { AnalyticsClient } from '@cherrystudio/analytics-client'
// Initialize the client
const analytics = new AnalyticsClient({
clientId: 'user-uuid-here',
channel: 'cherry-studio',
})
// Track token usage
analytics.trackTokenUsage({
provider: 'openai',
model: 'gpt-4',
input_tokens: 100,
output_tokens: 200,
})
// Drain within the shutdown budget before app exit
await analytics.destroy()
API 密码
构造选项
interface AnalyticsClientOptions {
/** Analytics service base URL (default: https://analytics.cherry-ai.com) */
baseUrl?: string
/** Client unique identifier (UUID) */
clientId: string
/** Channel/application name */
channel: string
/** Enable automatic batching (default: true) */
autoBatch?: boolean
/** Auto-flush threshold and maximum events per request (default: 10) */
batchSize?: number
/** Maximum queued events; newest events drop on overflow (default: 1000) */
maxQueueSize?: number
/** Queued plus active requests across all endpoints (default: 100), concurrency: 1 */
maxPendingRequests?: number
/** Maximum serialized bytes per event (default: 65536) */
maxEventBytes?: number
/** Maximum serialized bytes per event request (default: 262144) */
maxBatchBytes?: number
/** Batch flush interval in milliseconds (default: 5000) */
flushInterval?: number
/** Request timeout in milliseconds (default: 10000) */
timeout?: number
/** Custom fetch function (for Node.js or custom implementations) */
fetch?: typeof fetch
/** Retry/backoff settings; defaults to three retries */
retry?: RetryOptions
/** Additional request headers */
headers?: Record<string, string>
/** Called when an error occurs */
onError?: (error: Error) => void
}
方法
trackTokenUsage(data, timestamp?)
跟踪 AI 符号使用 .
提供者为 local-embedding,或者其输入和输出符号计数均为0,被忽略,不排队或发送到分析服务.
analytics.trackTokenUsage({
provider: 'openai', // AI provider name
model: 'gpt-4', // Model name
input_tokens: 100, // Input token count
output_tokens: 200, // Output token count
})
// With custom timestamp (for offline tracking)
analytics.trackTokenUsage(data, new Date('2025-01-15T10:30:00Z'))
track(eventType, data, timestamp?)
跟踪一个通用事件 。 用于自定义事件类型 。 数据得到验证
输入时被快照, 以及当前客户端的ID和事件时间 .
非 JSON 数据、 无效/ 未定义数据、 无效日期和超大小事件
个人通过 onError不给这批货下毒.
analytics.track('custom_event', {
action: 'button_click',
value: 42,
})
flush()
最多在请求中, 在呼叫开始时排队的模糊事件 batchSize 事件。 返回确认的合并计数,或 null 如果队列为空。 同步呼叫者共享活动冲出. 在冲出时添加的事件等待下一场冲出 .
const result = await analytics.flush()
// { success: true, count: 5 }
sendImmediate(eventType, data, timestamp?)
立即发送一个事件 不批量.
await analytics.sendImmediate('token_usage', {
provider: 'anthropic',
model: 'claude-3',
input_tokens: 50,
output_tokens: 150,
})
setClientId(clientId)
更新未来事件的客户端ID(如用户登录后). 排队事件
保留其原始身份; 不同身份分别发送
批发。 习惯 Client-Id 标题跟踪每个请求的身份.
analytics.setClientId('new-user-uuid')
getQueueSize()
在队列中获取当前待定事件的数量 .
const pending = analytics.getQueueSize()
destroy(options?)
关闭客户端,停止接受新工作,并等待所有终点和解.
默认是一个优雅的排水 总预算30秒,包括:
冷却和回击。 期满时,请求中止,其余数据为
本地丢弃。 结果报告终生交货计数器和 timedOut。 。 。 .
屡相召还同相允. 立即取消也可以
中断已经运行的优雅关闭.
const result = await analytics.destroy({ timeoutMs: 30000 })
// { acknowledgedEvents, discardedEvents, pendingEvents: 0, pendingRequests: 0, timedOut }
// Consent revocation: cancel in-flight requests and cooldowns, discard queued data.
await analytics.destroy({ flush: false })
撤销同意的申请必须使用 flush: false;仅仅取消
获取包装器无法中断 SDK 冷却 。 关机后, track()
拒绝报告通过 onError;即时/活动发送拒绝
承诺。 不重复使用已关闭的客户端 .
getDeliveryStats()
返回寿命的本地计数器 : acknowledgedEvents, (中文(简体) ), discardedEvents, (中文(简体) ),
pendingEvents (包括飞行中活动)和 pendingRequests活动
请求只帮助进行请求计数。 忽略的象征性事件不在此列.
discardedEvents 表示 SDK 不再保留事件; 模糊的网络
失败可能意味着服务器已经接受了它 。 这些柜台不是帐单
或服务器持续性保证. getQueueSize() 只计算已排队的批次事件.
实例
电子辅助
import { AnalyticsClient } from '@cherrystudio/analytics-client'
import { app } from 'electron'
const analytics = new AnalyticsClient({
clientId: getMachineId(),
channel: 'cherry-studio',
onError: (error) => console.error('Analytics error:', error),
})
// Track usage
analytics.trackTokenUsage({
provider: 'openai',
model: 'gpt-4',
input_tokens: 100,
output_tokens: 200,
})
// Flush on app quit
app.on('before-quit', async (event) => {
event.preventDefault()
await analytics.destroy()
app.exit()
})
有节点的节点.js
import { AnalyticsClient } from '@cherrystudio/analytics-client'
import fetch from 'node-fetch'
const analytics = new AnalyticsClient({
clientId: 'server-instance-id',
channel: 'cherryin-backend',
fetch: fetch as unknown as typeof globalThis.fetch,
})
禁用自定义
const analytics = new AnalyticsClient({
clientId: 'user-uuid',
channel: 'cherry-studio',
autoBatch: false, // Disable auto batching
})
// Manually send each event
await analytics.sendImmediate('token_usage', { ... })
自定义批次设置
const analytics = new AnalyticsClient({
clientId: 'user-uuid',
channel: 'cherry-studio',
batchSize: 50, // Flush when 50 events accumulated
flushInterval: 10000, // Or every 10 seconds
})
许可证
麻省理工学院
交货和重试限制
这个SDK提供了最佳的,内相遥测. 每批货最多可以
1 + retry.maxRetries 请求尝试(默认:共四次)。 一旦预算
已用尽,或发生不可弥补的错误,尝试的批次是: 丢弃, (中文(简体) ),
不放回队列中。 手册 flush() 拒绝; 自动冲出报告
结束 onError。失败的冲出 AnalyticsFlushError 带有 result
毕生送货柜台的快照 冲浪在初始时继续穿过其他批次
在报告第一次失败前快照; 一个错误批次无法屏蔽
数据背后。 在冲出时添加的事件等待下一场冲出 .
HTTP 408、429和5xx回复和支持的网络错误可通过
默认; 其他 HTTP 错误不是 . retryAllErrors 默认为 false。 。 。 .
Retry-After (秒或 HTTP 日期) 设置一个全客户端的冷却器
分批事件、即时事件和活动要求。 蝙蝠侠留在记忆中
在等待的时候,等待是不会减少尝试的. retry.maxDelay (默认)
30秒)的盖子只有指数回放;更长的服务器冷却被尊重,
包括在当前批次用完复试之后。 短暂的失败也
适用于后续批次。 HTTP 204 确认请求
没有JSON尸体, 并计算所有提交的事件 承认。 报告无效的HTTP答复机构
因为服务器可能已经接受了事件.
batchSize 是自动冲出阈值和最大请求批次
尺寸. maxQueueSize 默认为1,000起未决事件,不包括飞行中事件
批号。 完成后,最新事件将放弃,并通过 onError。 。 。 .
所有终点均采用单向请求道. maxPendingRequests 队列已加
活动请求( 默认 100); 立即/ 活动请求在溢出时被拒绝 .
批量冲出等待容量,而不是丢弃普通批量.
batchSize 财务报告和审定财务报表 maxBatchBytes 二者都制约了批量,以及 maxEventBytes
限制个别事件。 所有字节限制都是UTF-8序列大小.
destroy() 在总时间内排出被否决的有效批次
预算。 超时取消工作; 它不会绕过服务器冷却 。 呼叫者
离开前必须等待关闭。 待定的事件不保存到磁盘中 .
这些界限可以防止无限期队列重放, 但不能提供精确的一次 发送: 服务器接受后网络超时仍可导致限制 重试。 可靠的分解需要稳定的事件ID和服务器侧 一能为相. 失败/过多的事件不会持续到以后恢复.