@longzai-intelligence-telemetry/core 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -0
- package/dist/index.d.mts +708 -0
- package/dist/index.d.ts +709 -0
- package/dist/index.js +1 -0
- package/dist/index.mjs +1 -0
- package/package.json +44 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,709 @@
|
|
|
1
|
+
import "./rolldown-runtime-B7xKLgmA.js";
|
|
2
|
+
import * as z from "zod";
|
|
3
|
+
//#region src/contract.schema.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* 事件名合法 pattern(snake_case,2-64 字符)
|
|
6
|
+
*/
|
|
7
|
+
declare const TELEMETRY_EVENT_NAME_PATTERN: RegExp;
|
|
8
|
+
/**
|
|
9
|
+
* 单条日志 message 上限字符数
|
|
10
|
+
*/
|
|
11
|
+
declare const TELEMETRY_MESSAGE_MAX_LENGTH = 4000;
|
|
12
|
+
/**
|
|
13
|
+
* 单条日志 stack 上限字符数
|
|
14
|
+
*/
|
|
15
|
+
declare const TELEMETRY_STACK_MAX_LENGTH = 8000;
|
|
16
|
+
/**
|
|
17
|
+
* 单批条目上限
|
|
18
|
+
*/
|
|
19
|
+
declare const TELEMETRY_BATCH_MAX_ENTRIES = 100;
|
|
20
|
+
/**
|
|
21
|
+
* 时钟偏差标记阈值(客户端条目时间超前服务器时钟该毫秒数即落 clock_anomaly 标记)
|
|
22
|
+
*/
|
|
23
|
+
declare const TELEMETRY_CLOCK_ANOMALY_THRESHOLD_MS: number;
|
|
24
|
+
/**
|
|
25
|
+
* 遥测公开摄取端点路径(客户端传输与服务端路由共同消费)
|
|
26
|
+
*/
|
|
27
|
+
declare const TELEMETRY_ENDPOINTS: {
|
|
28
|
+
/**
|
|
29
|
+
* 事件批量摄取
|
|
30
|
+
*/
|
|
31
|
+
readonly trackingEventsBatch: '/telemetry/tracking-events/batch';
|
|
32
|
+
/**
|
|
33
|
+
* 日志批量摄取
|
|
34
|
+
*/
|
|
35
|
+
readonly clientLogsBatch: '/telemetry/client-logs/batch';
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* 批次上下文 schema
|
|
39
|
+
*/
|
|
40
|
+
declare const batchContextSchema: z.ZodObject<{
|
|
41
|
+
platform: z.ZodEnum<{
|
|
42
|
+
android: "android";
|
|
43
|
+
harmony: "harmony";
|
|
44
|
+
ios: "ios";
|
|
45
|
+
}>;
|
|
46
|
+
appVersion: z.ZodString;
|
|
47
|
+
sessionId: z.ZodString;
|
|
48
|
+
deviceId: z.ZodString;
|
|
49
|
+
buildChannel: z.ZodString;
|
|
50
|
+
userId: z.ZodNullable<z.ZodString>;
|
|
51
|
+
batchedAt: z.ZodNumber;
|
|
52
|
+
}, z.core.$strip>;
|
|
53
|
+
/**
|
|
54
|
+
* 事件条目 schema
|
|
55
|
+
*/
|
|
56
|
+
declare const eventEntrySchema: z.ZodObject<{
|
|
57
|
+
name: z.ZodString;
|
|
58
|
+
properties: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
|
|
59
|
+
occurredAt: z.ZodNumber;
|
|
60
|
+
}, z.core.$strip>;
|
|
61
|
+
/**
|
|
62
|
+
* 日志条目 schema
|
|
63
|
+
*/
|
|
64
|
+
declare const logEntrySchema: z.ZodObject<{
|
|
65
|
+
level: z.ZodEnum<{
|
|
66
|
+
debug: "debug";
|
|
67
|
+
error: "error";
|
|
68
|
+
fatal: "fatal";
|
|
69
|
+
info: "info";
|
|
70
|
+
warn: "warn";
|
|
71
|
+
}>;
|
|
72
|
+
message: z.ZodString;
|
|
73
|
+
stack: z.ZodString;
|
|
74
|
+
tag: z.ZodString;
|
|
75
|
+
occurredAt: z.ZodNumber;
|
|
76
|
+
}, z.core.$strip>;
|
|
77
|
+
/**
|
|
78
|
+
* 事件批量上报体 schema(批内至少一条、至多批上限)
|
|
79
|
+
*/
|
|
80
|
+
declare const eventBatchSchema: z.ZodObject<{
|
|
81
|
+
context: z.ZodObject<{
|
|
82
|
+
platform: z.ZodEnum<{
|
|
83
|
+
android: "android";
|
|
84
|
+
harmony: "harmony";
|
|
85
|
+
ios: "ios";
|
|
86
|
+
}>;
|
|
87
|
+
appVersion: z.ZodString;
|
|
88
|
+
sessionId: z.ZodString;
|
|
89
|
+
deviceId: z.ZodString;
|
|
90
|
+
buildChannel: z.ZodString;
|
|
91
|
+
userId: z.ZodNullable<z.ZodString>;
|
|
92
|
+
batchedAt: z.ZodNumber;
|
|
93
|
+
}, z.core.$strip>;
|
|
94
|
+
events: z.ZodArray<z.ZodObject<{
|
|
95
|
+
name: z.ZodString;
|
|
96
|
+
properties: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
|
|
97
|
+
occurredAt: z.ZodNumber;
|
|
98
|
+
}, z.core.$strip>>;
|
|
99
|
+
}, z.core.$strip>;
|
|
100
|
+
/**
|
|
101
|
+
* 日志批量上报体 schema(批内至少一条、至多批上限)
|
|
102
|
+
*/
|
|
103
|
+
declare const logBatchSchema: z.ZodObject<{
|
|
104
|
+
context: z.ZodObject<{
|
|
105
|
+
platform: z.ZodEnum<{
|
|
106
|
+
android: "android";
|
|
107
|
+
harmony: "harmony";
|
|
108
|
+
ios: "ios";
|
|
109
|
+
}>;
|
|
110
|
+
appVersion: z.ZodString;
|
|
111
|
+
sessionId: z.ZodString;
|
|
112
|
+
deviceId: z.ZodString;
|
|
113
|
+
buildChannel: z.ZodString;
|
|
114
|
+
userId: z.ZodNullable<z.ZodString>;
|
|
115
|
+
batchedAt: z.ZodNumber;
|
|
116
|
+
}, z.core.$strip>;
|
|
117
|
+
logs: z.ZodArray<z.ZodObject<{
|
|
118
|
+
level: z.ZodEnum<{
|
|
119
|
+
debug: "debug";
|
|
120
|
+
error: "error";
|
|
121
|
+
fatal: "fatal";
|
|
122
|
+
info: "info";
|
|
123
|
+
warn: "warn";
|
|
124
|
+
}>;
|
|
125
|
+
message: z.ZodString;
|
|
126
|
+
stack: z.ZodString;
|
|
127
|
+
tag: z.ZodString;
|
|
128
|
+
occurredAt: z.ZodNumber;
|
|
129
|
+
}, z.core.$strip>>;
|
|
130
|
+
}, z.core.$strip>;
|
|
131
|
+
/**
|
|
132
|
+
* 事件批量上报体的契约解析类型(与 types.ts 的 TelemetryEventBatch 结构对齐)
|
|
133
|
+
*/
|
|
134
|
+
type EventBatchInput = z.infer<typeof eventBatchSchema>;
|
|
135
|
+
/**
|
|
136
|
+
* 日志批量上报体的契约解析类型(与 types.ts 的 TelemetryLogBatch 结构对齐)
|
|
137
|
+
*/
|
|
138
|
+
type LogBatchInput = z.infer<typeof logBatchSchema>;
|
|
139
|
+
//#endregion
|
|
140
|
+
//#region src/consent-state.utils.d.ts
|
|
141
|
+
/**
|
|
142
|
+
* 分级同意状态机(O-2 推荐口径先行:崩溃/错误通道默认开、行为事件 opt-in、关闭即 purge 由服务层承接)
|
|
143
|
+
*/
|
|
144
|
+
/**
|
|
145
|
+
* 分级同意状态
|
|
146
|
+
*/
|
|
147
|
+
type TelemetryConsent = {
|
|
148
|
+
/**
|
|
149
|
+
* 崩溃/错误通道(封闭字段、无 PII):默认开启
|
|
150
|
+
*/
|
|
151
|
+
crashChannelEnabled: boolean;
|
|
152
|
+
/**
|
|
153
|
+
* 行为事件通道:opt-in 默认关闭
|
|
154
|
+
*/
|
|
155
|
+
behavioralEventsEnabled: boolean;
|
|
156
|
+
};
|
|
157
|
+
/**
|
|
158
|
+
* 默认同意状态(O-2 推荐口径;终裁前为配置可切换的缺省值)
|
|
159
|
+
*/
|
|
160
|
+
declare const DEFAULT_TELEMETRY_CONSENT: TelemetryConsent;
|
|
161
|
+
/**
|
|
162
|
+
* 同意变更指令
|
|
163
|
+
*/
|
|
164
|
+
type TelemetryConsentChange = {
|
|
165
|
+
/**
|
|
166
|
+
* 变更崩溃/错误通道开关
|
|
167
|
+
*/
|
|
168
|
+
kind: 'crash-channel';
|
|
169
|
+
/**
|
|
170
|
+
* 目标开关值
|
|
171
|
+
*/
|
|
172
|
+
enabled: boolean;
|
|
173
|
+
} | {
|
|
174
|
+
/**
|
|
175
|
+
* 变更行为事件通道开关
|
|
176
|
+
*/
|
|
177
|
+
kind: 'behavioral-events';
|
|
178
|
+
/**
|
|
179
|
+
* 目标开关值
|
|
180
|
+
*/
|
|
181
|
+
enabled: boolean;
|
|
182
|
+
};
|
|
183
|
+
/**
|
|
184
|
+
* 应用同意变更(返回新对象,原状态不可变)
|
|
185
|
+
*
|
|
186
|
+
* @param consent - 当前同意状态
|
|
187
|
+
* @param change - 变更指令
|
|
188
|
+
* @returns 新同意状态
|
|
189
|
+
*/
|
|
190
|
+
declare function applyConsentChange(consent: TelemetryConsent, change: TelemetryConsentChange): TelemetryConsent;
|
|
191
|
+
/**
|
|
192
|
+
* 上行通道标识(同意门控的粒度)
|
|
193
|
+
*/
|
|
194
|
+
type TelemetryUploadChannel = 'crash-reporting' | 'behavioral-events';
|
|
195
|
+
/**
|
|
196
|
+
* 判断通道当前是否允许上行
|
|
197
|
+
*
|
|
198
|
+
* @param consent - 同意状态
|
|
199
|
+
* @param channel - 上行通道
|
|
200
|
+
* @returns 允许上行返回 true
|
|
201
|
+
*/
|
|
202
|
+
declare function isChannelUploadAllowed(consent: TelemetryConsent, channel: TelemetryUploadChannel): boolean;
|
|
203
|
+
//#endregion
|
|
204
|
+
//#region src/types.d.ts
|
|
205
|
+
/**
|
|
206
|
+
* 遥测体系数据模型(L0 纯逻辑,语义规格源自 watch 遥测 TelemetryTypes.ets,TS 重写)
|
|
207
|
+
*/
|
|
208
|
+
/**
|
|
209
|
+
* 遥测平台标识(批次上下文 platform 字段取值域)
|
|
210
|
+
*/
|
|
211
|
+
type TelemetryPlatform = 'ios' | 'android' | 'harmony';
|
|
212
|
+
/**
|
|
213
|
+
* 日志级别(上行时 FATAL 并入 ERROR,本地保留原级——watch 日志通道语义)
|
|
214
|
+
*/
|
|
215
|
+
type TelemetryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
|
|
216
|
+
/**
|
|
217
|
+
* 遥测双通道(事件通道 / 日志通道)
|
|
218
|
+
*/
|
|
219
|
+
type TelemetryChannelKind = 'event' | 'log';
|
|
220
|
+
/**
|
|
221
|
+
* 事件属性值取值域(封闭字段集的值形态,禁止对象/数组等复合值)
|
|
222
|
+
*/
|
|
223
|
+
type TelemetryPropertyValue = string | number | boolean | null;
|
|
224
|
+
/**
|
|
225
|
+
* 事件条目
|
|
226
|
+
*/
|
|
227
|
+
type TelemetryEventEntry = {
|
|
228
|
+
/**
|
|
229
|
+
* 事件名(snake_case,须经事件目录登记;清洗失效落哨兵名 invalid_event_name)
|
|
230
|
+
*/
|
|
231
|
+
name: string;
|
|
232
|
+
/**
|
|
233
|
+
* 事件属性(封闭字段集:键须在采集点声明的白名单内,清洗时剔除白名单外键)
|
|
234
|
+
*/
|
|
235
|
+
properties: Readonly<Record<string, TelemetryPropertyValue>>;
|
|
236
|
+
/**
|
|
237
|
+
* 事件发生时间(epoch 毫秒)
|
|
238
|
+
*/
|
|
239
|
+
occurredAt: number;
|
|
240
|
+
};
|
|
241
|
+
/**
|
|
242
|
+
* 日志条目
|
|
243
|
+
*/
|
|
244
|
+
type TelemetryLogEntry = {
|
|
245
|
+
/**
|
|
246
|
+
* 日志级别
|
|
247
|
+
*/
|
|
248
|
+
level: TelemetryLogLevel;
|
|
249
|
+
/**
|
|
250
|
+
* 日志消息(清洗契约 ≤4000 字符)
|
|
251
|
+
*/
|
|
252
|
+
message: string;
|
|
253
|
+
/**
|
|
254
|
+
* 关联堆栈(清洗契约 ≤8000 字符,可为空字符串)
|
|
255
|
+
*/
|
|
256
|
+
stack: string;
|
|
257
|
+
/**
|
|
258
|
+
* 来源标签(模块/页面名,用于日志治理)
|
|
259
|
+
*/
|
|
260
|
+
tag: string;
|
|
261
|
+
/**
|
|
262
|
+
* 日志发生时间(epoch 毫秒)
|
|
263
|
+
*/
|
|
264
|
+
occurredAt: number;
|
|
265
|
+
};
|
|
266
|
+
/**
|
|
267
|
+
* 批次上下文(随每批上报,服务端据此区分平台与会话)
|
|
268
|
+
*/
|
|
269
|
+
type TelemetryBatchContext = {
|
|
270
|
+
/**
|
|
271
|
+
* 客户端平台
|
|
272
|
+
*/
|
|
273
|
+
platform: TelemetryPlatform;
|
|
274
|
+
/**
|
|
275
|
+
* 应用版本号
|
|
276
|
+
*/
|
|
277
|
+
appVersion: string;
|
|
278
|
+
/**
|
|
279
|
+
* 会话标识(单次启动内不变)
|
|
280
|
+
*/
|
|
281
|
+
sessionId: string;
|
|
282
|
+
/**
|
|
283
|
+
* 安装级随机设备标识(非用户标识)
|
|
284
|
+
*/
|
|
285
|
+
deviceId: string;
|
|
286
|
+
/**
|
|
287
|
+
* 构建渠道(如正式/测试)
|
|
288
|
+
*/
|
|
289
|
+
buildChannel: string;
|
|
290
|
+
/**
|
|
291
|
+
* 登录用户标识(未登录为 null;受同意门约束可选注入)
|
|
292
|
+
*/
|
|
293
|
+
userId: string | null;
|
|
294
|
+
/**
|
|
295
|
+
* 批次组装时间(epoch 毫秒)
|
|
296
|
+
*/
|
|
297
|
+
batchedAt: number;
|
|
298
|
+
};
|
|
299
|
+
/**
|
|
300
|
+
* 事件批量上报体
|
|
301
|
+
*/
|
|
302
|
+
type TelemetryEventBatch = {
|
|
303
|
+
/**
|
|
304
|
+
* 批次上下文
|
|
305
|
+
*/
|
|
306
|
+
context: TelemetryBatchContext;
|
|
307
|
+
/**
|
|
308
|
+
* 事件条目集合(批上限 100)
|
|
309
|
+
*/
|
|
310
|
+
events: readonly TelemetryEventEntry[];
|
|
311
|
+
};
|
|
312
|
+
/**
|
|
313
|
+
* 日志批量上报体
|
|
314
|
+
*/
|
|
315
|
+
type TelemetryLogBatch = {
|
|
316
|
+
/**
|
|
317
|
+
* 批次上下文
|
|
318
|
+
*/
|
|
319
|
+
context: TelemetryBatchContext;
|
|
320
|
+
/**
|
|
321
|
+
* 日志条目集合(批上限 100)
|
|
322
|
+
*/
|
|
323
|
+
logs: readonly TelemetryLogEntry[];
|
|
324
|
+
};
|
|
325
|
+
//#endregion
|
|
326
|
+
//#region src/delivery-profiles.d.ts
|
|
327
|
+
/**
|
|
328
|
+
* 递送档位标识
|
|
329
|
+
*/
|
|
330
|
+
type TelemetryDeliveryMode = 'lossless' | 'balanced' | 'lite';
|
|
331
|
+
/**
|
|
332
|
+
* 递送档位参数面
|
|
333
|
+
*/
|
|
334
|
+
type TelemetryDeliveryProfile = {
|
|
335
|
+
/**
|
|
336
|
+
* 档位标识
|
|
337
|
+
*/
|
|
338
|
+
mode: TelemetryDeliveryMode;
|
|
339
|
+
/**
|
|
340
|
+
* 持久 outbox 为数据真源(进程重启续传);false 表示仅内存缓冲
|
|
341
|
+
*/
|
|
342
|
+
persistentOutbox: boolean;
|
|
343
|
+
/**
|
|
344
|
+
* 事件内存缓冲上限(内存档溢出丢最旧)
|
|
345
|
+
*/
|
|
346
|
+
eventBufferLimit: number;
|
|
347
|
+
/**
|
|
348
|
+
* 日志内存缓冲上限
|
|
349
|
+
*/
|
|
350
|
+
logBufferLimit: number;
|
|
351
|
+
/**
|
|
352
|
+
* 单轮发送链最大批数(失败冷却前的批次数上限)
|
|
353
|
+
*/
|
|
354
|
+
maxBatchesPerRun: number;
|
|
355
|
+
/**
|
|
356
|
+
* 失败冷却毫秒数
|
|
357
|
+
*/
|
|
358
|
+
failureCooldownMs: number;
|
|
359
|
+
/**
|
|
360
|
+
* 定时冲刷间隔毫秒数
|
|
361
|
+
*/
|
|
362
|
+
flushIntervalMs: number;
|
|
363
|
+
/**
|
|
364
|
+
* 日志远程镜像最低级别(低于该级别不上行)
|
|
365
|
+
*/
|
|
366
|
+
remoteLogLevelThreshold: TelemetryLogLevel;
|
|
367
|
+
/**
|
|
368
|
+
* INFO 组提交延迟毫秒数(lossless 削写盘 I/O;0 表示即时)
|
|
369
|
+
*/
|
|
370
|
+
infoCommitDelayMs: number;
|
|
371
|
+
};
|
|
372
|
+
/**
|
|
373
|
+
* lossless 无损持久档(默认):outbox 写穿落库、单轮 30 批、失败冷却 5 秒
|
|
374
|
+
*/
|
|
375
|
+
declare const LOSSLESS_DELIVERY_PROFILE: TelemetryDeliveryProfile;
|
|
376
|
+
/**
|
|
377
|
+
* balanced 均衡档:现行内存策略(缓冲 200/1000、单轮 3 批、冷却 30 秒)
|
|
378
|
+
*/
|
|
379
|
+
declare const BALANCED_DELIVERY_PROFILE: TelemetryDeliveryProfile;
|
|
380
|
+
/**
|
|
381
|
+
* lite 轻量档:仅 WARN+ 远程镜像、缓冲 100/300、冷却 60 秒
|
|
382
|
+
*/
|
|
383
|
+
declare const LITE_DELIVERY_PROFILE: TelemetryDeliveryProfile;
|
|
384
|
+
/**
|
|
385
|
+
* 默认递送档位(lossless——watch issues/0394 处置口径)
|
|
386
|
+
*/
|
|
387
|
+
declare const DEFAULT_DELIVERY_MODE: TelemetryDeliveryMode;
|
|
388
|
+
/**
|
|
389
|
+
* 按档位标识取参数面
|
|
390
|
+
*
|
|
391
|
+
* @param mode - 档位标识
|
|
392
|
+
* @returns 对应档位参数面
|
|
393
|
+
*/
|
|
394
|
+
declare function getDeliveryProfile(mode: TelemetryDeliveryMode): TelemetryDeliveryProfile;
|
|
395
|
+
/**
|
|
396
|
+
* 归一持久化读取的档位值(非法值回落 lossless,防毒配置)
|
|
397
|
+
*
|
|
398
|
+
* @param raw - 持久化读取的原始字符串
|
|
399
|
+
* @returns 合法档位标识
|
|
400
|
+
*/
|
|
401
|
+
declare function normalizeDeliveryMode(raw: string): TelemetryDeliveryMode;
|
|
402
|
+
//#endregion
|
|
403
|
+
//#region src/queue-state.utils.d.ts
|
|
404
|
+
/**
|
|
405
|
+
* 发送冷却状态(失败后的退避门控)
|
|
406
|
+
*/
|
|
407
|
+
type TelemetryCooldownState = {
|
|
408
|
+
/**
|
|
409
|
+
* 冷却截止时间(epoch 毫秒;此前禁止发送尝试)
|
|
410
|
+
*/
|
|
411
|
+
cooldownUntilMs: number;
|
|
412
|
+
};
|
|
413
|
+
/**
|
|
414
|
+
* 初始冷却状态(无冷却)
|
|
415
|
+
*/
|
|
416
|
+
declare const INITIAL_COOLDOWN_STATE: TelemetryCooldownState;
|
|
417
|
+
/**
|
|
418
|
+
* 判断当前时刻是否允许发送尝试
|
|
419
|
+
*
|
|
420
|
+
* @param state - 冷却状态
|
|
421
|
+
* @param nowMs - 当前时间(epoch 毫秒)
|
|
422
|
+
* @returns 冷却到期返回 true
|
|
423
|
+
*/
|
|
424
|
+
declare function shouldAttemptSend(state: TelemetryCooldownState, nowMs: number): boolean;
|
|
425
|
+
/**
|
|
426
|
+
* 登记发送失败(注册冷却;不回退已有更晚的截止时间)
|
|
427
|
+
*
|
|
428
|
+
* @param state - 当前冷却状态
|
|
429
|
+
* @param nowMs - 失败发生时间(epoch 毫秒)
|
|
430
|
+
* @param cooldownMs - 冷却时长毫秒
|
|
431
|
+
* @returns 新冷却状态
|
|
432
|
+
*/
|
|
433
|
+
declare function registerSendFailure(state: TelemetryCooldownState, nowMs: number, cooldownMs: number): TelemetryCooldownState;
|
|
434
|
+
/**
|
|
435
|
+
* 登记发送成功(清除冷却)
|
|
436
|
+
*
|
|
437
|
+
* @returns 无冷却的初始状态
|
|
438
|
+
*/
|
|
439
|
+
declare function registerSendSuccess(): TelemetryCooldownState;
|
|
440
|
+
/**
|
|
441
|
+
* outbox 记录(行号 + 通道 + 条目载荷;存储端口装载返回的形态)
|
|
442
|
+
*
|
|
443
|
+
* @typeParam TEntry - outbox 条目载荷类型(事件条目或日志条目)
|
|
444
|
+
*/
|
|
445
|
+
type OutboxRecord<TEntry> = {
|
|
446
|
+
/**
|
|
447
|
+
* outbox 自增行号(有序装载依据)
|
|
448
|
+
*/
|
|
449
|
+
id: number;
|
|
450
|
+
/**
|
|
451
|
+
* 所属通道
|
|
452
|
+
*/
|
|
453
|
+
channel: TelemetryChannelKind;
|
|
454
|
+
/**
|
|
455
|
+
* 条目载荷
|
|
456
|
+
*/
|
|
457
|
+
entry: TEntry;
|
|
458
|
+
};
|
|
459
|
+
/**
|
|
460
|
+
* 事件批量装配结果
|
|
461
|
+
*/
|
|
462
|
+
type EventBatchAssembly = {
|
|
463
|
+
/**
|
|
464
|
+
* 装配完成的批量上报体
|
|
465
|
+
*/
|
|
466
|
+
batch: TelemetryEventBatch;
|
|
467
|
+
/**
|
|
468
|
+
* 本批包含的 outbox 行号(成功后据此删行)
|
|
469
|
+
*/
|
|
470
|
+
recordIds: number[];
|
|
471
|
+
};
|
|
472
|
+
/**
|
|
473
|
+
* 日志批量装配结果
|
|
474
|
+
*/
|
|
475
|
+
type LogBatchAssembly = {
|
|
476
|
+
/**
|
|
477
|
+
* 装配完成的批量上报体
|
|
478
|
+
*/
|
|
479
|
+
batch: TelemetryLogBatch;
|
|
480
|
+
/**
|
|
481
|
+
* 本批包含的 outbox 行号
|
|
482
|
+
*/
|
|
483
|
+
recordIds: number[];
|
|
484
|
+
};
|
|
485
|
+
/**
|
|
486
|
+
* 装配事件批量(条目经清洗:事件名 pattern 失效落哨兵名)
|
|
487
|
+
*
|
|
488
|
+
* @param context - 批次上下文
|
|
489
|
+
* @param records - 按行号序装载的 outbox 记录
|
|
490
|
+
* @param maxEntries - 单批上限
|
|
491
|
+
* @returns 装配结果(批量体 + 行号清单)
|
|
492
|
+
*/
|
|
493
|
+
declare function assembleEventBatch(context: TelemetryBatchContext, records: readonly OutboxRecord<TelemetryEventEntry>[], maxEntries: number): EventBatchAssembly;
|
|
494
|
+
/**
|
|
495
|
+
* 装配日志批量(FATAL 并入 ERROR 上行;message/stack 经长度契约清洗)
|
|
496
|
+
*
|
|
497
|
+
* @param context - 批次上下文
|
|
498
|
+
* @param records - 按行号序装载的 outbox 记录
|
|
499
|
+
* @param maxEntries - 单批上限
|
|
500
|
+
* @returns 装配结果(批量体 + 行号清单)
|
|
501
|
+
*/
|
|
502
|
+
declare function assembleLogBatch(context: TelemetryBatchContext, records: readonly OutboxRecord<TelemetryLogEntry>[], maxEntries: number): LogBatchAssembly;
|
|
503
|
+
//#endregion
|
|
504
|
+
//#region src/send-classification.utils.d.ts
|
|
505
|
+
/**
|
|
506
|
+
* 发送结果三态分类(success / retryable / rejected,带成因枚举)
|
|
507
|
+
*
|
|
508
|
+
* 成因枚举自第一版即具备——watch issues/0444 教训(failed 无成因区分 × -1 哨兵语义缺口)。
|
|
509
|
+
* 状态码语义与服务端摄取路由对齐:408/429/5xx 可重试,其余 4xx 拒绝(防毒批无限重试)。
|
|
510
|
+
*/
|
|
511
|
+
/**
|
|
512
|
+
* 发送结果三态
|
|
513
|
+
*/
|
|
514
|
+
type TelemetrySendOutcome = 'success' | 'retryable' | 'rejected';
|
|
515
|
+
/**
|
|
516
|
+
* 可重试失败成因
|
|
517
|
+
*/
|
|
518
|
+
type TelemetryRetryableCause = 'timeout' | 'rate-limited' | 'server-error' | 'network-error';
|
|
519
|
+
/**
|
|
520
|
+
* 拒绝失败成因(载荷被服务端判定违例,重试无意义)
|
|
521
|
+
*/
|
|
522
|
+
type TelemetryRejectedCause = 'client-rejected';
|
|
523
|
+
/**
|
|
524
|
+
* 发送结果(success 无成因;失败必带成因枚举)
|
|
525
|
+
*/
|
|
526
|
+
type TelemetrySendResult = {
|
|
527
|
+
outcome: 'success';
|
|
528
|
+
} | {
|
|
529
|
+
outcome: 'retryable';
|
|
530
|
+
cause: TelemetryRetryableCause;
|
|
531
|
+
} | {
|
|
532
|
+
outcome: 'rejected';
|
|
533
|
+
cause: TelemetryRejectedCause;
|
|
534
|
+
};
|
|
535
|
+
/**
|
|
536
|
+
* 按 HTTP 状态码分类发送结果
|
|
537
|
+
*
|
|
538
|
+
* @param status - HTTP 状态码
|
|
539
|
+
* @returns 三态结果(每次返回新对象,调用方持有安全)
|
|
540
|
+
*/
|
|
541
|
+
declare function classifyHttpStatus(status: number): TelemetrySendResult;
|
|
542
|
+
/**
|
|
543
|
+
* 传输层失败分类(网络异常/超时中断等无状态码场景,一律可重试)
|
|
544
|
+
*
|
|
545
|
+
* @returns 网络错误成因的可重试结果
|
|
546
|
+
*/
|
|
547
|
+
declare function classifyTransportFailure(): TelemetrySendResult;
|
|
548
|
+
//#endregion
|
|
549
|
+
//#region src/ports.d.ts
|
|
550
|
+
/**
|
|
551
|
+
* outbox 存储记录(装载返回形态)
|
|
552
|
+
*/
|
|
553
|
+
type StoredTelemetryRecord = {
|
|
554
|
+
/**
|
|
555
|
+
* outbox 自增行号(有序装载依据)
|
|
556
|
+
*/
|
|
557
|
+
id: number;
|
|
558
|
+
/**
|
|
559
|
+
* 所属通道
|
|
560
|
+
*/
|
|
561
|
+
channel: TelemetryChannelKind;
|
|
562
|
+
/**
|
|
563
|
+
* 已清洗的条目载荷
|
|
564
|
+
*/
|
|
565
|
+
entry: TelemetryEventEntry | TelemetryLogEntry;
|
|
566
|
+
};
|
|
567
|
+
/**
|
|
568
|
+
* 持久存储端口(lossless outbox 的载体;RN 壳以 op-sqlite 实现,鸿蒙壳同栈)
|
|
569
|
+
*/
|
|
570
|
+
type TelemetryStoragePort = {
|
|
571
|
+
/**
|
|
572
|
+
* 追加条目(返回分配的行号)
|
|
573
|
+
*/
|
|
574
|
+
append(channel: TelemetryChannelKind, entry: TelemetryEventEntry | TelemetryLogEntry): Promise<number>;
|
|
575
|
+
/**
|
|
576
|
+
* 按行号序装载一批(至多 maxEntries 条)
|
|
577
|
+
*/
|
|
578
|
+
loadBatch(channel: TelemetryChannelKind, maxEntries: number): Promise<StoredTelemetryRecord[]>;
|
|
579
|
+
/**
|
|
580
|
+
* 删除已完成行(成功才删行——至少一次语义)
|
|
581
|
+
*/
|
|
582
|
+
deleteRecords(channel: TelemetryChannelKind, ids: readonly number[]): Promise<void>;
|
|
583
|
+
/**
|
|
584
|
+
* 清空全部通道(同意关闭即 purge)
|
|
585
|
+
*/
|
|
586
|
+
purgeAll(): Promise<void>;
|
|
587
|
+
/**
|
|
588
|
+
* 统计行数(配额驱逐与状态呈现)
|
|
589
|
+
*/
|
|
590
|
+
count(channel: TelemetryChannelKind): Promise<number>;
|
|
591
|
+
};
|
|
592
|
+
/**
|
|
593
|
+
* 时钟端口(测试可控时间注入)
|
|
594
|
+
*/
|
|
595
|
+
type TelemetryClockPort = {
|
|
596
|
+
/**
|
|
597
|
+
* 当前时间(epoch 毫秒)
|
|
598
|
+
*/
|
|
599
|
+
nowMs(): number;
|
|
600
|
+
};
|
|
601
|
+
/**
|
|
602
|
+
* 传输端口(裸传输纪律:不走业务 http 客户端、不带鉴权头、短超时)
|
|
603
|
+
*/
|
|
604
|
+
type TelemetryTransportPort = {
|
|
605
|
+
/**
|
|
606
|
+
* 发送事件批量
|
|
607
|
+
*/
|
|
608
|
+
sendEventBatch(batch: TelemetryEventBatch): Promise<TelemetrySendResult>;
|
|
609
|
+
/**
|
|
610
|
+
* 发送日志批量
|
|
611
|
+
*/
|
|
612
|
+
sendLogBatch(batch: TelemetryLogBatch): Promise<TelemetrySendResult>;
|
|
613
|
+
};
|
|
614
|
+
/**
|
|
615
|
+
* 原生崩溃标记端口(过渡期原生崩溃面:运行标记写入/清除与异常退出检测;真原生捕获属 O6)
|
|
616
|
+
*/
|
|
617
|
+
type NativeCrashMarkerPort = {
|
|
618
|
+
/**
|
|
619
|
+
* 会话启动写运行标记
|
|
620
|
+
*/
|
|
621
|
+
markSessionStart(): Promise<void>;
|
|
622
|
+
/**
|
|
623
|
+
* 正常退出清标记
|
|
624
|
+
*/
|
|
625
|
+
markSessionEnd(): Promise<void>;
|
|
626
|
+
/**
|
|
627
|
+
* 检测上次会话是否异常退出(残留运行标记即判定)
|
|
628
|
+
*/
|
|
629
|
+
detectPreviousAbnormalExit(): Promise<boolean>;
|
|
630
|
+
};
|
|
631
|
+
/**
|
|
632
|
+
* 系统观测事件种类(鸿蒙 HiAppEvent 故障事件映射;iOS/Android 壳按平台能力映射)
|
|
633
|
+
*/
|
|
634
|
+
type SystemObservedEventKind = 'js-error' | 'app-freeze' | 'native-crash';
|
|
635
|
+
/**
|
|
636
|
+
* 系统观测事件(L2 系统事件通道递入 JS 侧的统一形态)
|
|
637
|
+
*/
|
|
638
|
+
type SystemObservedEvent = {
|
|
639
|
+
/**
|
|
640
|
+
* 系统事件种类
|
|
641
|
+
*/
|
|
642
|
+
kind: SystemObservedEventKind;
|
|
643
|
+
/**
|
|
644
|
+
* 事件名(catalog 登记)
|
|
645
|
+
*/
|
|
646
|
+
name: string;
|
|
647
|
+
/**
|
|
648
|
+
* 事件消息
|
|
649
|
+
*/
|
|
650
|
+
message: string;
|
|
651
|
+
/**
|
|
652
|
+
* 原始堆栈
|
|
653
|
+
*/
|
|
654
|
+
stack: string;
|
|
655
|
+
/**
|
|
656
|
+
* 发生时间(epoch 毫秒)
|
|
657
|
+
*/
|
|
658
|
+
occurredAt: number;
|
|
659
|
+
};
|
|
660
|
+
/**
|
|
661
|
+
* 系统事件通道端口(鸿蒙壳以 ArkTSTurboModule 订阅 HiAppEvent 实现)
|
|
662
|
+
*/
|
|
663
|
+
type SystemEventChannelPort = {
|
|
664
|
+
/**
|
|
665
|
+
* 订阅系统事件(返回退订函数)
|
|
666
|
+
*/
|
|
667
|
+
subscribe(listener: (event: SystemObservedEvent) => void): () => void;
|
|
668
|
+
};
|
|
669
|
+
//#endregion
|
|
670
|
+
//#region src/sanitizer.utils.d.ts
|
|
671
|
+
/**
|
|
672
|
+
* 截断尾标记(截断后仍占用上限长度内字符,保证总长不超限)
|
|
673
|
+
*/
|
|
674
|
+
declare const TELEMETRY_TRUNCATION_TAIL = "…[truncated]";
|
|
675
|
+
/**
|
|
676
|
+
* 非法事件名回落哨兵名(服务端 pattern 校验的第二道防线)
|
|
677
|
+
*/
|
|
678
|
+
declare const INVALID_EVENT_NAME_SENTINEL = "invalid_event_name";
|
|
679
|
+
/**
|
|
680
|
+
* 清洗日志消息(≤4000 字符,超限截断带尾标记)
|
|
681
|
+
*
|
|
682
|
+
* @param message - 原始消息
|
|
683
|
+
* @returns 契约合规的消息
|
|
684
|
+
*/
|
|
685
|
+
declare function sanitizeMessage(message: string): string;
|
|
686
|
+
/**
|
|
687
|
+
* 清洗堆栈(≤8000 字符;空字符串原样返回)
|
|
688
|
+
*
|
|
689
|
+
* @param stack - 原始堆栈
|
|
690
|
+
* @returns 契约合规的堆栈
|
|
691
|
+
*/
|
|
692
|
+
declare function sanitizeStack(stack: string): string;
|
|
693
|
+
/**
|
|
694
|
+
* 清洗事件名(pattern 失效回落哨兵名 invalid_event_name)
|
|
695
|
+
*
|
|
696
|
+
* @param name - 原始事件名
|
|
697
|
+
* @returns 合法事件名或哨兵名
|
|
698
|
+
*/
|
|
699
|
+
declare function sanitizeEventName(name: string): string;
|
|
700
|
+
/**
|
|
701
|
+
* 按白名单过滤事件属性(封闭字段集:白名单外键一律剔除,值原样保留)
|
|
702
|
+
*
|
|
703
|
+
* @param properties - 原始属性集
|
|
704
|
+
* @param allowedKeys - 采集点声明的白名单键集合
|
|
705
|
+
* @returns 仅含白名单键的新属性集
|
|
706
|
+
*/
|
|
707
|
+
declare function sanitizeProperties(properties: Readonly<Record<string, TelemetryPropertyValue>>, allowedKeys: readonly string[]): Record<string, TelemetryPropertyValue>;
|
|
708
|
+
//#endregion
|
|
709
|
+
export { BALANCED_DELIVERY_PROFILE, DEFAULT_DELIVERY_MODE, DEFAULT_TELEMETRY_CONSENT, type EventBatchAssembly, type EventBatchInput, INITIAL_COOLDOWN_STATE, INVALID_EVENT_NAME_SENTINEL, LITE_DELIVERY_PROFILE, LOSSLESS_DELIVERY_PROFILE, type LogBatchAssembly, type LogBatchInput, type NativeCrashMarkerPort, type OutboxRecord, type StoredTelemetryRecord, type SystemEventChannelPort, type SystemObservedEvent, type SystemObservedEventKind, TELEMETRY_BATCH_MAX_ENTRIES, TELEMETRY_CLOCK_ANOMALY_THRESHOLD_MS, TELEMETRY_ENDPOINTS, TELEMETRY_EVENT_NAME_PATTERN, TELEMETRY_MESSAGE_MAX_LENGTH, TELEMETRY_STACK_MAX_LENGTH, TELEMETRY_TRUNCATION_TAIL, type TelemetryBatchContext, type TelemetryChannelKind, type TelemetryClockPort, type TelemetryConsent, type TelemetryConsentChange, type TelemetryCooldownState, type TelemetryDeliveryMode, type TelemetryDeliveryProfile, type TelemetryEventBatch, type TelemetryEventEntry, type TelemetryLogBatch, type TelemetryLogEntry, type TelemetryLogLevel, type TelemetryPlatform, type TelemetryPropertyValue, type TelemetryRejectedCause, type TelemetryRetryableCause, type TelemetrySendOutcome, type TelemetrySendResult, type TelemetryStoragePort, type TelemetryTransportPort, type TelemetryUploadChannel, applyConsentChange, assembleEventBatch, assembleLogBatch, batchContextSchema, classifyHttpStatus, classifyTransportFailure, eventBatchSchema, eventEntrySchema, getDeliveryProfile, isChannelUploadAllowed, logBatchSchema, logEntrySchema, normalizeDeliveryMode, registerSendFailure, registerSendSuccess, sanitizeEventName, sanitizeMessage, sanitizeProperties, sanitizeStack, shouldAttemptSend };
|