Logging

unix-openim-sdk logs diagnose initialization, login, and business API calls on Android, iOS, and HarmonyOS. Development and staging builds can emit detailed SDK logs. Production should retain only necessary errors and tracing fields and must avoid tokens, message bodies, file URLs, server credentials, and other private data.

A diagnostic flow combines logging options in OpenIMInitConfig, an optional operationID for one call, the plugin error, upload-progress events, and the application's structured logs.

Log levels

Configure logging through OpenIMInitConfig.logLevel when calling initSDK(). From most to least verbose, the exported levels are:

Do not leave Verbose or Debug enabled in production. Prefer an environment setting, staged feature flag, or explicit user-initiated diagnostic flow that raises verbosity only temporarily.

Recommended log levels

Configure logging

Logging options belong to SDK initialization, not login(). This Android example uses the corresponding platform identity and required systemType:

import {
  OpenIMLogLevelDebug,
  OpenIMPlatformAndroid,
  initSDK,
  type OpenIMInitConfig,
} from '@/uni_modules/unix-openim-sdk'

const config : OpenIMInitConfig = {
  platformID: OpenIMPlatformAndroid,
  apiAddr: 'https://im-api.example.com',
  wsAddr: 'wss://im-ws.example.com',
  logLevel: OpenIMLogLevelDebug,
  isLogStandardOutput: true,
  systemType: 'android',
}

await initSDK(config)

Parameters

apiAddr, wsAddr, platform ID, and systemType are still required initialization settings, but they are not logging fields. Error codes and messages in plugin failures are also not logging configuration parameters.

Trace one call with operationID

operationID is an optional correlation identifier for one SDK call. Most asynchronous APIs accept it as the last parameter. Ordinary calls can omit it and let the plugin generate or delegate the value. Create and pass one explicitly only when a specific call must be correlated precisely with native and OpenIMServer logs.

import { getConversationListSplit } from '@/uni_modules/unix-openim-sdk'

const operationID = createDiagnosticOperationID()

try {
  const result = await getConversationListSplit(
    { offset: 0, count: 50 },
    operationID,
  )

  appLogger.info('openim_api_success', {
    operationID,
    action: 'get_conversation_page',
    count: result?.conversations.length ?? 0,
  })
} catch (error) {
  appLogger.error('openim_api_failed', {
    operationID,
    action: 'get_conversation_page',
    error: sanitizeOpenIMError(error),
  })
  throw error
}

Use a new operationID for every call. It is not a user identity, permission credential, conversation ID, or business idempotency key and cannot replace a token, conversationID, or clientMsgID. If one business flow contains several SDK calls, give every call its own operationID and use an application trace ID to correlate the whole flow.

Record business context

Application logs can contain the route, business action, operationID, redacted error code, and necessary target identifiers such as conversationID or clientMsgID. Do not log:

• User or administrator tokens, secrets, or commercial business credentials.
• Complete message bodies, raw custom-message payloads, or private file URLs.
• Unnecessary user profiles, contact lists, or group-member lists.
• SDK database contents or complete local sandbox paths.

Apply support and privacy policy to target identifiers as well, and redact them again before publishing an issue or sharing logs across teams.

Upload logs

uploadLogs() receives a line count and an extension description. Obtain user consent first and explain what is collected, why it is needed, and how long it is retained.

import { uploadLogs } from '@/uni_modules/unix-openim-sdk'

const operationID = createDiagnosticOperationID()

await uploadLogs(
  {
    line: 2000,
    ex: JSON.stringify({ scene: 'login-timeout' }),
  },
  operationID,
)

Parameters

Promise success means that the log-upload request completed. It does not create a support case or mean that the problem has been analyzed. Limit retries on failure to avoid sustained background data and battery usage.

Observe upload progress

onUploadLogsProgress() returns an independent subscription handle. The canonical business owner for this event is Message overview; this page only defines how diagnostic UI uses the progress. The diagnostic service that owns the listener must release it with off(subscription).

Upload progress is display state, not proof that support analysis has completed. Never place raw log content or a token in progress state.

Related pages

• Install, initialize, and inspect the SDK
• Authenticate and manage a session
• Send your first message
• Send a message