Client debug data
About client debug data
Our client debug data feature enables you to send debug information from elements and sensors available on the mobile device such as disk space and available memory to the Encap server. This is logged to a separate file.
The feature is not intended to be continuously enabled. It is designed to be used during error or support situations where additional data can help in finding the error.
The feature is disabled by default. It It is possible to enable it for either Android or iOS devices, or for both platforms.
Example data
You can find some examples of data that can be logged in the list below:
- Disk space available
- The amount of memory left on the mobile device, given in MB.
- The process ID of the app performing the operation.
- The thread ID performing the operation.
- Whether or not the mobile device is currently in battery saver / low power mode.
- Whether the operation if performed over a Wi-Fi or cellular connection.
- The timestamp of the request as reported from the mobile device.
The feature is configured in the application configuration.
Integration
Server configuration
Application configuration
To enable client debug data, you need to configure the application configuration with the following parameter on the sever:
Logback configuration
To write the data to the logs, you need to update the logback.xml file needs to be updated.
- The configuration that comes default with a new installation of Encap server writes all client debug data to the
logs/clientDebugData.log. - If you are upgrading and already have a custom
logback.xml, then you need to update it with the below configuration in order to enable client debug data.<!-- Client debug data log appender -->
<appender name="clientDebugData" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>./logs/clientDebugData.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
<fileNamePattern>./logs/clientDebugData.%i.log.gz</fileNamePattern>
<minIndex>1</minIndex>
<maxIndex>10</maxIndex>
</rollingPolicy>
<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
<maxFileSize>10MB</maxFileSize>
</triggeringPolicy>
<encoder>
<Pattern>%d %X{requestCorrelationId} %m%n</Pattern>
</encoder>
</appender>
<logger name="ClientDebugDataLogger" level="INFO" additivity="false">
<appender-ref ref="clientDebugData"/>
</logger> - Nothing will be written to the log unless you change the configuration in the application configuration.
Mobile configuration
The mobile SDK will never send any client debug data without it being configured on the server.
In addition, each registration on a device can reserve itself from sending debug data. To do this, the app needs to set value false in the configuration:
Technical details
The application configuration setting on the server will be communicated to the client SDKs meaning that no debug data will be sent if the setting is disabled.
Log output
The log output for client debug data is configured in logback.xml. This gives an opportunity to add the logs to any appender and adjust the output format to fit into any external log analysis tool.
By default, the data is stored in the clientDebugData.log file in the same folder as the other logs. The appender is set up to roll over after 10 MB and stores the previous log file as a compressed gz file.
The 10 last files are stored.
Log size
Client debug data is logged for each operation:
- Activation
- Authentication
- Recovery
Depending on the number of mobile devices, this can potentially produce many entries. You can update the configuration in the logback.xml file to limit or extend the amount of data stored on the server.
Log format
Client debug data is stored in the following format:
date correlationId registrationId clientDebugData
2022-05-18 13:06:31,410 561570bb-d6ab-11ec-8a74-0a2622afb44b 0028211c-6512-4f44-8fd6-6fbb1d0a55d7 {"processId":"24057","threadId":"{number = 8, name = (null","connectionType":"WiFi","applicationState":"active","clientRequestTime":"15:05:20 + 2060","isProtectedDataAvailable":"true","lowPowerMode":"false","isIosAppOnMac":"false","freeDiskSpace":"21,454"}
2022-05-18 13:06:31,622 5637ecdc-d6ab-11ec-8a74-0a2622afb44b 0028211c-6512-4f44-8fd6-6fbb1d0a55d7 {"isIosAppOnMac":"false","connectionType":"WiFi","processId":"24057","threadId":"{number = 6, name = (null","freeDiskSpace":"21,454","applicationState":"active","lowPowerMode":"false","isProtectedDataAvailable":"true","clientRequestTime":"15:05:42 + 4290"}
The correlationId is used to correlate all log entries during a request.
Logged data
All available debug information will be sent to server if the feature is enabled. The list of attributes vary depending on the mobile platform.
You can see attributes are returned in our the Collected data appendix in our SDK documentation. To see this, use the buttons below for each platform below.