diff --git a/docs/api/index.md b/docs/api/index.md index 5fe9b5340..41cf38844 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -5,13 +5,14 @@ title: Overview # API Symbolicator exposes a HTTP API to allow symbolication of raw native stack -traces and minidumps. All information necessary for symbolication needs to be -part of the request, such as external buckets and their auth tokens or full -stack traces. There are the following endpoints: +traces, minidumps, and JavaScript stack traces. All information necessary for symbolication +needs to be part of the request, such as external buckets and their auth tokens +or full stack traces. There are the following endpoints: - `POST /symbolicate`: Symbolicate raw native stacktrace - `POST /minidump`: Symbolicate a minidump and extract information - `POST /applecrashreport`: Symbolicate an Apple Crash Report +- `POST /symbolicate-js`: Symbolicate JavaScript stacktrace - `GET /requests/:id`: Status update on running symbolication jobs - `GET /healthcheck`: System status and health monitoring diff --git a/docs/api/response.md b/docs/api/response.md index 3d45842ab..19fa67f6b 100644 --- a/docs/api/response.md +++ b/docs/api/response.md @@ -4,7 +4,9 @@ title: Symbolication Response # Symbolication Response -The response to a symbolication request is a JSON object which contains +## Native Response + +The response to a native symbolication request is a JSON object which contains different data depending on the status of the symbolication job: - `pending`: Symbolication has not finished yet; try again later. This is only @@ -14,7 +16,7 @@ different data depending on the status of the symbolication job: - `error`: Something went wrong during symbolication, and details are in the payload. -## Success Response +### Success Response Symbol server responds with _200 OK_ and the response payload listed below if symbolication succeeds within a configured timeframe (around 20 seconds): @@ -73,7 +75,7 @@ occurred during symbolication, such as missing symbol files or unresolvable addresses within symbols are reported as values for `status` in both modules and frames. -## Note on Addresses +### Note on Addresses Addresses (`instruction_addr` and `sym_addr`) can come in two versions. They can be absolute or relative. Symbolicator will always try to make addresses @@ -82,7 +84,7 @@ not have absolute addresses in which case the addresses stay relative. This is identified by the `addr_mode` property. When it's set to `"abs"` it means the addresses are absolute, when `"rel:X"` it's relative to module index `X`. -## Backoff Response +### Backoff Response If symbolication takes longer than the threshold `timeout`, the server instead responds with a backoff response. It will then continue to fetch symbols and @@ -105,7 +107,7 @@ guarantee. The request may be repeated at any time: GET /requests/deadbeef?timeout=123 -## Invalid Request Response +### Invalid Request Response If the user provided a non-existent request ID, the server responds with _404 Not Found_. @@ -115,3 +117,71 @@ deploy. Clients must expect that 404 is returned even for valid request IDs and then re-schedule symbolication On a related note, state on the server is generally ephemeral. + + +## JavaScript Response + +The response to a JavaScript symbolication request is a JSON object which contains +a list of original raw stack traces, corresponding list of processed stack traces +and an optional list of errors that happened during symbolication. + +```javascript +{ + "stacktraces": [ + { + "frames": [ + { + "function": "onFailure", + "filename": "test.js", + "module": "files/test", + "abs_path": "http://localhost:/files/test.js", + "lineno": 5, + "colno": 11, + "pre_context": [ + "var makeAFailure = (function() {", + " function onSuccess(data) {}", + "", + " function onFailure(data) {" + ], + "context_line": " throw new Error('failed!');", + "post_context": [ + " }", + "", + " function invoke(data) {", + " var cb = null;", + " if (data.failed) {" + ], + "data": { + "sourcemap": "http://localhost:/files/app.js.map" + } + } + ] + } + ], + "raw_stacktraces": [ + { + "frames": [ + { + "abs_path": "http://localhost:/files/app.js", + "lineno": 1, + "colno": 64, + "context_line": "var makeAFailure=function(){function n(n){}function e(n){throw new Error(\"failed!\")}function r(r){var i=null;if(r.failed){i=e}else{i=n}i(r)} {snip}", + "post_context": [ + "", + "", + "//# sourceMappingURL=a.different.map", + "", + "//@ sourceMappingURL=another.different.map" + ] + } + ] + } + ], + "errors": [ + { + "abs_path": "http://localhost:/assets/missing_bar.js", + "type": "missing_source" + } + ] +} +``` diff --git a/docs/api/sourcemaps.md b/docs/api/sourcemaps.md new file mode 100644 index 000000000..2a54b0b4d --- /dev/null +++ b/docs/api/sourcemaps.md @@ -0,0 +1,87 @@ +--- +title: POST /symbolicate-js +--- + +# Symbolication Request + +```http +POST /symbolicate-js?timeout=123&scope=123 HTTP/1.1 +Content-Type: application/json + +{ + "source": { + "id": "", + "url": "https://sentry.io/api/0/projects/sentry-org/sentry-project/artifact-lookup/", + "token": "secret" + }, + "stacktraces": [ + { + "frames": [ + { + "function": "x", + "module": "x", + "filename": "x", + "abs_path": "x", + "lineno": 1, + "colno": 1, + "in_app": true + } + ] + } + ], + "modules": [ + { + "code_file": "some-code-file", + "debug_id": "some-debug-id", + "type": "debug_id" + } + ], + "dist": "production", + "release": "1.33.1", + "scraping": { + "enabled": true, + "allowed_origins": ["*.domain.com"] + } +} +``` + +## Query Parameters + +- `timeout`: If given, a response status of `pending` might be sent by the + server. +- `scope`: An optional scope which will be used to isolate cached files from + each other + +## Request Body + + pub scraping: ScrapingConfig, + pub options: JsRequestOptions, + +A JSON payload describing the stack traces and code modules for symbolication, +as well as configuration for scraping sources from external servers: + +- `source`: A descriptor for the Sentry source to be used for symbolication. See + [Sentry](index.md) source. +- `modules`: A list of source code files with a corresponding debug id that + were loaded during JS code execution. The list is handled by the Sentry source. +- `stacktrace`: A list of stacktraces to symbolicate. + - `frames`: A list of frames with corresponding `abs_path`, `lineno`, + and other optional fields like `colno` or minified `function` name. +- `release`: Name of Sentry `release` for the processed request. +- `dist`: Name of Sentry `dist` for the processed request. +- `scraping`: Configuration for scraping of JS sources and sourcemaps from the web. + - `enabled`: Whether scraping should happen at all. + - `allowed_origins`: A list of "allowed origin patterns" that control what + URLs we are allowed to scrape from. Allowed origins may be defined in several ways: + - `http://domain.com[:port]`: Exact match for base URI (must include port). + - `*`: Allow any domain. + - `*.domain.com`: Matches domain.com and all subdomains, on any port. + - `domain.com`: Matches domain.com on any port. + - `*:port`: Wildcard on hostname, but explicit match on port. + - `headers`: A map of headers to send with every HTTP request while scraping. +- `options`: Symbolication-specific options which control the endpoint's behavior. + - `apply_source_context`: Whether to apply source context for the stack frames. + +## Response + +See [Symbolication Response](response.md). diff --git a/docs/index.md b/docs/index.md index 06ea377b8..20b7560d7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,8 +8,8 @@ title: Introduction

Symbolicator is a standalone service that resolves function names, file location -and source context in native stack traces. It can process Minidumps and Apple -Crash Reports. Additionally, Symbolicator can act as a proxy to symbol servers +and source context in native and JavaScript stack traces. It can process minidumps, Apple +crash reports and source maps. Additionally, Symbolicator can act as a proxy to symbol servers supporting multiple formats, such as Microsoft's symbol server or Breakpad symbol repositories. diff --git a/mkdocs.yml b/mkdocs.yml index b8f676e99..99be881ef 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,5 +25,6 @@ nav: - api/minidump.md - api/symbolication.md - api/applecrashreport.md + - api/sourcemaps.md - api/response.md - api/proxy.md