Troubleshooting

This page provides tools and techniques for diagnosing and troubleshooting issues with your Ditto Cloud Platform queries and operations.

PROFILE

The PROFILE keyword is used to analyze the execution characteristics of DQL queries. When you prefix a query with PROFILE, the query executes normally and returns both the query results and detailed profiling information about the query execution.

Before attempting to interpret PROFILE results on your own, we strongly recommend opening a support ticket at https://support.ditto.live/hc/en-us. Profiling metrics taken out of context can lead to incorrect assumptions about query performance. Our support team can help you properly interpret the results.

Example

DQL

PROFILE SELECT * FROM movies LIMIT 10

produces:

{
  "~request_profile": {
    "_id": "some-unique-uuid",
    "_server_id": "your-server-id",
    "app_id": "your-app-id",
    "featureFlags": "0x1a",
    "plan": {
      "#operator": "sequence",
      "children": [
        {
          "#operator": "scan",
          "#stats": {
            "documentsOut": 10,
            "phaseTimes": {
              "exec": 3298,
              "recv": 4198771,
              "send": 10367
            }
          },
          "collection": "movies",
          "datasource": "default",
          "descriptor": {
            "limit": 10,
            "path": {
              "full_scan": {}
            }
          }
        }
      ]
    },
    "queryType": "select",
    "requestType": "http_api",
    "resultCount": 10,
    "state": "completed",
    "text": "PROFILE SELECT * FROM movies LIMIT 10",
    "times": {
      "elapsed": 51796819,
      "parse": 51483,
      "plan": 44739214,
      "start": "2025-12-02T15:26:57.510+00:00"
    }
  }
}

Understanding the Output

The PROFILE output includes several key sections:

plan: The execution plan showing the operators used to execute the query, similar to EXPLAIN output
#stats: Execution statistics for each operator, including document counts and timing information
times: Overall query timing breakdown showing parse, plan, and total elapsed time
resultCount: The number of documents returned by the query
state: The current state of the query execution

Important: All timing values in the PROFILE output are measured in nanoseconds. For example, an elapsed time of 51796819 nanoseconds equals approximately 51.8 milliseconds.

Remote Logging

Remote Logging allows you to request and retrieve detailed diagnostic logs from any device in your mesh through the Ditto Portal. This feature is particularly useful for investigating unexpected behavior on devices that may have intermittent connectivity or are deployed in the field.

When to Use Remote Logging

Use Remote Logging when you need to:

Investigate bugs or unexpected behavior on specific devices
Diagnose synchronization issues across your mesh
Gather diagnostic information from devices in production
Troubleshoot devices that are difficult to access physically

Remote Logging is designed for retroactive investigation and diagnostics. For real-time log monitoring or integrating Ditto logs into your application’s logging infrastructure, use the SDK’s custom log callback functionality instead.

Requesting Logs from the Portal

You can request logs from devices in two ways:

Option 1: Request Full Data Bundle

A data bundle includes logs, flamegraphs, and other diagnostic data produced by the Ditto SDK.

Navigate to Devices in the Portal sidebar
Locate the device you want to investigate in the devices table
Click the overflow menu (three dots) on the right of the device row
Click the Request data bundle link for that device

Device listing with Request data bundle option

Option 2: Request Logs Only

If you only need log files without additional diagnostic data:

Navigate to Devices in the Portal sidebar
Click on the device to open its detail page
Scroll down to the Local Ditto data section
Use the Request data bundle overflow menu (three dots)
Select Request logs from the dropdown

Local Ditto data section with Request logs option

How It Works

When you request logs from a device:

The request is sent through Ditto’s replication system
The device receives the request when it’s connected to the mesh
The device exports its logs and uploads them back through replication
Once uploaded, a Download link appears in the Portal
Click the download link to retrieve the log file

The device does not need to be online when you request logs. Both the request and the log upload use Ditto’s replication system, which means they work even with intermittent connectivity and the logs will be uploaded when the device is next connected to the mesh. Be patient if requesting logs from a device that connects infrequently.

The status of your log request appears in the Portal:

Pending upload: Request sent, waiting for device to process and upload logs
Download: Logs are ready to download

Understanding Log Files

Exported logs are plain text files where each line contains a structured JSON log entry:

{"timestamp":"2024-09-05T19:30:22.853460Z","level":"DEBUG","message":"starting vacuum","target":"ditto_system_info::implementation","span":{"name":"system_info_vacuum_run"},"threadName":"tokio-runtime-worker","threadId":"ThreadId(12)"}
{"timestamp":"2024-09-05T19:30:24.494150Z","level":"DEBUG","message":"Write txn committed","txn_id":12198,"originator":"Internal","target":"ditto_store::database","threadName":"tokio-runtime-worker","threadId":"ThreadId(13)"}

Each log entry includes:

timestamp: When the event occurred
level: Log level (DEBUG, INFO, WARN, ERROR)
message: Human-readable description of the event
target: Which component generated the log
Additional context-specific fields

Requirements

Remote Logging was introduced in Ditto SDK version 4.4.0. For SDK versions 4.4.0 to 4.7.x:

The “Small Peer Info” feature must be enabled in your SDK configuration
This feature must be configured to allow replication with the Cloud

For SDK version 4.8.0 and later:

Remote Logging is enabled by default
No additional configuration required

If you’ve manually disabled or modified the “Small Peer Info” feature in SDK 4.8.0+, it may prevent Remote Logging from working. Contact support if you’re experiencing issues.

Limitations

Log Size and Retention: Each device stores up to 15 MB of uncompressed log data OR 15 days of logs, whichever is smaller. This limit is not currently configurable. Full Export Only: Remote log requests export all available logs from the device as a single file. You’ll need to filter by timestamp or other criteria after downloading. Not Real-Time: This feature is designed for diagnostic investigation, not real-time monitoring. There may be a delay between requesting logs and receiving them, especially for devices with intermittent connectivity. Storage: If you need to retain logs for longer than 15 days, you should periodically export and store them outside of Ditto.