|
1 | 1 | --- |
2 | 2 | title: "Trace Explorer" |
3 | 3 | sidebar_order: 30 |
4 | | -description: "Learn how to use the Traces page to search span data, including conditions relating to the structure of the trace itself, and find distributed traces that help you get to the root cause of the problem." |
| 4 | +description: "Learn how to use the Trace Explorer to search span data, find distributed traces, and debug performance issues across your entire application stack." |
5 | 5 | --- |
6 | 6 |
|
7 | 7 | <Note> |
8 | 8 | The Traces page is currently in beta. Beta features are still in progress and may have bugs. We recognize the irony. |
9 | 9 | </Note> |
10 | 10 |
|
11 | | -The [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page lets you search for individual spans that make up a trace, linked by a trace id. This gives you a connected view of your application from the frontend to the backend and/or between different applications and workflows. You can query and find particular distributed traces to help you debug problems or optimize hot paths in your application. |
| 11 | +The [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page allows you to query individual spans within traces and analyze distributed traces across your entire application stack. When you search by spans, your queries are more targeted and more precise. This helps you pinpoint specific operations that may be causing problems (like slow database queries, API calls, and so on) across multiple traces. |
12 | 12 |
|
| 13 | +## Key Concepts |
| 14 | +- **Trace**: A collection of spans representing the end-to-end journey of a request through your system that all share the same trace ID. |
| 15 | +- **Distributed Trace**: A collection of spans representing the end-to-end journey of a request from your frontend to your backend that all share the same trace ID. (In order for this to work, you have to have Sentry SDKs instrumented for both your backend and your frontend.) |
| 16 | +- **Span**: An individual unit of work within a trace, such as a database query or an API call. |
13 | 17 |
|
14 | | -### Build a New Traces Query |
| 18 | +## How to Build a Span Query |
15 | 19 |
|
16 | | -From the **Traces** page, you can build a query by applying up to three search conditions to modify the results of the query. |
| 20 | +To get started, go to the [Traces](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page in Sentry. You'll be able to apply up to three types of span search conditions in the search bar. To see all available search conditions, click on the "all" tab once you start typing in your search. You'll be automatically prompted once you choose your search criteria. You'll also be able to filter by environment and date range. |
17 | 21 |
|
18 | | -All your search conditions should be targetting spans. |
| 22 | +### Span Search Conditions |
19 | 23 |
|
20 | | -## Query Results |
| 24 | +Each set of search conditions helps you find a specific kind of span within a trace. You can either: |
21 | 25 |
|
22 | | - |
| 26 | +- Use a single set of conditions to search across all spans. |
| 27 | +**Example: ** Single condition: Find traces where a user with email `[email protected]` loaded a specific frontend route: |
| 28 | + |
23 | 29 |
|
24 | | -Each row in the results represents a trace, with the first row of the table auto expanded to help interpret results while searching. |
| 30 | +- Use multiple sets of conditions to search for traces containing all specified span types. |
| 31 | +**Example: ** Multiple conditions: Find traces where a user with the email `[email protected]` loaded a page on your frontend on a specific route AND a slow database query was present: |
| 32 | + |
25 | 33 |
|
26 | | -For each of the top-level trace rows in the table we display: |
27 | | -- A trace id, which links out to the trace in question if you want to see the trace with the [Trace View](/concepts/key-terms/tracing/trace-view/). |
28 | | -- The project for the traces |
29 | | -- A trace name derived from either the root transaction or the first transaction if the trace doesn't have a consistent root transaction |
30 | | -- The number of spans matching your search conditions for that trace, versus the total number of spans inside that trace |
31 | | -- An approximate timeline of significant spans inside of the trace to help visually interpret span start and end times |
32 | | -- A duration, which is derived from the beginning of the first span to the end of the last span in a trace |
33 | | -- The relative time for when the trace happened, which also contains the exact time on hover |
34 | | -- A link to any issues associated to this trace |
| 34 | +Because traces range accross multiple projects, there's no project filter, but you can filter by projects with similar sets of span conditions by adding `project:your-project-here` in the search. |
35 | 35 |
|
36 | | -Within each trace, we also return some of your matching spans to help you interpret your search conditions. |
37 | | -In this span table within each trace we display: |
38 | | -- A span id, which links to the [Trace View](/concepts/key-terms/tracing/trace-view/) |
39 | | -- A span description, which includes the project, `span.op` and `span.description` to help you identify the span |
40 | | -- The timeline of the span, which you can use with the trace timeline above to get an idea for when and where in the trace the span happened |
41 | | -- The duration of the span |
42 | | -- The relative time of when the span happened |
| 36 | +### Search Syntax |
43 | 37 |
|
44 | | -## How to Search Traces |
| 38 | +The Query Builder uses [Sentry's standard search syntax](/concepts/search/). Here are a few key points to keep in mind: |
| 39 | + |
| 40 | +- Use built-in [span properties](/concepts/search/searchable-properties/spans/) or custom tags. |
| 41 | +- Combine conditions with `AND` and `OR` (with some limitations on aggregates). |
| 42 | +- Use functions like `count()` for advanced queries. |
| 43 | + |
| 44 | +For a list of built-in key fields used in Sentry, check out our [Searchable Properties for Spans documentation](/concepts/search/searchable-properties/spans/). |
| 45 | + |
| 46 | +<Note> |
| 47 | + |
| 48 | +Trace Explorer uses sampled data. Your search results may be limited based on sampling rates and retention policies. Learn more about [retention priorities](/product/performance/retention-priorities/). |
| 49 | + |
| 50 | +</Note> |
| 51 | + |
| 52 | +## Search Query Results |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +Search results are displayed as a list of traces. Each row corresponds to a single trace and has the below fields: |
| 57 | + |
| 58 | +- **Trace ID**: Links to the detailed [Trace View](/concepts/key-terms/tracing/trace-view/). |
| 59 | +- **Project**: The associated Sentry project. |
| 60 | +- **Trace Name**: Derived from the root transaction or first transaction. |
| 61 | +- **Matching Spans**: The number of spans matching your query versus the total spans in the trace. |
| 62 | +- **Timeline**: A visual representation of significant spans within the trace. |
| 63 | +- **Duration**: The total time from the first to last span. |
| 64 | +- **Timestamp**: When the trace occurred (hover for exact time). |
| 65 | +- **Issues**: Links to any associated error issues. |
| 66 | + |
| 67 | +### Span Details |
| 68 | + |
| 69 | +Expand a trace to see the matching spans in the following table format: |
| 70 | + |
| 71 | +- **Span ID**: Links to the span in the Trace View. |
| 72 | +- **Description**: Includes project, `span.op`, and `span.description`. |
| 73 | +- **Timeline**: A visual representation of the span's position within the trace. |
| 74 | +- **Duration**: The time taken by the individual span. |
| 75 | +- **Timestamp**: When the span occurred. |
45 | 76 |
|
46 | | -Trace explorer allows you to search for up to 3 span conditions within a trace. Each set of span conditions matches against a particular span in a trace. |
47 | 77 |
|
48 | | -Adding one set of span conditions lets you search all spans. |
49 | 78 |
|
50 | | -The following example shows you all traces where: |
51 | | -- A user with the email `[email protected]` loaded a page on your frontend on a specific route |
52 | 79 |
|
53 | | - |
54 | 80 |
|
55 | | -Alternatively, adding multiple span conditions will only return traces that contain ALL span conditions. |
56 | 81 |
|
57 | | -The following example let's you find a trace where: |
58 | | -- A user with the email `[email protected]` loaded a page on your frontend on a specific route |
59 | | -- AND within that same trace, there was a slow database span |
60 | 82 |
|
61 | | - |
62 | 83 |
|
63 | | -### Filter by Environment, and Date Range |
64 | 84 |
|
65 | | -These common filters allow you to filter on your environments, as well as specify the date range you want to zoom in on. |
66 | 85 |
|
67 | | -Since traces are distributed in nature, there is no page-wide project filter, but you can filter on projects per set of span conditions by adding `project:your-project-here` in the search. |
68 | 86 |
|
69 | | -### Filter by Search Conditions |
70 | 87 |
|
71 | | -<Note> |
72 | 88 |
|
73 | | -When performing searches on spans, based on your search criteria |
74 | | -and sample rate, the events available may be limited because Traces uses |
75 | | -sampled data only. Learn more by reading about [our retention priorities](/product/performance/retention-priorities/). |
76 | 89 |
|
77 | | -</Note> |
78 | 90 |
|
79 | | -All events have built-in key fields or custom tags, this includes our span data. Use the search bar to enter these keys and assign them values. This will filter down your list of events. For a list of the built-in key fields, check out our [Searchable Properties for spans documentation](/concepts/search/searchable-properties/spans/). |
80 | 91 |
|
81 | | -### Syntax |
82 | 92 |
|
83 | | -The Query Builder syntax is identical to [Sentry's Search syntax](/concepts/search/). After you enter a key field from above or a custom tag, you can use any of the referenced syntax. For example, `count()` gives you the number of times an event occurs. |
84 | 93 |
|
85 | | -Use `OR` and `AND` to search conditions between filters. However `OR` cannot be used between aggregate and non-aggregate filters. For more details about these conditions, see [Using `OR` and `AND`](/concepts/search/#using-or-and-and). |
|
0 commit comments