Capturing Support Bundles

A support bundle is a tar archive that a device assembles locally. It packages logs, the effective configuration, and runtime telemetry for analysis by Ditto Support. Bundles are generated entirely on the device and work offline. No connection to Ditto Server is required.

Support bundles are available in Ditto SDK 5.2 and later on native platforms. The system_request_support_bundle() function isn’t available in the JavaScript Web SDK.

Requesting a bundle

Request a bundle with the system_request_support_bundle() DQL function. Run it with EXECUTE FUNCTION. The call completes when the bundle has been generated and stored, or fails with an error.

DQL

EXECUTE FUNCTION system_request_support_bundle()

You can attach your own metadata to the bundle, for example to record why it was requested. Ditto stores the metadata on the bundle’s attachment, and it’s visible when you list bundles:

DQL

EXECUTE FUNCTION system_request_support_bundle({
  "metadata": { "requested_by": "support", "ticket": "DIT-1234" }
})

The function returns one document that identifies the new bundle:

{
  "_id": { "pk": "<peer key>", "created_at": "2026-09-17T19:48:23.776558+00:00" },
  "reason": "USER_INITIATED",
  "file": { "id": "<attachment id>", "len": 31744, "metadata": { "requested_by": "support" } }
}

Field	Description
`_id.pk`	The peer key of the device that generated the bundle.
`_id.created_at`	The capture time as an RFC 3339 timestamp.
`reason`	`USER_INITIATED` for on-demand requests. `CRASH` for bundles captured after a crash.
`file`	An attachment token for the bundle archive. `file.metadata` holds any metadata you passed in the request.

Ditto generates one bundle at a time. If a bundle is already being generated, Ditto rejects the new request instead of queuing it.

Requesting from your app

Run the statement with ditto.store.execute(), the same way you run any other DQL statement. Because it’s a query, you can trigger it from wherever your app already runs Ditto queries, such as an admin screen, a remote command from your backend, or a debug socket. To download the archive, pass the file token to fetchAttachment(). See Fetching attachments for the full fetch lifecycle in each SDK.

let result = try await ditto.store.execute(
    query: "EXECUTE FUNCTION system_request_support_bundle()"
)

if let token = result.items.first?.value["file"] as? [String: Any] {
    let fetcher = try await ditto.store.fetchAttachment(token) { event in
        if case .completed(let attachment) = event {
            // Save the bundle, for example to share it with Ditto Support.
            try? attachment.copy(toPath: "/path/to/support-bundle.tar")
        }
    }
}

ditto.store.execute(
    query = "EXECUTE FUNCTION system_request_support_bundle()",
).use { result ->
    val token = result.items.first().value["file"] as Map<String, Any>

    val fetchResult = ditto.store.fetchAttachment(
        tokenMap = token,
        onFetchProgress = { downloadedBytes, totalBytes -> },
    )

    if (fetchResult is DittoAttachmentFetchResult.Completed) {
        fetchResult.attachment.use { attachment ->
            // Save the bundle, for example to share it with Ditto Support.
            attachment.copyToPath("/path/to/support-bundle.tar")
        }
    }
}

const result = await ditto.store.execute(
  "EXECUTE FUNCTION system_request_support_bundle()"
)
const token = result.items[0].value["file"]

const fetcher = await ditto.store.fetchAttachment(token, (event) => {
  if (event.type === "Completed") {
    // Save the bundle, for example to share it with Ditto Support.
    event.attachment.copyToPath("/path/to/support-bundle.tar")
  }
})

using var result = await ditto.Store.ExecuteAsync(
    query: "EXECUTE FUNCTION system_request_support_bundle()");

var token = result.Items.First().Value["file"] as Dictionary<string, object>;
var fetcher = ditto.Store.FetchAttachment(token, fetchEvent =>
{
    if (fetchEvent is DittoAttachmentFetchEvent.Completed e)
    {
        // Save the bundle, for example to share it with Ditto Support.
        e.Attachment.CopyToPath("/path/to/support-bundle.tar");
        e.Attachment.Dispose();
    }
});

final result = await ditto.store.execute(
  "EXECUTE FUNCTION system_request_support_bundle()",
);
final doc = result.items.single.value;
final token = Map<String, dynamic>.from(doc["file"] as Map);

final fetcher = ditto.store.fetchAttachment(token, (event) {});
final attachment = await fetcher.attachment;
// Save the bundle, for example to share it with Ditto Support.
await attachment!.copyToPath("/path/to/support-bundle.tar");

On Android, the support bundle screen in DittoAndroidTools lets you request, view, and export bundles without writing queries.

Listing retained bundles

Ditto stores generated bundles on the device and lists them in the system:support_bundles virtual collection. To list bundles from newest to oldest, run:

DQL

SELECT * FROM system:support_bundles ORDER BY _id.created_at DESC

Each document has the same _id, reason, and file fields that system_request_support_bundle() returns. See system:support_bundles for the schema.

Bundle contents

The archive is a plain tar with a flat layout:

Entry	Contents
`ditto-logs.log.gz`	Gzipped export of the on-device Ditto logs (JSON lines), covering the retained log window.
`device_logs_METADATA.json`	The time range covered by the log export.
`config_snapshot.json`	The effective configuration at capture time: `ditto_config` with secrets redacted, the full system parameter set, `transport_config`, the SDK version, and the capture timestamp.
`dial9/dial9.bin.gz`	Tokio runtime telemetry (worker activity over time). Present only when dial9 recording is enabled and at least one 60-second trace segment has completed.
`bundle_errors.txt`	Present only when a bundle source failed. Lists the failed sources and their errors.

Bundles captured in the first 60 seconds of process lifetime don’t contain dial9 traces. Trace segments rotate every 60 seconds, and only completed segments are captured. dial9 recording is on by default at level Lite. Change it with the DITTO_DIAL9_OBSERVABILITY_LEVEL environment variable.

The log export includes a mapping of full peer public keys, so that peer logs can be cross-referenced, and absolute on-device file paths. Config secrets are redacted from config_snapshot.json. Review bundle contents before sharing them broadly.

Rate limiting, timeout, and retention

Three system parameters control bundle generation. Change them at run time with ALTER SYSTEM. Changes apply to the next request without a restart and reset to the defaults when the process restarts. In SDK 5.2 and later you can also set them in the system parameters of DittoConfig.

Parameter	Default	Range	Behavior
`support_bundle_request_rate`	3	0 or more	Maximum requests admitted per rolling 10-minute window. `0` turns off bundle generation. Rejected requests fail immediately with an error that names the limit and when to retry. The request count survives restarts.
`support_bundle_request_timeout`	30 seconds	1 to 3600 seconds	Maximum time for bundle collection and archive finalization. A capture that exceeds the deadline fails as a whole. Individual section failures are tolerated and recorded in `bundle_errors.txt`.
`support_bundle_retention_limit`	10	1 or more	Maximum bundles retained on the device. Saving beyond the limit evicts the oldest first.

For example, to allow more requests during a support session:

DQL

ALTER SYSTEM SET support_bundle_request_rate = 10

There is no total byte-size cap on retained bundles. Retention is count-based. Bundle size is driven mainly by retained log volume and the dial9 buffer size (dial9_buffer_size_mb, default 16 MB).

Requesting a bundle from the Portal

You can also request a support bundle from a managed device through the Ditto Portal. See Troubleshooting. The Portal-driven archive uses the same base entries and adds request_history.json and system_indexes.json, plus a flamegraph when remote_flamegraph_request_enabled is on. Portal-triggered bundles upload to Ditto Server automatically. Locally requested bundles stay on the device until you fetch and share them.

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Capturing Support Bundles

Requesting a bundle

Requesting from your app

Listing retained bundles

Bundle contents

Rate limiting, timeout, and retention

Requesting a bundle from the Portal

​Requesting a bundle

​Requesting from your app

​Listing retained bundles

​Bundle contents

​Rate limiting, timeout, and retention

​Requesting a bundle from the Portal

Requesting a bundle

Requesting from your app

Listing retained bundles

Bundle contents

Rate limiting, timeout, and retention

Requesting a bundle from the Portal