目录— 个文件
⌕
目录加载中…
…/core/log/LogManager.ts
1import { Framework } from "../../Framework";
2import { frameworkManager } from "../base/FrameworkClassRegistry";
3import { IFrameworkManager } from "../base/IFrameworkManager";
4import { Singleton } from "../base/Singleton";
5import { SdkChannel } from "../../module/sdk/SdkChannel";
6import { SdkConfig } from "../../module/sdk/SdkConfig";
7import { SdkReportFrameDefine } from "../../module/sdk/SdkReportFrameDefine";
8
9@frameworkManager()
10export class LogManager extends Singleton<LogManager> implements IFrameworkManager {
11
12 public static EnableLog = true;
13 /** 是否开启资源相关日志(ResourceManager / ResourceBundleLoader / ResourceAssetLoader 等) */
14 public static EnableResourceLog = false;
15
16 public Name = "LogManager";
17
18 /** 日志链路 id(用于串联一整条调用链的日志) */
19 private traceIdSeed: number = 1;
20 /** SDK 同步报错可能再次进入 Error,阻止递归上报。 */
21 private reportingError = false;
22
23 public async Init(): Promise<void> {
24 // 日志管理器直接使用自身入口,遵循日志总开关。
25 this.Log(this.Name, "Init", "初始化日志管理器");
26 }
27
28 public DeInit(): void {
29 }
30
31 Update(deltaTime: number): void {
32 }
33
34 /** 内部工具:判断是否属于资源模块日志(通过模块名字符串简单匹配) */
35 private static IsResourceModuleArg(arg: any): boolean {
36 return typeof arg === "string" && arg.indexOf("Resource") !== -1;
37 }
38
39 public Log(...args: any[]): void {
40 // Framework.Sdk.ReportFeedbackLog(JSON.stringify(args));
41
42 if (!LogManager.EnableLog) {
43 return;
44 }
45 // 资源日志总开关:当第一个参数是资源相关模块名且关闭时,直接不输出
46 if (!LogManager.EnableResourceLog && args.length > 0 && LogManager.IsResourceModuleArg(args[0])) {
47 return;
48 }
49 console.log(...args);
50 }
51
52 public Warn(...args: any[]): void {
53 // Framework.Sdk.ReportFeedbackLog(JSON.stringify(args));
54 // if (!LogManager.EnableLog) {
55 // return;
56 // }
57 console.warn(...args);
58 const reportMessage = LogManager.SerializeArgs(args);
59 // Framework.Sdk.ReportErrorToRealtime(reportMessage);
60 Framework.Sdk.ReportFeedbackError(reportMessage);
61 }
62
63 /** 仅写入抖音用户反馈日志,供开放平台“下载日志”功能排查问题。 */
64 public FeedbackInfo(...args: any[]): void {
65 Framework.Sdk.ReportFeedbackLog(LogManager.SerializeArgs(args));
66 }
67
68 public Error(...args: any[]): void {
69 console.error(...args);
70 if (this.reportingError) return;
71 const reportMessage = LogManager.SerializeArgs(args);
72 this.reportingError = true;
73 try {
74 // 反馈日志与统计事件共用入口;平台字段使用运营约定值。
75 Framework.Sdk.ReportFeedbackError(reportMessage);
76 let platform: string;
77 if (SdkConfig.Channel === SdkChannel.Wechat) {
78 platform = SdkReportFrameDefine.errorLog.platform.wx;
79 } else if (SdkConfig.Channel === SdkChannel.Tiktok) {
80 platform = SdkReportFrameDefine.errorLog.platform.tt;
81 } else {
82 return;
83 }
84 Framework.Sdk.ReportAnalytic(SdkReportFrameDefine.errorLog.name, {
85 [SdkReportFrameDefine.errorLog.field.platform]: platform,
86 [SdkReportFrameDefine.errorLog.field.info]: reportMessage,
87 });
88 } catch (error) {
89 // 错误上报失败只写控制台,不能再次调用业务错误入口。
90 console.error("LogManager", "ErrorLog 上报失败", error);
91 } finally {
92 this.reportingError = false;
93 }
94 }
95
96 /**
97 * 将日志参数转换为适合上传的字符串,并保留 Error 的名称、消息和堆栈。
98 * 原生 JSON.stringify(Error) 只会得到空对象,无法用于线上定位问题。
99 */
100 private static SerializeArgs(args: any[]): string {
101 try {
102 return JSON.stringify(args, (_key, value) => {
103 if (value instanceof Error) {
104 return {
105 name: value.name,
106 message: value.message,
107 stack: value.stack,
108 };
109 }
110 if (typeof value === "bigint") {
111 return value.toString();
112 }
113 return value;
114 });
115 } catch {
116 return args.map((arg) => {
117 if (arg instanceof Error) {
118 return `${arg.name}: ${arg.message}\n${arg.stack ?? ""}`;
119 }
120 try {
121 return typeof arg === "string" ? arg : String(arg);
122 } catch {
123 return "[Unserializable]";
124 }
125 }).join(" ");
126 }
127 }
128
129 /**
130 * 获取全局唯一的 TraceId(用于一条日志链路,从头到尾复用同一个 id)
131 */
132 public NextTraceId(): number {
133 return this.traceIdSeed++;
134 }
135
136 /**
137 * 带 TraceId 的普通日志。
138 * 建议格式:TraceLog(traceId, 模块名, 步骤名, 信息, 其它参数...)
139 */
140 public TraceLog(traceId: number | null, module: string, step: string, message: string, ...extra: any[]): void {
141 if (!LogManager.EnableLog) {
142 return;
143 }
144 // 资源日志总开关:module 带有 Resource 关键字时,受资源日志开关控制
145 if (!LogManager.EnableResourceLog && LogManager.IsResourceModuleArg(module)) {
146 return;
147 }
148 const prefix = traceId != null ? `[#${traceId}] ` : "";
149 this.Log(module, step, `${prefix}${message}`, ...extra);
150 }
151
152 /**
153 * 带 TraceId 的错误日志。
154 * 建议格式:TraceError(traceId, 模块名, 步骤名, 信息, Error)
155 */
156 public TraceError(traceId: number | null, module: string, step: string, message: string, error?: any, ...extra: any[]): void {
157 const prefix = traceId != null ? `[#${traceId}] ` : "";
158 this.Error(module, step, `${prefix}${message}`, error, ...extra);
159 }
160
161}
讲解162 行
日志与错误上报管理器人工通读
LogManager.ts
提供普通日志、警告、错误与带 TraceId 的日志入口,输出受两个静态开关控制。警告与错误除了写控制台,还会把序列化后的内容上报到 SDK 反馈日志,错误再按渠道补一条统计事件。编辑器配置脚本会依据环境直接改写日志总开关。
先看两个静态开关的作用域,再读 Log 的两层过滤,然后看 SerializeArgs 的 Error 展开,最后读 Warn 与 Error 的上报分支和递归保护。
特殊处理与易错点
- 单例/静态状态EnableLog 与 EnableResourceLog 都是静态字段,编辑器配置在 SyncConfig 里直接赋值,一处改动全局生效且不随实例销毁复位。L12
- 特殊处理资源日志过滤只检查第一个参数是否为含 Resource 的字符串,TraceLog 则检查 module 参数,两处判定对象不同。L46
- 异常兜底reportingError 标记阻止 SDK 同步报错再次进入 Error 造成递归,finally 里必须复位。L70
- 易错点Warn 的日志开关判断被注释掉,线上关闭日志后警告仍会写控制台并产生一次 SDK 上报。L52
- 渠道差异只有微信和抖音渠道有统计平台映射,其它渠道在反馈上报之后直接 return,不发统计事件。L77
- 特殊处理SerializeArgs 用 replacer 把 Error 展开成名称、消息与堆栈,bigint 转字符串;循环引用导致 stringify 失败时降级为逐项字符串拼接。L102
10注释LogManager:日志管理器:Log/Warn/Error、资源日志开关、TraceId、错误序列化并上报平台
14注释是否开启资源相关日志(ResourceManager / ResourceBundleLoader / ResourceAssetLoader 等)
19属性自增的链路编号种子,NextTraceId 每次取用后加一。
21注释SDK 同步报错可能再次进入 Error,阻止递归上报。
23方法用自身日志入口写一条初始化记录,会照常受日志总开关过滤。
25注释日志管理器直接使用自身入口,遵循日志总开关。
28方法空实现,不重置静态开关也不清空链路编号。
31方法空实现,日志管理器没有逐帧任务,也不做日志缓冲或定时落盘。
35方法判断参数是否为包含 Resource 子串的字符串,用于识别资源模块日志。
39方法总开关关闭时直接返回,资源日志开关关闭且首参命中资源模块时也返回,否则输出到控制台。
46注释资源日志总开关:当第一个参数是资源相关模块名且关闭时,直接不输出
52方法先输出警告到控制台,再把参数序列化后无条件上报到 SDK 反馈错误接口。
64方法只把序列化后的参数写入 SDK 反馈日志,不输出到控制台。
68方法先写错误到控制台,再在未重入时上报反馈日志,并按渠道补发一条错误统计事件。
75注释反馈日志与统计事件共用入口;平台字段使用运营约定值。
90注释错误上报失败只写控制台,不能再次调用业务错误入口。
100方法把参数数组转成 JSON 字符串,Error 与 bigint 按自定义规则展开,失败时逐项拼接。
132方法返回当前链路编号后把种子加一,保证同一进程内编号不重复。
140方法按总开关与资源开关过滤后,给消息加上链路前缀并转交给普通日志输出。
145注释资源日志总开关:module 带有 Resource 关键字时,受资源日志开关控制
156方法给错误消息加上链路前缀后转交错误入口,会触发上报与统计逻辑。