From 249e575ef279500884b95683b42ff61390bb69b6 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Wed, 25 Nov 2020 00:35:44 +0100 Subject: [PATCH 1/2] feat: Document WASM protocol extensions --- src/docs/sdk/event-payloads/debugmeta.mdx | 49 ++++++++++++++++++++-- src/docs/sdk/event-payloads/stacktrace.mdx | 12 +++++- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/src/docs/sdk/event-payloads/debugmeta.mdx b/src/docs/sdk/event-payloads/debugmeta.mdx index 6aa76ef855..9db2f565f1 100644 --- a/src/docs/sdk/event-payloads/debugmeta.mdx +++ b/src/docs/sdk/event-payloads/debugmeta.mdx @@ -57,9 +57,8 @@ prefixed with `"0x"`. `image_size` -: **Required**. The size of the image in virtual memory. If missing, Sentry will -assume that the image spans up to the next image, which might lead to invalid -stack traces. +: The size of the image in virtual memory. If missing, Sentry will assume that +the image spans up to the next image, which might lead to invalid stack traces. `debug_id` @@ -308,6 +307,50 @@ Example: } ``` +### WASM Images + +WASM images are used on for WebAssembly. Their structure is identical to other +native images. + +Attributes: + +`type` + +: **Required**. Type of the debug image. Must be `"wasm"`. + +`debug_id` + +: **Required**. Identifier of the dynamic library or executable. It is the value +of the `build_id` custom section and must be formatted as UUID truncated to the +leading 16 bytes. + +`debug_file` + +: _Optional_: Name or absolute URL to the WASM file containing debug +information for this image. This value might be required to retrieve debug +files from certain symbol servers. + +`code_id` + +: _Optional_. Identifier of the WASM file. It is the value of the +`build_id` custom section formatted as HEX string. It can be omitted in case +the section contains a UUID (16 bytes). + +`code_file` + +: _Optional_. The absolute URL to the wasm file. This helps +to locate the file if it is missing on Sentry. + +Example: + +```json +{ + "type": "wasm", + "debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a", + "debug_file": "sample.wasm" +} +``` + ### Proguard Images Proguard images refer to `mapping.txt` files generated when Proguard obfuscates diff --git a/src/docs/sdk/event-payloads/stacktrace.mdx b/src/docs/sdk/event-payloads/stacktrace.mdx index f80405e411..37fa8f9551 100644 --- a/src/docs/sdk/event-payloads/stacktrace.mdx +++ b/src/docs/sdk/event-payloads/stacktrace.mdx @@ -109,7 +109,17 @@ The following attributes are primarily used for C-based languages: : An optional instruction address for symbolication. This should be a string with a hexadecimal number that includes a `0x` prefix. If this is set and a known image is defined in the [Debug Meta Interface](/sdk/event-payloads/debugmeta/), then -symbolication can take place. +symbolication can take place. Note that when `in_image` is provided the value +is considered to be relative within the image, otherwise absolute in the +unified address space. + +`in_image` + +: Optionally a reference into the `images` array in the `debug_meta` interface. +When provided this must be the `debug_id` of the image in question. This changes +the addressing mode from absolute in address space to absolute within the target +image. This for instance is necessary for WASM processing as WASM does not use +a unified address space. `symbol_addr` From 983162c44c4497eff59529321395a7804f19805b Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Fri, 27 Nov 2020 00:19:28 +0100 Subject: [PATCH 2/2] feat: Update develop docs to latest WASM protocol --- src/docs/sdk/event-payloads/debugmeta.mdx | 5 +++-- src/docs/sdk/event-payloads/stacktrace.mdx | 18 +++++++++--------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/src/docs/sdk/event-payloads/debugmeta.mdx b/src/docs/sdk/event-payloads/debugmeta.mdx index 9db2f565f1..ec4fd958f4 100644 --- a/src/docs/sdk/event-payloads/debugmeta.mdx +++ b/src/docs/sdk/event-payloads/debugmeta.mdx @@ -328,7 +328,8 @@ leading 16 bytes. : _Optional_: Name or absolute URL to the WASM file containing debug information for this image. This value might be required to retrieve debug -files from certain symbol servers. +files from certain symbol servers. This should correspond to the externalized +URL pulled from the `external_debug_info` custom section. `code_id` @@ -338,7 +339,7 @@ the section contains a UUID (16 bytes). `code_file` -: _Optional_. The absolute URL to the wasm file. This helps +: **Required**. The absolute URL to the wasm file. This helps to locate the file if it is missing on Sentry. Example: diff --git a/src/docs/sdk/event-payloads/stacktrace.mdx b/src/docs/sdk/event-payloads/stacktrace.mdx index 37fa8f9551..9122e07e2f 100644 --- a/src/docs/sdk/event-payloads/stacktrace.mdx +++ b/src/docs/sdk/event-payloads/stacktrace.mdx @@ -109,23 +109,23 @@ The following attributes are primarily used for C-based languages: : An optional instruction address for symbolication. This should be a string with a hexadecimal number that includes a `0x` prefix. If this is set and a known image is defined in the [Debug Meta Interface](/sdk/event-payloads/debugmeta/), then -symbolication can take place. Note that when `in_image` is provided the value -is considered to be relative within the image, otherwise absolute in the -unified address space. +symbolication can take place. Note that the `addr_mode` attribute can +control the behavior of this address. -`in_image` +`addr_mode` -: Optionally a reference into the `images` array in the `debug_meta` interface. -When provided this must be the `debug_id` of the image in question. This changes -the addressing mode from absolute in address space to absolute within the target -image. This for instance is necessary for WASM processing as WASM does not use +: Optionally changes the addressing mode. The default value is the same as `"abs"` +which means absolute referencing. This can also be set to `"rel:DEBUG_ID"` or +`"rel:IMAGE_INDEX"` to make addresses relative to an object referenced by debug id +or index. This for instance is necessary for WASM processing as WASM does not use a unified address space. `symbol_addr` : An optional address that points to a symbol. We use the instruction address for symbolication, but this can be used to calculate an instruction -offset automatically. +offset automatically. Note that the `addr_mode` attribute can +control the behavior of this address. `image_addr`