From 3563e4b8e74a6b5c98cdfdbb9ee02ce115684320 Mon Sep 17 00:00:00 2001 From: Liza Mock Date: Thu, 3 Oct 2024 15:38:08 -0700 Subject: [PATCH 1/4] Update Distributed Tracing Page Make a few more tweaks to make this page easier to digest. --- .../key-terms/tracing/distributed-tracing.mdx | 86 +++++++++---------- 1 file changed, 40 insertions(+), 46 deletions(-) diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx index 4557deee220af..fddd0021e34fb 100644 --- a/docs/concepts/key-terms/tracing/distributed-tracing.mdx +++ b/docs/concepts/key-terms/tracing/distributed-tracing.mdx @@ -21,7 +21,45 @@ It's important to note that tracing is not [profiling](https://github.com/produc Learn more in this [Tracing: Frontend issues with backend solutions](https://sentry.io/resources/tracing-frontend-issues-with-backend-solutions/?original_referrer=https%3A%2F%2Fblog.sentry.io%2F) workshop. -### Why Tracing? +### The Tracing Data Model + +Ultimately, any data structure is defined by the kind of data it contains, and relationships between data structures are defined by how links between them are recorded. Traces, transactions, and spans are no different. + +#### Traces + +Traces are defined as the collection of all transactions that share a `trace_id` value. + +#### Transactions + +Transactions share most properties (start and end time, tags, etc.) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. + +Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, and `Sentry.setExtra()`.) + +Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. + + + +Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. + + + +#### Spans + +Span data includes: + +- `parent_span_id`: ties the span to its parent span +- `op`: short string identifying the type or category of operation the span is measuring +- `start_timestamp`: when the span was opened +- `end_timestamp`: when the span was closed +- `description`: longer description of the span's operation +- `status`: short code indicating operation's status +- `tags`: key-value pairs holding additional data about the span +- `data`: arbitrarily-structured additional data about the span + +An example use of the `op` and `description` properties together is `op: db.query` and `description: SELECT * FROM users WHERE last_active < %s`. The `status` property indicates the success or failure of the span's operation, or a response code for HTTP requests. `Tags` and `data` attach further contextual information to the span, such as `function: middleware.auth.is_authenticated` for a function call or `request: {url: ..., headers: ... , body: ...}` for an HTTP request. +To search span data see [Searchable Properties](/concepts/search/searchable-properties/spans/) + +### What Can Tracing Help With? Applications consist of interconnected components or services. For example, a modern web application may include: @@ -47,7 +85,7 @@ Top-level spans can be broken down into smaller spans, mirroring the way one fun ![Diagram illustrating the parent-child relationship between spans within a single transaction.](./img/diagram-transaction-spans.png) -### Tracing, Transaction & Span Example: Investigating Slow Page Load +### Tracing Example: Investigating Slow Page Load Suppose your web application is slow to load. A lot has to happen for your app to get to a usable state: multiple requests to your backend, calls to your database or external APIs, and browser processing. Which part is slowing things down? @@ -142,50 +180,6 @@ For a backend periodically polling for data from an external service, processing \* Starred spans are parents of later transactions (and their root spans). -### The Tracing Data Model - -> "Show me your flowchart and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowchart; it'll be obvious." -> -> -- [Fred Brooks](https://en.wikipedia.org/wiki/Fred_Brooks), The Mythical Man Month (1975) - -Ultimately, any data structure is defined by the kind of data it contains, and relationships between data structures are defined by how links between them are recorded. Traces, transactions, and spans are no different. - -#### Traces - -Traces are defined as the collection of all transactions that share a `trace_id` value. - -#### Transactions - -Transactions share most properties (start and end time, tags, etc.) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. - - - -Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. - - - -Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, and `Sentry.setExtra()`.) - -Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. - - - -#### Spans - -Span data includes: - -- `parent_span_id`: ties the span to its parent span -- `op`: short string identifying the type or category of operation the span is measuring -- `start_timestamp`: when the span was opened -- `end_timestamp`: when the span was closed -- `description`: longer description of the span's operation -- `status`: short code indicating operation's status -- `tags`: key-value pairs holding additional data about the span -- `data`: arbitrarily-structured additional data about the span - -An example use of the `op` and `description` properties together is `op: db.query` and `description: SELECT * FROM users WHERE last_active < %s`. The `status` property indicates the success or failure of the span's operation, or a response code for HTTP requests. `Tags` and `data` attach further contextual information to the span, such as `function: middleware.auth.is_authenticated` for a function call or `request: {url: ..., headers: ... , body: ...}` for an HTTP request. -To search span data see [Searchable Properties](/concepts/search/searchable-properties/spans/) - ### Important Information About Tracing, Spans & Transactions #### Trace Duration From 6ea31a8f5074e6be2f9a7ae2b88057a563ddfef2 Mon Sep 17 00:00:00 2001 From: Liza Mock Date: Tue, 8 Oct 2024 11:49:02 -0700 Subject: [PATCH 2/4] Update docs/concepts/key-terms/tracing/distributed-tracing.mdx --- docs/concepts/key-terms/tracing/distributed-tracing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx index fddd0021e34fb..6ca0f42ca2ca9 100644 --- a/docs/concepts/key-terms/tracing/distributed-tracing.mdx +++ b/docs/concepts/key-terms/tracing/distributed-tracing.mdx @@ -31,7 +31,7 @@ Traces are defined as the collection of all transactions that share a `trace_id` #### Transactions -Transactions share most properties (start and end time, tags, etc.) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. +Transactions share most properties (start and end time, tags, and so on) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, and `Sentry.setExtra()`.) From a698853a0cdcf18053633ec4451531e600596c4a Mon Sep 17 00:00:00 2001 From: Liza Mock Date: Tue, 8 Oct 2024 11:49:09 -0700 Subject: [PATCH 3/4] Update docs/concepts/key-terms/tracing/distributed-tracing.mdx --- docs/concepts/key-terms/tracing/distributed-tracing.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx index 6ca0f42ca2ca9..69af5504ee88c 100644 --- a/docs/concepts/key-terms/tracing/distributed-tracing.mdx +++ b/docs/concepts/key-terms/tracing/distributed-tracing.mdx @@ -35,7 +35,6 @@ Transactions share most properties (start and end time, tags, and so on) with th Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, and `Sentry.setExtra()`.) -Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. From c4c5555a2cbffb0bf28141b5fd04858c236f27b9 Mon Sep 17 00:00:00 2001 From: Liza Mock Date: Tue, 8 Oct 2024 11:49:15 -0700 Subject: [PATCH 4/4] Update docs/concepts/key-terms/tracing/distributed-tracing.mdx --- docs/concepts/key-terms/tracing/distributed-tracing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx index 69af5504ee88c..5b100493f1956 100644 --- a/docs/concepts/key-terms/tracing/distributed-tracing.mdx +++ b/docs/concepts/key-terms/tracing/distributed-tracing.mdx @@ -33,7 +33,7 @@ Traces are defined as the collection of all transactions that share a `trace_id` Transactions share most properties (start and end time, tags, and so on) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. -Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, and `Sentry.setExtra()`.) +Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, or `Sentry.setExtra()`.)