From 77245ad44316d2babb757b34f827de0677984476 Mon Sep 17 00:00:00 2001 From: Dominik Buszowiecki <44422760+DominikB2014@users.noreply.github.com> Date: Thu, 13 Jun 2024 13:42:58 -0400 Subject: [PATCH] feat(insights): asset module documentation (#1306) * asset module initial docs * update broken link * Update assets.mdx Co-authored-by: George Gritsouk <989898+gggritso@users.noreply.github.com> * Update assets.mdx Co-authored-by: George Gritsouk <989898+gggritso@users.noreply.github.com> * Update assets.mdx Co-authored-by: George Gritsouk <989898+gggritso@users.noreply.github.com> * Update assets.mdx Co-authored-by: George Gritsouk <989898+gggritso@users.noreply.github.com> * code review * Update src/docs/sdk/performance/modules/assets.mdx Co-authored-by: Ash <0Calories@users.noreply.github.com> * asset data description * update snippet * update typos --------- Co-authored-by: George Gritsouk <989898+gggritso@users.noreply.github.com> Co-authored-by: Ash <0Calories@users.noreply.github.com> --- src/docs/sdk/performance/modules/assets.mdx | 51 +++++++++++++++++++ src/docs/sdk/performance/modules/index.mdx | 2 +- .../sdk/performance/modules/resources.mdx | 5 -- 3 files changed, 52 insertions(+), 6 deletions(-) create mode 100644 src/docs/sdk/performance/modules/assets.mdx delete mode 100644 src/docs/sdk/performance/modules/resources.mdx diff --git a/src/docs/sdk/performance/modules/assets.mdx b/src/docs/sdk/performance/modules/assets.mdx new file mode 100644 index 0000000000..8518d68f08 --- /dev/null +++ b/src/docs/sdk/performance/modules/assets.mdx @@ -0,0 +1,51 @@ +--- +title: 'Assets Module' +--- + +Browser SDKs should auto-instrument javascript, stylesheet and image assets with the ops `resource.script`, `resource.css` and `resource.img` respectively. The Asset module is technology agnostic, it only cares about span data properties. + +## Span conventions + +### Span Description + +The description of an asset span should be the full URL of the asset, e.g., `https://cdn.com/main.hash123.js?q=11274713`. + +### Span Data + +The following data should be provided for each asset span + +| Data Key | Type | Description | Notes | +| :------------------------------------- | :------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | +| `http.response_content_length` | `int` | encoded size of the asset in `bytes` (what is sent over the network) | required on all asset operations | +| `http.decoded_response_content_length` | `int` | the decoded size of the asset in `bytes` | recommended; if not provided, would show up as 0 on the resource summary size chart | +| `http.response_transfer_size` | `int` | the size of the encoded asset plus the response headers in `bytes` | recommended; if not provided, would show up as 0 on the resource summary size chart | +| `resource.render_blocking_status` | `string` | whether the resource blocks UI rendering, values are 'non-blocking' or 'blocking' | recommended; if not provided, the asset can't be narrowed down by their render blocking status | + +## Instrumentation Example + +The SDK should create a span per asset fetched by the browser. + +Consider a basic HTML file that fetches a single script: + +```html + + + +``` + +Should result in the following span, assuming the request was successful: + +```json +{ + "description": "https://cdn.com/main.hash123.js", + "op": "resource.script", + "data": { + "http.decoded_response_content_length": 123, + "http.response_content_length": 123, + "http.response_transfer_size": 123, + "resource.render_blocking_status": "blocking", + "server.address": "cdn.com", + ... other span properties + } +} +``` diff --git a/src/docs/sdk/performance/modules/index.mdx b/src/docs/sdk/performance/modules/index.mdx index 9802fe18d1..ee25e3e524 100644 --- a/src/docs/sdk/performance/modules/index.mdx +++ b/src/docs/sdk/performance/modules/index.mdx @@ -10,6 +10,6 @@ The list below contains SDK documentation for our various Insights Modules (form - [Queues](/sdk/performance/modules/queues/) - [Queries](/sdk/performance/modules/queries/) - [Requests](/sdk/performance/modules/requests/) -- [Resources](/sdk/performance/modules/resources/) +- [Assets](/sdk/performance/modules/assets/) - [Screen Loads](/sdk/performance/modules/screen-loads/) - [Web Vitals](/sdk/performance/modules/web-vitals/) diff --git a/src/docs/sdk/performance/modules/resources.mdx b/src/docs/sdk/performance/modules/resources.mdx deleted file mode 100644 index f6674faac6..0000000000 --- a/src/docs/sdk/performance/modules/resources.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: 'Resources Module' ---- - -to be defined ...