hugo-log-sdk/index.d.ts

全链路日志SDK

declare global {
  var $trace: IBaseTrace;
  var $traceInit: (options: TraceOptions) => void | IBaseTrace;
}

/** 一下是错误 (data) 类型 */

// 问题级别
export enum TraceDataSeverity {
  // 其他
  Else = "else",
  // 错误级别
  Error = "error",
  // 告警级别
  Warning = "warning",
  // 日志级别
  Info = "info",
  // 调试级别
  Debug = "debug",
  // 低危级别
  Low = "low",
  // 普通级别
  Normal = "normal",
  // 高危级别
  High = "high",
  // 极其严重
  Critical = "critical",
}

// 错误日志类型
export enum TraceDataTypes {
  // 未知
  UNKNOWN = "UNKNOWN",
  // 未知函数
  UNKNOWN_FUNCTION = "UNKNOWN_FUNCTION",
  // js 脚本
  JAVASCRIPT = "JAVASCRIPT",
  // 打印信息
  LOG = "LOG",
  // 网络请求
  HTTP = "HTTP",
  // 资源
  RESOURCE = "RESOURCE",
  // 异步
  PROMISE = "PROMISE",
  // 路由
  ROUTE = "ROUTE",
  // 性能
  PERF = "PERF",
  // UI 框架
  VUE = "VUE",
  REACT = "REACT",
  // ...更多框架
}

// 异常通用接口
export interface ITraceBaseData {
  // id
  dataId: number;
  // 日志信息名称
  name?: string;
  // 问题类型
  type: TraceDataTypes;
  // 问题级别
  level: TraceDataSeverity;
  // 异常信息
  message: string;
  // 发生时间
  time: number;
}

// 代码异常错误信息
export interface TractDataCodeError extends ITraceBaseData {
  // 行数
  lineNumber: number;
  // 列数
  column: number;
  // 文件地址
  source: string;
}

// 请求类型接口
export interface TraceDataFetch extends ITraceBaseData {
  // 执行时间，用于统计耗时
  elapsedTime: number;
  // 请求方法
  method: string;
  // 请求类型
  httpType: "fetch" | "xhr";
  // 请求地址
  url: string;
  // 请求参数
  body: string;
  // 响应状态
  status: number;
}

// Promise类型接口
export interface TraceDataPromise extends ITraceBaseData {}

// 资源类型接口
export interface TraceDataResource extends ITraceBaseData {
  // 请求地址
  url?: string;
}

// 普通日志接口
export interface TraceDataLog extends ITraceBaseData {
  // 标签
  tag?: string;
}

// PV/UV 接口
export interface TraceDataPageView extends ITraceBaseData {
  // 路由
  route?: string;
}

/** 以下是性能 (pref) 类型 */

// webVitals性能收集信息接口
export enum TracePerfRating {
  GOOD = "good",
  NEEDS_IMPROVEMENT = "needs improvement",
  POOR = "poor",
}

export interface TracePerf {
  id: string;
  // 指标值
  LCP?: number;
  // 指标衡量值
  LCPRating?: TracePerfRating;
  FID?: number;
  FIDRating?: TracePerfRating;
  FCP?: number;
  FCPRating?: TracePerfRating;
  TTFB?: number;
  TTFBRating?: TracePerfRating;
  CLS?: number;
  CLSRating?: TracePerfRating;
  INP?: number;
  INPRating?: TracePerfRating;
}

/** 以下是行为 (breadcrumbs) 类型 */

// 行为分类
export enum BreadcrumbsCategorys {
  // 网络请求
  Http = "http",
  // 用户操作
  User = "user",
  // 调试
  Debug = "debug",
  // 抛异常
  Exception = "exception",
  // 生命周期
  Lifecycle = "lifecycle",
}

// 日志类型
export enum BreadcrumbTypes {
  // 路由跳转
  ROUTE = "Route",
  // 用户点击
  CLICK = "UI.Click",
  // 控制台打印
  CONSOLE = "Console",
  // 网络请求
  FETCH = "Fetch",
  // 未处理异常
  UNHANDLEDREJECTION = "Unhandledrejection",
  // 资源
  RESOURCE = "Resource",
  // 代码错误
  CODE_ERROR = "Code Error",
  // 其他
  CUSTOMER = "Customer",
}

interface ITraceBaseAction {
  // 动作名称
  name?: string;
  // 动作参数
  level: TraceDataSeverity;
  // 动作时间
  time: number;
  // 日志类型
  type: BreadcrumbTypes;
  // 行为分类
  category: BreadcrumbsCategorys;
}

// 行为日志
export interface TraceAction extends ITraceBaseAction {
  // 行为动作相关的信息，可以是DOM，可以是错误信息，可以是自定义信息
  message?: string;
  // 请求参数
  request?: any;
  // 请求结果内容
  response?: any;
  // 错误堆栈信息
  stack?: string;
}

/** 以下是基本日志信息集合 */

// 日志类型
export enum TraceTypes {
  // PV/UV
  PAGE_VIEW = "PageView",
  // 事件
  EVENT = "EVENT",
  // 性能
  PERF = "Performance",
  // 资源
  RESOURCE = "Resource",
  // 动作、行为类型
  ACTION = "Action",
  // 请求类型
  FETCH = "Fetch",
  // 代码错误
  CODE_ERROR = "CodeError",
  // 日志
  CONSOLE = "Console",
  // 其它
  CUSTOMER = "Customer",
}

// 浏览器类型
export enum BrowserType {
  // 手机端浏览器
  MOBILE = "mobile",
  // PC浏览器
  PC = "pc",
  // webview
  WEBVIEW = "webview",
  // 小程序
  MINI_PROGRAM = "miniProgram",
  // 未知
  UNKNOWN = "unknown",
}

// 日志级别
export enum TraceLevelType {
  // 告警级别
  error = "error",
  // 预警级别
  warn = "warn",
  // 普通日志
  info = "info",
  // 调试日志
  debug = "debug",
}

// 客户端类型
export enum TraceClientTypes {
  // 安卓
  ANDROID_H5 = "android",
  // iOS
  IOS_H5 = "ios",
  // PC端
  PC_H5 = "pc",
  // 浏览器
  BROWSER_H5 = "browser",
}

// 全链路日志基类
export interface ITraceBase {
  // 唯一ID，用户侧生成
  traceId: string;
  // 日志类型
  type: TraceTypes;
  // 日志产生时间
  createdAt: number;
  // 日志最后更新时间
  updatedAt: number;
}

// 浏览器相关字段基类
export interface IBaseBrowserTrace {
  // 当前浏览器的UserAgent
  ua: string;
  // 浏览器类型
  browserType: BrowserType;
}

// 页面相关字段基类
export interface IBasePageTrace {
  // 页面ID
  pid: string;
  // 页面标题
  title?: string;
  // 当前页面URL
  url: string;
}

// 用户相关字段基类
export interface IBaseUserTrace {
  // 指纹ID，fingerprintId
  fpId: string;
  // 用户ID
  uid?: string | number;
  // 用户名称
  userName?: string;
  // 用户邮箱
  email?: string;
  // 用户手机号
  phone?: string;
}

// 业务相关字段基类
export type BaseAppTrace = {
  // 业务ID
  appId: string;
  // 业务名称
  appName?: string;
  // 客户端类型
  clientType: TraceClientTypes;
  // 日志级别
  level: TraceLevelType;
};

// 日志基本类型
export interface IBaseTraceInfo extends ITraceBase, IBaseBrowserTrace, IBaseUserTrace, IBasePageTrace, BaseAppTrace {}

// 一份错误信息的类型集合
export type TraceTypeData =
  | TraceDataFetch
  | TractDataCodeError
  | TraceDataPromise
  | TraceDataResource
  | TraceDataLog
  | TraceDataPageView;

// 操作行为日志集合
export type TraceBreadcrumbs = TraceAction[];

// 性能
export type TracePerfs = TracePerf[];

// 完整日志类型
export interface TraceData extends IBaseTraceInfo {
  // 记录错误信息
  data?: TraceTypeData;
  // 记录操作行为
  breadcrumbs?: TraceBreadcrumbs;
  // 记录性能信息
  perf?: TracePerf;
}

/** 以下是 sdk 使用类型 */

export interface IBaseTrace {
  // 浏览器信息
  userAgent: string;
  // 浏览器类型
  browserType: string;
  // 客户端类型
  clientType: string;
  // fingerprintId
  fpId: string | undefined;
  // 页面ID
  pageId: string;
  // 应用ID
  appId: string;
  // 是否开启debug
  debug: boolean;
  // 记录用户行为
  breadcrumb: TraceBreadcrumbs;
  // 最大存储用户行为
  maxBreadcrumbs: number;
  // 待发送日志队列
  readonly traceQueue: TraceData[];

  onGlobalError(callback?: (e: Event) => {}): void;
  onGlobalClick(callback?: (bc: TraceAction) => {}): void;
  saveBreadcrumb(data: TraceAction): void;
  saveError(data: ErrorEvent): void;
  // 生成日志数据
  setTraceData(data: TraceTypeData | TracePerf): TraceData;
  // 添加日志到队列
  pushTraceQueue(data: TraceData): void;
  // 清空队列
  clearQueue(): void;
  // 配置用户信息
  setUserInfo(data: Omit<IBaseUserTrace, "fpId">): void;
  // 清空用户信息
  clearUserInfo(): void;
  // 发送日志
  send(data: TraceData): Promise<unknown> | undefined;
  // 日志打印
  log(log: TraceDataLog): void;
  // 普通日志
  info(message: string, tag?: string): void;
  // 警告日志
  warn(message: string, tag?: string): void;
  // 错误日志
  error(message: string, tag?: string): void;
  // 页面访问日志
  pageView(route: string, title?: string): void;
}

export type SendType = "xhr" | "fetch" | "beacon" | "img";

export type TraceOptions = {
  perfOnSend?: () => void;
  perfBeforeSend?: (data?: TracePerf) => void;
  maxBreadcrumbs?: number;
  debug?: boolean;
  dsn?: string;
  appId: string;
  sendType?: SendType;
};

export const init: (options: TraceOptions) => IBaseTrace;