SDKsFlutter

日志

配置 OpenIM Flutter SDK 日志，并使用 operationID 定位调用链路。

开发和预发布环境可以输出较详细的 SDK 日志；生产环境应降低级别并关闭不必要的标准输出。不要记录 Token、完整消息正文、原始文件 URL 或用户隐私字段。

初始化日志配置

Flutter SDK 在 initSDK() 时配置日志，而不是在 login() 时配置。

import 'dart:io';

final platformID = Platform.isIOS
    ? IMPlatform.ios
    : IMPlatform.android;

await OpenIM.iMManager.initSDK(
  platformID: platformID,
  apiAddr: apiAddr,
  wsAddr: wsAddr,
  dataDir: dataDir,
  listener: connectListener,
  logLevel: 5,
  isLogStandardOutput: true,
  logFilePath: logFilePath,
);

示例面向 Flutter 的 Android 与 iOS 运行环境：Android 使用 IMPlatform.android，iOS 使用 IMPlatform.ios。不要把 Android 平台值硬编码到 iOS 构建中。

参数	说明
`logLevel`	SDK 日志级别数字；固定 SDK 默认值为 `6`，应按部署环境选择。
`isLogStandardOutput`	是否输出到平台标准日志；开发诊断时开启。
`logFilePath`	可选日志文件路径；应放在应用可写目录。

生产环境建议关闭标准输出并只保留必要级别。日志目录受平台权限与生命周期约束，不要硬编码其他应用或系统目录。

写入与上传日志

await OpenIM.iMManager.logs(
  logLevel: 5,
  file: 'chat_repository.dart',
  line: 120,
  msgs: 'load conversation page failed',
  err: error.toString(),
  keyAndValues: ['conversationID', conversationID],
);

需要由用户主动提交诊断日志时，可以监听上传进度并调用 uploadLogs()：

OpenIM.iMManager.setUploadLogsListener(
  OnUploadLogsListener(
    onUploadProgress: (current, size) {
      updateLogUploadProgress(current, size);
    },
  ),
);

await OpenIM.iMManager.uploadLogs(ex: 'user initiated diagnostics');

setUploadLogsListener() 保存的是 manager 级 singleton listener，后一次设置会覆盖前一次。固定 SDK 没有 remove 或 unset API，因此应在应用统一的 SDK 绑定层设置一次，并由该层把进度分发给当前界面；不要在每个页面或组件重复设置。退出登录或切换账号时，清空应用层订阅和上一账号的上传状态，避免进度或错误显示到新账号界面。

上传前应向用户说明收集范围，并按隐私与合规要求处理日志。

使用 operationID 定位调用

operationID 是单次 SDK 调用的链路标识。Flutter SDK 多数方法把它作为可选命名参数；省略时 Utils.checkOperationID() 会生成 UUID。仅在需要与 OpenIMServer 日志精确对应时显式传入，每次调用使用新的值。

final operationID = createUniqueTraceID();
try {
  await OpenIM.iMManager.conversationManager.getConversationListSplit(
    offset: 0,
    count: 50,
    operationID: operationID,
  );
} catch (error) {
  appLogger.error('openim_api_failed', {
    'operationID': operationID,
    'action': 'get_conversation_page',
    'error': error.toString(),
  });
  rethrow;
}

示例中的 createUniqueTraceID() 代表应用已有的唯一追踪 ID 生成器；无需为了日志额外引入依赖，也可以直接省略 operationID。它不是身份凭据、业务幂等键或 conversationID，不能替代 Token 和业务标识。

这个页面有帮助吗？