Debug your inbox app

This document covers tools and features available for debugging building with XMTP, including stress testing, group chat diagnostics, logging, and network monitoring capabilities.

XMTP Debug

You can use the XMTP Debug tool to stress and burn-in test your inbox app on the local and dev XMTP environments.

To learn more, see XMTP Debug.

Forked group debugging tool

A conversation now has getDebugInformation. You can use this to see:

• The MLS epoch of a group chat conversation for a member
• Whether a group chat might be forked for a member
• Details of a potential fork

The function that provides this information is called maybeForked because it is difficult to be 100% certain whether a group is forked.

• If maybeForked returns true, it is highly likely that the group chat is forked.
• If maybeForked returns false, it is highly likely that the group chat is NOT forked.

To learn about group chat forks, see MLS Group State Forks: What, Why, How.

If you believe you are experiencing a forked group, please open an issue in the LibXMTP repo to get support. Please include logs, the epoch, and other fork details.

Forked groups are not recoverable. Your options are to:

• Remove all members from the forked group and then re-add them to the group.
• Start a new group.

File logging

These file logging functions enable the XMTP rust process to write directly to persistent log files that roll during every hour of active usage and provide a 6-hour window of logs. This can be especially helpful when debugging group chat errors and other complex issues.

The file logs complement Android and iOS system logs, which rely on memory buffer constraints, but often don't go back far enough to help catch when an issue occurs.

To use file logging, call the following static functions:

• Client.activatePersistentLibXMTPLogWriter(): Use to activate the file logging feature.
  • We recommend using LogLevel.Debug, LogRotation.Hourly, and a logMaxFiles value of 5-10. Log files can grow to ~100mb each with active clients on debug level in an hour of usage.
• Client.getXMTPLogFilePaths(): Use to get the full paths of log files written so far. This is useful for passing to iOS or Android Share functions.
• Here are additional helper static functions in the XMTP Client object:
  • deactivatePersistentLibXMTPLogWriter()
  • isLogWriterActive()
  • readXMTPLogFile()
  • clearXMTPLogs()

For an example UI implementation, see PR to add new persistent log debug menu options to the Convos app, built with XMTP.

Network statistics

You can use these statistics to see which and how many API, identity, and streaming calls are going across the network, which can help you better manage network usage and debug potential rate limiting issues.

These statistics are maintained per client instance, so each app installation has its own separate counter. Each one is a rolling counter for the entire session since the gRPC client was created. To get a snapshot of statistics at a moment in time, you can check the counter, run the action, get the counter again, and then diff the counter with the original counter.

Get aggregated statistics

To return aggregated statistics, run:

• For Browser, Node, iOS, and Android SDKs: client.debugInformation.apiAggregateStatistics()
• For React Native SDK: client.debugInformation.aggregateStatistics

Aggregate Stats:
============ Api Stats ============
UploadKeyPackage        1
FetchKeyPackage         2
SendGroupMessages       5
SendWelcomeMessages     1
QueryGroupMessages      7
QueryWelcomeMessages    0
============ Identity ============
PublishIdentityUpdate    1
GetIdentityUpdatesV2     4
GetInboxIds             2
VerifySCWSignatures     0
============ Stream ============
SubscribeMessages        0
SubscribeWelcomes       0

Get an individual statistic

To return an individual statistic as a number, run:

• For Browser, Node, iOS, and Android SDKs:

  • client.debugInformation.apiStatistics.uploadKeyPackage to track uploadKeyPackage only, for example
  • client.debugInformation.apiIdentityStatistics.publishIdentityUpdate to track publishIdentityUpdate only, for example

• For React Native SDK:

  • client.debugInformation.Statistics.uploadKeyPackage to track uploadKeyPackage only, for example
  • client.debugInformation.IdentityStatistics.publishIdentityUpdate to track publishIdentityUpdate only, for example

For available individual statistics, see Statistic descriptions.

Clear statistics

To clear all API, identity, and stream statistics and set them to zero, run client.debugInformation.clearAllStatistics().

This is useful when you want to get a clean baseline before running specific actions. It's also particularly helpful for managing memory usage on mobile devices where gRPC client caching can accumulate large statistics.

Upload an archive of network statistics

With the Browser and Node SDKs, you can upload an archive of collected network statistics.

// Upload to default server (no serverUrl needed)
const result1 = await client.debugInformation.uploadDebugArchive();
 
// Upload to custom server (serverUrl provided)
const result2 = await client.debugInformation.uploadDebugArchive(
  "https://my-debug-server.com/api/upload"
);

Statistic descriptions

API statistics

Identity statistics

Stream statistics