getsentry · sfanahata · Jul 7, 2026 · Jul 7, 2026
diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx
@@ -35,6 +35,12 @@ Traces are defined as the collection of all transactions that share a `trace_id`
 
 #### Transactions
 
+<Alert level="info">
+
+Transactions are a legacy data model concept. Sentry's newer span-based model represents all operations as spans; the root span of a trace replaces what was previously called a transaction. When working with Sentry's current tools, use [Trace Explorer](/product/trace-explorer/) and the [Spans](/product/dashboards/widget-builder/#spans) dataset.
+
+</Alert>
+
 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()`, or `Sentry.setExtra()`.)
@@ -211,7 +217,13 @@ Collecting transactions from multiple machines may result in **clock skew**, whe
 
 #### How Data is Sent
 
-Individual spans aren't sent to Sentry; the entire transaction is sent as one unit. No span data is recorded by Sentry's servers until the transaction is closed and dispatched. Transactions are still valid and sent even if they only contain their root span.
+<Alert level="info">
+
+In Sentry's current span-based SDKs, individual spans are sent directly to Sentry as they complete, without waiting for a parent transaction to close. The description below applies to the legacy transaction-based model.
+
+</Alert>
+
+In the legacy model, individual spans aren't sent to Sentry; the entire transaction is sent as one unit. No span data is recorded by Sentry's servers until the transaction is closed and dispatched. Transactions are still valid and sent even if they only contain their root span.
 
 ## Data Sampling
 

diff --git a/docs/concepts/key-terms/tracing/index.mdx b/docs/concepts/key-terms/tracing/index.mdx
@@ -33,6 +33,12 @@ Span attributes and metrics are key pieces of information that are captured for
 
 ### What's a Transaction?
 
+<Alert level="info">
+
+Transactions are a legacy concept. In Sentry's current span-based model, the root span of a trace serves the same role that transactions previously filled. New SDKs and features use spans exclusively. See [Trace Explorer](/product/trace-explorer/) for the recommended way to query performance data.
+
+</Alert>
+
 In Sentry, a "transaction" is a specific unit that represents any event that your application sends to Sentry, like loading a web page or processing an API call. Each transaction is made up of one or more spans. Transactions have a unique transaction ID and include the associated child spans that capture the operation’s entire process from start to finish.
 
 ## How to Use Tracing in Sentry

diff --git a/docs/product/dashboards/widget-builder/index.mdx b/docs/product/dashboards/widget-builder/index.mdx
@@ -15,7 +15,7 @@ Some of these options are standard and displayed for all widgets, but others are
 
 ## Dataset
 
-In the dataset selection step, choose which type of data you would like to use in your widget. Available datasets include: [errors](#errors), [spans](#spans), [transactions](#transactions), [logs](#logs), [issues](#issues), and [releases](#releases).
+In the dataset selection step, choose which type of data you would like to use in your widget. Available datasets include: [errors](#errors), [spans](#spans), [logs](#logs), [issues](#issues), [releases](#releases), and [application metrics](#application-metrics).
 
 ### Errors
 Choosing "Errors" allows you to query and aggregate error events in the same way you would for a [Discover Query](/product/discover-queries/). This data is comprised of errors that occur in your application, which Sentry will use to group into issues, for example:
@@ -32,13 +32,6 @@ Choosing "Spans" allows you to query and aggregate individual operations within
 
 You can create span-based widgets directly from [Trace Explorer](/product/trace-explorer/) queries using the "Save As" button.
 
-### Transactions
-
-Choosing "Transactions" allows you to query and aggregate transaction events in the same way you would for a [Discover Query](/product/discover-queries/). This data is comprised of events that track the performance of operations in your application. Some widget examples include:
-
-- Tracking performance of an endpoint
-- Throughput by country
-
 ### Logs
 
 Choosing "Logs" allows you to query and aggregate structured log data from your applications. Logs are trace-connected and searchable by message content or custom properties. This data is useful for tracking application behavior that doesn't necessarily generate errors. Some widget examples include:
@@ -49,6 +42,16 @@ Choosing "Logs" allows you to query and aggregate structured log data from your
 
 You can create log-based widgets from [Logs Explorer](/product/logs/) queries.
 
+### Application Metrics
+
+Choosing "Application Metrics" allows you to query and visualize counters, gauges, and distributions you've instrumented from your code. These metrics are trace-connected, meaning you can click directly into related traces, logs, and errors when something looks off. Some widget examples include:
+
+- Count of `checkout.failed` events over time
+- `queue.depth` gauge trending across deployments
+- Distribution of response times for a custom operation
+
+Learn more about setting up metrics in the [Application Metrics documentation](/product/metrics/).
+
 ### Issues
 
 Choosing "Issues (States, Assignment, Time, etc.)" allows you to query issue properties, such as `is:unresolved` or event properties such as `error.handled:0`, and to sort by issue fields such as `First Seen`. When searching on event properties, the search will return any issue that has one or more events matching the supplied event filters.
@@ -65,6 +68,14 @@ Choosing "Releases (sessions, crash rates)" allows you to query properties speci
 - Crash rates for your latest release
 - Session count across releases
 
+### Transactions (Deprecated)
+
+<Alert level="warning">
+Transactions are deprecated in favor of Spans. Use the [Spans](#spans) dataset for new widgets, or explore performance data in [Trace Explorer](/product/trace-explorer/).
+</Alert>
+
+Choosing "Transactions" allows you to query and aggregate transaction events in the same way you would for a [Discover Query](/product/discover-queries/). This data is comprised of events that track the performance of operations in your application.
+
 ## Visualization Type
 
 In this step, you can choose from the following visualization types:

diff --git a/docs/product/dashboards/widget-library/index.mdx b/docs/product/dashboards/widget-library/index.mdx
@@ -13,19 +13,19 @@ You can also create your own custom widgets using the [Widget Builder](/product/
 
 The library includes the following widgets:
 
-- **Duration Distribution**: Compare transaction durations across different percentiles.
-- **High Throughput Transactions**: Top 5 transactions with the largest volume.
+- **Duration Distribution**: Compare span durations across different percentiles.
+- **High Throughput Transactions**: Top 5 transactions with the largest volume. _(Uses the legacy Transactions dataset; consider building a [span-based widget](/product/dashboards/widget-builder/#spans) instead.)_
 - **Crash Rates for Recent Releases**: Percentage of crashed sessions for latest releases.
 - **Session Health**: Number of abnormal, crashed, errored, and healthy sessions.
 - **LCP by Country**: Table showing page load times by country.
-- **Slow vs. Fast Transactions**: Count breakdown of transaction durations over and under 300ms.
+- **Slow vs. Fast Transactions**: Count breakdown of transaction durations over and under 300ms. _(Uses the legacy Transactions dataset; consider building a [span-based widget](/product/dashboards/widget-builder/#spans) instead.)_
 - **Performance Score**: Tracks the overall performance rating of the pages in your selected project.
 - **SSR File Tree**: Visualizes the file tree of the server-rendered components in your Next.js project.
 - **Rage and Dead Clicks**: Visualizes the rage and dead clicks in your frontend project.
 - **Issues For Review**: Most recently seen unresolved issues for review.
 - **Top Unhandled Error Types**: Most frequently encountered unhandled errors.
 - **Users Affected by Errors**: Footprint of unique users affected by errors.
-- **Error Count By Transaction**: Compare error volume across your top transactions.
+- **Error Count By Transaction**: Compare error volume across your top transactions. _(Uses the legacy Transactions dataset.)_
 
 
 

diff --git a/docs/product/discover-queries/index.mdx b/docs/product/discover-queries/index.mdx
@@ -8,6 +8,12 @@ description: >-
 og_image: /og-images/product-explore-discover-queries.png
 ---
 
+<Alert level="info">
+
+For performance data, [Trace Explorer](/product/trace-explorer/) is the recommended tool. It queries spans directly and supports the full set of span attributes. Discover's Transactions dataset is deprecated; existing saved queries will continue to work but new performance queries should use Trace Explorer.
+
+</Alert>
+
 The Discover homepage displays the query builder where you can immediately begin creating a new query. By default, the page shows the pre-built "All Events" query, but you can customize the homepage and [set the custom version as your default](#set-as-default). To navigate back to the query management page, where you can find [pre-built](#pre-built-queries) and [saved](#saved-queries) queries, click the "Saved Queries" button.
 
 The query management page offers views of all your saved and pre-built queries so you can quickly see areas that need immediate attention. For example, if a query on errors shows a spike has occurred in the past 24 hours, you might want to investigate that first. Each query is saved as a card that displays a summarized view of the following data:

diff --git a/docs/product/discover-queries/query-builder.mdx b/docs/product/discover-queries/query-builder.mdx
@@ -30,6 +30,12 @@ There are five main building blocks that impact the results of your saved query,
 
 The dataset selector allows you to query for either errors or transactions. You can only query one dataset at a time. The errors dataset returns events related to errors, while the transactions dataset returns transaction events that help you see application performance.
 
+<Alert level="warning">
+
+The Transactions dataset in Discover is deprecated. For performance data, use [Trace Explorer](/product/trace-explorer/) which queries spans directly. Existing saved queries using the Transactions dataset will continue to work, but new queries should use [Trace Explorer](/product/trace-explorer/) instead.
+
+</Alert>
+
 ## Filter by Project, Environment, and Date Range
 
 These common filters allow you to filter on your projects and environments, as well as specify the date range you want to zoom in on.
@@ -118,7 +124,14 @@ You can also add the following functions as columns to stack events, depending o
 - `eps()`
 - `epm()`
 
-#### Transactions
+#### Transactions (Deprecated)
+
+<Alert level="warning">
+
+The Transactions dataset is deprecated. Use [Trace Explorer](/product/trace-explorer/) for new performance queries based on spans.
+
+</Alert>
+
 - `any(...)`
 - `apdex(...)`
 - `avg(...)`