Error Reporting API Endpoints

These API endpoints allow you to interact with Error Reporting (Backtrace) functionality.

What You'll Need

• A Backtrace account (log in or sign up for a free trial license).
• Your subdomain name (used to connect to your Backtrace instance). For example, https://example-subdomain.sp.backtrace.io.
• A Backtrace project and an API token.

Submit Crash

POSThttp://api.backtrace.io/post

Submits crash object to Backtrace instance.

Parameters

token	| QUERY | REQUIRED | STRING | Your API token.
format	| QUERY | REQUIRED | STRING | The format of the crash you are submitting. Default value is json.
upload_file	| BODY | OPTIONAL | STRING | It allows to attach a file with the initial crash submission. It contains the location of file containing crash data to send.
body	| BODY | REQUIRED | STRING | The JSON body of the crash dump. The required fields for body are: uuid timestamp lang langVersion agent agentVersion threads mainThread
uuid	| BODY | REQUIRED | STRING | 16 bytes of randomness in human readable UUID format. The server will reject the request if UUID is already found.
timestamp	| BODY | REQUIRED | INTEGER | The UTC timestamp in seconds.
lang	| BODY | REQUIRED | STRING | The name of the programming language/environment this error originates from.
langVersion	| BODY | REQUIRED | STRING | The version of the programming language/environment this error originates from.
agent	| BODY | REQUIRED | STRING | The name of the client that is sending this error report.
agentVersion	| BODY | REQUIRED | STRING | The version of the client that is sending this error report.
threads	| BODY | REQUIRED | OBJECT | Contains a map of all threads running in the environment. It could be only one. The object is composed by the main object that is the key of the threads object and represents the unique ID of a thread. The object contains the following fields: name - A string that provides a small description of what the thread does. fault - A boolean value that denotes if a thread is a faulting thread. Rarely two faulted threads can be seen, if it happens, the first faulting thread listed gets the status of mainThread stack - An array composed by the following fields: guessed_frame - A boolean value that is true if the stack frame is created by hueristic method due to missing CFI, and false otherwise. funcName - A string value that identifies the function, method, or procedure name. If not provided then address must be provided. address - A string value that identifies the address of the stack frame. Required if funcName is not provided. line - A string value that identifies the line number in the source code of the stack frame. First line is 1. column - A string value that identifies the column number in the source code of the stack frame. First column is 1. sourceCode - A string value that identifies the ID of the source code file the stack frame is contained in. library - A string value that identifies the shared object, the library or the module name. debug_identifier - A string value that identifies the debug identifier for the library associated with this frame. faulted - A boolean value that indicates if this frame is known to to the faulting frame. registers - In this object the keys are the register names. Use any names that make sense for the architecture. These must correspond to the values in the arch definition. JSON does not support 64 bit integers, so you must set the correct type and then encode the 64 bit integers as a string.
mainThread	| BODY | REQUIRED | STRING | It represent the thread that either triggered the error or generated this object. The value of this field should be one of the keys in the threads object and cannot be null.
symbolication	| BODY | OPTIONAL | STRING | Specifies the symbolication that needs to be applied. Supported values are: minidump. sourcemap. proguard. This should not be specified for client-symbolicated objects.
entryThread	| BODY | OPTIONAL | STRING | Specifies which thread is the entry point or the starting thread. This must correspond to an entry in the threads field.
arch	| BODY | OPTIONAL | OBJECT | Specifies the CPU architecture information. It is required if you want to have registers in the stack frame. The object has two fields: name - On some systems the running program can be run with a different arch than the system itself. attributes.uname.machine has to do with the system arch; this field has to do with the running process arch. registers - It corresponds with registers in the stack frame. Specifies the names of the registers for this arch. The values are the types. Valid types are: i32 u32 i64 u64 f32 string If you use string, you can format the value as you want.
fingerprint	| BODY | OPTIONAL | STRING | This is a base64 encoded unique ID that groups the report with the same fingerprint (32 bytes). If omitted, a fingerprint will be generated from the submitted stack trace.
classifiers	| BODY | OPTIONAL | ARRAY of STRINGS | List of strings which are report classifications.
attributes	| BODY | OPTIONAL | OBJECT of KEY:VALUE Pairs | This is a set of key-value pairs that belong to the error report. The exact fields are not defined by this specification. It is up to the JSON consumer how to display or otherwise represent key/value pairs in this object. The value of a key-value pair can be a string, integer, or boolean. These attributes are indexed and searchable. Some of the possible values: application: foo cpu.iowait: 1234143 system.memory.buffers: 1234 uname.machine: x86_64 vm.swap.size: 1234 error.message: Unexpected token h
sourceCode	| BODY | OPTIONAL | OBJECT | The object include the source code for better debugging experience. The object is composed by the sourceCodeId object that is the ID of the source code. The object is composed by the following fields: text - A string that provides the full source file or a subset of it. If provided, then also startline should be provided. If not provided, then path must be provided. startLine - An integer value that provides the line number that the provided text starts on. It is required if text is provided. First line is 1. startColumn - An integer value that provides the column number that the first byte in the text segment is. First column is 1. startPos - An integer value that provides the absolute byte index in the original file that the provided segment is part of. First byte is 0. path - A string value that provides the file system path to the original source code file. If not provided, then text must be provided. tabWidth - An integer value that informs source code display how many spaces a tab should represent.
memory	| BODY | OPTIONAL | ARRAY | Provides arbitrary slices of memory. The array is composed by the following keys: start - An integer offset that this slice of memory starts at. The 64 bit integers are represented as strings. size - The number of bytes of the slice. Optional if you include data. data - Base64 encoded bytes of the slice of memory. If provided, size can be inferred from it. perms - The object that sets of permissions of this slice of memory. It is composed by the boolean properties: read write exec
annotations	| BODY | OPTIONAL | ARRAY or OBJECT or STRING | A generic, non-indexed user-provided property. The names are free, the values can be of any type, and there is no limit to nesting.
modules	| BODY | OPTIONAL | ARRAY | A list of modules as loaded in memory, used to symbolicate stack traces. The array is composed by the following keys: start - An integer offset that the module starts at. 64 bit integers are represented as strings. size - The number of bytes occupied by the module. code_file - A string that indicates the path that the module is loaded from. version - The human-readable version string for the module. debug_file - The file containing debug information for the module. debug_identifier - The debug file identifier. debug_file_exists - A boolean value that indicates if symbolication was able to locate the debug file.

Sample Request

curl --request POST 'https://api.backtrace.io/post?token=<your_token>&format=<format>' \
-H 'Content-Type: application/json' \
-d '{
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "timestamp": 1475530543,
  "lang": "nodejs",
  "langVersion": "v4.5.0",
  "agent": "backtrace-node",
  "agentVersion": "0.4.0",
  "threads": {
    "main": {
      "name": "my super cool thread",
      "fault": true,
      "stack": [
        {
          "guessed_frame": "false",
          "funcName": "main",
          "address": "16045690984833335023",
          "line": "10",
          "column": "19",
          "sourceCode": "o9BYbg2uO+1m",
          "library": "/home/example/nodebt/test.js",
          "callstack_state": "1",
          "registers": {
            "rax": "16045690984833335023",
            "rip": 1234,
            "FLAGS": "E:1 B:0 C:1"
          }
        }
      ]
    },
    "mainThread": "main"
  }
}'

Responses

200	Success.
400	Malformed request.
403	Invalid token.

Sample Response

{
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "timestamp": 1475530543,
  "lang": "nodejs",
  "langVersion": "v4.5.0",
  "agent": "backtrace-node",
  "agentVersion": "0.4.0",
  "threads": {
    "main": {
      "name": "my super cool thread",
      "fault": true,
      "stack": [
        {
          "guessed_frame": "false",
          "funcName": "main",
          "address": "16045690984833335023",
          "line": "10",
          "column": "19",
          "sourceCode": "o9BYbg2uO+1m",
          "library": "/home/example/nodebt/test.js",
          "callstack_state": "1",
          "registers": {
            "rax": "16045690984833335023",
            "rip": 1234,
            "FLAGS": "E:1 B:0 C:1"
          }
        }
      ]
    }
  },
  "mainThread": "main",
  "entryThread": "12341324",
  "arch": {
    "name": "x64",
    "registers": {
      "rax": "u64",
      "rip": "u32",
      "FLAGS": "string"
    }
  },
  "fingerprint": "kqJB7mgd22nvWGxYU2MvCpLRTiNWO1C8KFS434eTz1M=",
  "callstack": {
    "frames": ["one@foo.js:123", "two@bar.js", "three"]
  },
  "classifiers": ["SyntaxError"],
  "attributes": {
    "application": "foo",
    "cpu.boottime": 1234234234,
    "cpu.context": 1234,
    "cpu.idle": 1234234,
    "cpu.iowait": 1234143,
    "cpu.irq": 1234113,
    "cpu.kernel": "foo",
    "cpu.nice": "foo",
    "cpu.process.blocked": 1234,
    "cpu.process.count": 1234,
    "cpu.process.running": 1234,
    "cpu.softirq": "foo",
    "cpu.user": 1234,
    "descriptor.count": 1234,
    "fault.address": "foo",
    "fingerprint": "foo",
    "hostname": "foo",
    "process.age": 1234,
    "sched.cs.involuntary": 1234,
    "sched.cs.voluntary": 1234,
    "system.memory.active": 1234,
    "system.memory.buffers": 1234,
    "system.memory.cached": 1234,
    "system.memory.dirty": 1234,
    "system.memory.free": 1234,
    "system.memory.inactive": 1234,
    "system.memory.slab": 1234,
    "system.memory.swap.cached": 1234,
    "system.memory.swap.free": 1234,
    "system.memory.swap.total": 1234,
    "system.memory.total": 1234,
    "system.memory.vmalloc.chunk": 1234,
    "system.memory.vmalloc.total": 1234,
    "system.memory.vmalloc.used": 1234,
    "system.memory.writeback": 1234,
    "uname.machine": "x86_64",
    "uname.release": "4.4.0-38-generic",
    "uname.sysname": "Linux",
    "uname.version": "#57-Ubuntu SMP Tue Sep 6 15:42:33 UTC 2016",
    "vm.data.size": 1234,
    "vm.locked.size": 1234,
    "vm.pte.size": 1234,
    "vm.rss.peak": 1234,
    "vm.rss.size": 1234,
    "vm.shared.size": 1234,
    "vm.stack.size": 1234,
    "vm.swap.size": 1234,
    "vm.vma.peak": 1234,
    "vm.vma.size": 1234,
    "mem.rss": 1234,
    "mem.heap.total": 1234,
    "mem.heap.used": 1234,
    "error.message": "Unexpected token h"
  },
  "sourceCode": {
    "o9BYbg2uO+1m": {
      "text":
        "var bt = require('backtrace.io');\nbt.initialize({\n  debugBacktrace: true,\n  timeout: 9999999,\n});\n\nmain();\n\nfunction main() {\n  var json = JSON.parse(\"example\");\n}\n",
      "startLine": 1,
      "startColumn": 1,
      "startPos": 0,
      "path": "/home/andy/tmp/nodebt/test.js",
      "tabWidth": 8
    }
  },
  "memory": [
    {
      "start": "16045690984833335023",
      "size": 1024,
      "data": "R56cuNuwpqEJe8n3i4Ojlxt59fpPMU74RygKv5byWJzoHYwCr",
      "perms": {
        "read": true,
        "write": true,
        "exec": false
      }
    }
  ],
  "annotations": {
    "Environment Variables": {
      "ENV_VAR_EXAMPLE": "example value"
    },
    "Some Property Name": true,
    "Dependencies": {
      "dependencyName": {
        "requestedVersion": "~1.2.0",
        "installedVersion": "1.2.0",
        "dependencies": {}
      }
    }
  }
}