Overview

This is an enterprise feature. Please contact support@backtrace.io to request it be enabled for your account.

Submission buckets allow for advanced control of error data submission and attachments. In particular, they allow for conditional logic on the submission path based on previously seen error data attributes. For example, large assets such as videos, screenshots, log files or full dumps may be useful for root cause investigation. At the same time, you may not want your users to pay the cost of generating and sending this data for every single crash. Submission will allow you to control this for any combination of attributes. For example, you may want these assets generated and attached once for every crash.

Submission buckets are configured on api_token  objects. Currently, only one submission bucket may be defined for every token. The api_token  must also have a synchronous post and error post capability (sync:post  and error:post  respectively).

Step-by-step

Step 1. Create a token.

We will create a token specifying sync:post  and error:post  capabilities. We will also update the metadata field specifying a submission bucket called cts. The submission bucket will provide counts for unique combinations of issue identifiers and operating systems. In this case, our goal is to have a crash reporting client submit an attachment once for every unique combination of the fingerprint  and uname.sysname  attribute values. In addition to this, the submission bucket is configured to set the has_advanced_log  attribute to "1" for all requests (attachment or error upload) that reference the submission bucket. We will use the morgue command line tool to create this token.

$ morgue token create --project=cts --capability=error:post --capability=sync:post --metadata='{"buckets":{"cts":{"attributes":["fingerprint","uname.sysname"], "set": { "has_advanced_log" : "1" }}}}'

Step 2. Submit an object using synchronous post.

Using the token you just created (it should have capabilities sync:post  and error:post  specified) you should submit a dump using the mod_sync=1 parameter to tell the submission layer that you are expecting a synchronous response to this submission. 

$ curl -s --data-binary @datfc8.dmp "http://localhost.sp.backtrace.io:8081/api/post?token=&_mod_sync=1?format=dump

This error object is for an application called packrat . The fingerprint value is A  and the uname.sysname value is Linux .

If the request is successful, the response looks like the following:

{
    "response": "ok",
    "_rxid": "06000000-e660-9101-0000-000000000000",
    "object": "7",
    "fingerprint": "6238c76d08fa71d23cfc3ef6fcc591b795a2f3369962c7b8991aab058baa8560",
    "unique": false,
    "buckets": {
        "cts": {
            "count": 0,
            "token": "8a78f6f292ea68d0e49c28ca11675ec422f0aa93c186046472c2daddc3efebe0"
        }
    }
}

In this response, buckets.cts.count  is 0. This indicates that no other objects were submitted or additional assets for that combination of fingerprint  and uname.sysname  attributes.

In this example, we would like to ensure that advanced diagnostic data is included only once for every one of those unique combinations.

We will achieve this by specifying a header of X-Submission-Bucket  with the buckets.cts.token  value specified above. This header is used for submitting attachments or errors.

Step 3. Submit an attachment using the submission bucket token.

The submission bucket token is only valid for a limited time from submission time. The default is 1 minute after submission. Currently, this can be attached to any error upload or attachment upload request. If the submission bucket token is used, a count is incremented for the unique combination of attribute values of the error object. In the case of error uploads, the combination of attribute values of the error are used. In the case of attachment uploads, the combination of attribute values of the object the attachment is associated with is used.

$ curl -H "X-Submission-Bucket: 8a78f6f292ea68d0e49c28ca11675ec422f0aa93c186046472c2daddc3efebe0" --data-binary @configure "http://localhost.sp.backtrace.io:8081/api/post?token=&object=4&attachment_name=advanced_logs.txt

The crash reporting client makes the above request since buckets.cts.count  is 0. Since a valid X-Submission-Bucket  value is provided, the count for the combination of attribute values of object 4 , in this case a fingerprint of A  and a uname.sysname  value of Linux  is incremented from 0 to 1.

On the next submission of a dump with the same attribute values for fingerprint  and uname.sysname , the count will have a value of 1. The crash submission client is able to detect that advanced diagnostic data was already submitted for that combination of fingerprint  and uname.sysname  and so it is unnecessary to generate advanced diagnostic data for attachment.

{
    "response": "ok",
    "_rxid": "06000000-e663-9391-0000-000000000000",
    "object": "7",
    "fingerprint": "6238c76d08fa71d23cfc3ef6fcc591b795a2f3369962c7b8991aab058baa8560",
    "unique": false,
    "buckets": {
        "cts": {
            "count": 1,
            "token": "8a78f6f292ea68d0e49c28ca11675ec422f0aa93c186046472c2daddc3efebe0"
        }
    }
}