Docs/logs refresh kyle (#15595)

KyleTryon · Copilot · sfanahata · web-flow · commit 431a9be8f43d · 2025-11-24T23:30:05.000-05:00
This pull request updates Sentry's documentation for logs and drains to
provide clearer explanations, improved onboarding, and better guidance
for users integrating platform-native logs and traces. The changes
introduce new overview sections, clarify the benefits of trace-connected
logs, and enhance instructions for setting up log drains across
supported platforms.

**Documentation improvements and onboarding clarity:**

* Added a comprehensive overview of log and trace drains, including
supported platforms, data types, setup prerequisites, and links to
related documentation in `docs/product/drains/index.mdx`. This helps
users understand when and how to use drains for platform-level
telemetry.
* Updated the logs getting started guide to describe log drains, list
supported integrations, and clarify the use of OpenTelemetry endpoints
for log forwarding.

**Feature explanation and search enhancements:**

* Expanded the logs overview to explain "trace-connected" logs—each log
entry is linked to its trace, enabling seamless navigation from logs to
traces and errors. Added practical examples for log search queries and
clarified how to use custom attributes.
* Added a new section describing the trace-connected debugging workflow,
guiding users through searching logs, viewing traces, and identifying
root causes in a unified flow.

**Usability and search improvements:**

* Improved explanations for auto-refresh and query volume conditions in
the logs explorer, including links to filtering and search documentation
for better discoverability.

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: Shannon Anahata &lt;shannon.anahata@gmail.com&gt;
diff --git a/docs/product/drains/index.mdx b/docs/product/drains/index.mdx
@@ -4,12 +4,15 @@ sidebar_order: 75
 description: Learn how to set up trace and log drains and forwarders to send data to Sentry.
 ---
 
-To send data to Sentry, we recommend using the Sentry SDKs. However we also support forwarding data to Sentry from platforms where you can't use the Sentry SDKs. At the moment we only support forwarding logs and traces data, error events are not supported yet.
+## Overview
 
-## Endpoints
+Log and trace drains allow you to forward logs and traces from your deployment platform's native logging and tracing systems directly into Sentry without modifying your application code. Drains capture platform-level telemetry—like build logs, runtime logs, and static asset logs—from deployment platforms such as Vercel, Cloudflare, Heroku, and Supabase.
 
-- [OpenTelemetry (OTLP)](/concepts/otlp/)
+Drains are ideal when you want to capture platform-level observability from your hosting infrastructure or when you can't install Sentry SDKs directly in your application.
 
+<Alert level="info">
+Error events are not currently supported through drains. To capture errors, use [Sentry SDKs](/product/explore/logs/getting-started/) instead.
+</Alert>
 ## Forwarders
 
 - [Vector](/product/drains/integration/vector/)
@@ -18,8 +21,50 @@ To send data to Sentry, we recommend using the Sentry SDKs. However we also supp
 
 ## Drains
 
-- [Vercel](/product/drains/integration/vercel/)
-- [Cloudflare](/product/drains/integration/cloudflare/)
-- [Heroku](/product/drains/integration/heroku/)
-- [Supabase](/product/drains/integration/supabase/)
-- [Shopify Hydrogen](/product/drains/integration/shopify-hydrogen/)
+## Supported Platforms
+
+| Platform | Logs | Traces | Documentation |
+|----------|------|--------|---------------|
+| [Vercel](/product/drains/integration/vercel/) | ✅ | ✅ | Forward runtime, build, and static logs, plus distributed traces |
+| [Cloudflare](/product/drains/integration/cloudflare/) | ✅ | ✅ | Forward logs and traces from Cloudflare Workers |
+| [Heroku](/product/drains/integration/heroku/) | ✅ | ✅ | Forward logs and traces via Heroku Telemetry Drains |
+| [Supabase](/product/drains/integration/supabase/) | ✅ | ❌ | Forward logs from your Supabase stack |
+| [Shopify Hydrogen](/product/drains/integration/shopify-hydrogen/) | ❌ | ✅ | Forward traces from Hydrogen storefronts |
+
+## Supported Data Types
+
+Drains support forwarding **logs** from most supported platforms, with some platforms supporting **traces** as well:
+
+- **Logs**: Application logs, runtime logs, build logs, and system-generated logs from your platform
+- **Traces**: Distributed tracing data showing request flows through your application and connected services (supported on Vercel, Cloudflare, Heroku, and Shopify Hydrogen)
+
+## How Drains Work
+
+Drains work by configuring your deployment platform's native telemetry export system to forward data to Sentry's ingestion endpoints. Most platforms support forwarding data via:
+
+- [**OpenTelemetry Protocol (OTLP)**](https://opentelemetry.io/docs/): The standard protocol for forwarding logs and traces
+- **Platform-specific endpoints**: Custom endpoints provided by Sentry for specific platforms (like Vercel's custom drain endpoint). Follow the [platform-specific link](/product/drains/#supported-platforms) to learn more. 
+
+Once configured, your platform automatically forwards logs and traces (where supported) to Sentry, where you can view, search, and analyze them alongside data from your Sentry SDKs.
+
+## Prerequisites
+
+Before setting up a drain, ensure you have:
+
+1. **A Sentry project**: Create a project in Sentry if you don't have one already
+2. **Your project credentials**: You'll need your Sentry project's OTLP endpoint URL and public key, which can be found in your [Sentry Project Settings](https://sentry.io/settings/projects/) under **Client Keys (DSN)** > **OpenTelemetry (OTLP)**
+3. **Platform access**: Admin or configuration access to your platform's telemetry settings
+
+## Getting Started
+
+1. Choose your platform from the [Supported Platforms](#supported-platforms) table above and follow the platform-specific setup guide
+2. Configure the drain in your platform's dashboard or via CLI using your Sentry project credentials (found in your [Sentry Project Settings](https://sentry.io/settings/projects/) under **Client Keys (DSN)** > **OpenTelemetry (OTLP)**)
+3. Verify data is flowing by checking your Sentry project's [Logs](/product/explore/logs/) or [Performance](/product/performance/) views
+
+Most drains use Sentry's [OpenTelemetry Protocol (OTLP)](/concepts/otlp/) endpoints. Some platforms, like Vercel, also support custom endpoints. You can find your OTLP endpoint URLs and authentication headers in your project settings.
+
+## Related Documentation
+
+- [Logs Overview](/product/explore/logs/): Learn how to view, search, and analyze logs in Sentry
+- [Performance Monitoring](/product/performance/): Understand distributed tracing and performance data
+- [OpenTelemetry Protocol](/concepts/otlp/): Learn more about OTLP and how to configure OpenTelemetry SDKs
diff --git a/docs/product/explore/logs/getting-started/index.mdx b/docs/product/explore/logs/getting-started/index.mdx
@@ -322,8 +322,17 @@ If you don't see your platform listed above, please reach out to us on [GitHub](
 
 ## Log Drains
 
-Sentry supports connecting to log drains or sinks to ingest logs. We are actively working on adding support for more platforms, which we are tracking in [this GitHub issue](https://github.com/getsentry/sentry/issues/91726).
+Log drains allow you to forward logs from platforms like Vercel, Cloudflare, Heroku, and Supabase directly to Sentry without modifying your application code. Learn more about [log and trace drains](/product/drains/).
 
-### Endpoints
+### Supported Platform Integrations
 
-You can send logs to Sentry via [Sentry's OpenTelemetry (OTLP) Logs endpoint](/concepts/otlp/#opentelemetry-logs). This can be used with any OpenTelemetry SDK, or with the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) to send logs to Sentry.
+- **[Vercel](/product/drains/integration/vercel/)**: Forward runtime, build, and static logs from Vercel deployments
+- **[Cloudflare](/product/drains/integration/cloudflare/)**: Forward logs from Cloudflare Workers
+- **[Heroku](/product/drains/integration/heroku/)**: Forward logs from Heroku apps using telemetry drains
+- **[Supabase](/product/drains/integration/supabase/)**: Forward logs from your Supabase stack
+
+We are actively working on adding support for more platforms, which we are tracking in [this GitHub issue](https://github.com/getsentry/sentry/issues/91726).
+
+### OpenTelemetry (OTLP) Endpoint
+
+You can also send logs to Sentry via [Sentry's OpenTelemetry (OTLP) Logs endpoint](/concepts/otlp/#opentelemetry-logs). This can be used with any OpenTelemetry SDK, or with the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) to send logs to Sentry. This is useful if you're already using OpenTelemetry instrumentation or want to route logs through an OTLP collector.
diff --git a/docs/product/explore/logs/index.mdx b/docs/product/explore/logs/index.mdx
@@ -10,35 +10,60 @@ og_image: /og-images/product-explore-logs.png
 
 ## Overview
 
-With Structured Logs, users can send text-based log information from their applications, whether frontend or backend, to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual parameters.
+With Structured Logs, you can send text-based log information from your applications, whether frontend or backend, to Sentry.
 
 <Arcade src="https://demo.arcade.software/PalOCHofpcO3DqvA4Rzr?embed" />
 
-Not everything that you want to track in your application generates an error event. You might want to arbitrarily track information happening in your application for many reasons, such as:
+Sentry's structured logs are searchable, **trace-connected**, and viewable alongside your errors. 
 
-- Debugging information like navigation actions, page interactions, or query results
-- User specific events
-- Configuration items that users or an application are receiving
+**What does trace-connected mean?** Every log entry is automatically linked to the active trace when it was recorded. This means you can click directly from any log entry to see the full trace waterfall, including all related spans, errors, and other logs from the same request. This connection makes it easy to understand the complete context of what happened—not just what was logged, but the entire execution path that led to that log entry.
+
+When investigating an issue, you can search your logs by message content or attributes, then click into any log entry to see the exact trace, spans, and errors that occurred at that moment. Learn more about [Trace View](/concepts/key-terms/tracing/trace-view/) to understand how to navigate from logs to traces.
+
+Not everything in your application generates an error or requires full tracing. Logs are perfect for tracking:
+
+- **Debugging information**: Cache misses, database connections, query results, and performance metrics
+- **User behavior**: Login events, checkout flows, feature usage, and preference changes
+- **Application state**: Configuration loading, service initialization, and connection status
+- **Business events**: Order placements, payment processing, and notification delivery
+
+Learn how to [send structured logs](/product/explore/logs/getting-started/) with custom attributes that you can search and filter in Sentry.
 
 ## Set up Logs
 
 To get started with Logs, navigate to the [Getting Started](/product/explore/logs/getting-started/) page and select your SDK from the list.
 
+If you're using a platform where you can't install the Sentry SDK directly, or if you want to forward logs from platform-native logging systems, you can use [log drains](/product/drains/) to send logs to Sentry.
+
 ## Viewing and Searching Logs
 
 **Raw Text Search**  
-Raw text search is case sensitive and allows you to search for specific strings within the *message* attribute of the Log. **Raw text search over the entire log's JSON is not supported.**
+Raw text search is case sensitive and allows you to search for specific strings within the *message* attribute of the Log. **Raw text search over the entire log's JSON is not supported.** Learn more about [search syntax](/concepts/search/).
 
 ![Raw Text Logs Search](./img/LogSearchRawText.png)
 
 **Default Properties Search**  
-You can also search using the default properties (like `severity`) or additional custom properties that you've added to your log entries.
+You can also search using the default properties (like `severity`) or [additional custom properties](/concepts/search/searchable-properties/) that you've added to your log entries.
 
 ![Property Logs Search](./img/LogSearchTags.png)
 
+**Search Examples**  
+Here are some practical examples of log searches you can use:
+
+- `severity:error` - Find all error-level logs
+- `severity:error payment.failed` - Find error logs containing "payment.failed" in the message
+- `user.id:12345` - Find all logs for a specific user
+- `trace_id:abc123def456` - Find all logs associated with a specific trace
+- `severity:error environment:production` - Find production errors
+- `order.id:order_123` - Find logs related to a specific order
+- `severity:warn OR severity:error` - Find warnings or errors
+- `database:"users" query.duration_ms:>1000` - Find slow database queries on the users database
+
+Learn more about [search syntax](/concepts/search/) for advanced querying.
+
 
 **Expand Logs**  
-Log entries can be expanded to view all properties of logs entry. Individual properties can be added as columns to the results view, allowing you to quickly view properties that matter specifically to you alongside your search results.
+Log entries can be expanded to view all properties of a log entry. Individual properties can be added as columns to the results view, allowing you to quickly view properties that matter specifically to you alongside your search results.
 
 ![Expanded Logs View](./img/LogsExpanded.png)
 
@@ -49,15 +74,15 @@ You can also enable auto refreshing of the logs view to see your latest logs as
 
 Conditions in which auto-refresh is disabled:
 
-- Auto-refresh is only supported when sorting by time in descending order.
-- Auto-refresh is only supported when using a relative time period, like "Last 15 minutes" or "Last 7 days", not absolute dates like "2025-07-23".
-- Auto-refresh is disabled due to high data volume (100 logs per second). Try adding a filter to reduce the number of logs.
+- Auto-refresh is only supported when sorting by time in descending order.
+- Auto-refresh is only supported when using a relative time period, like "Last 15 minutes" or "Last 7 days", not absolute dates like "2025-07-23".
+- Auto-refresh is disabled due to high data volume (100 logs per second). Try adding a [filter](/concepts/data-management/filtering/#logs-filtering) to reduce the number of logs.
 - Auto-refresh will be disabled due to reaching a max auto-refresh time of 10 minutes.
 - Auto-refresh will be disabled if there is an error fetching logs.
-- Auto-refresh is not available in the aggregates view.
+- Auto-refresh is not available in the aggregates view.
 
 ### Query Volumes
-When the number of logs returned by a query is too high, there are a couple of changes to explorer functionality.
+When the number of logs returned by a query is too high, there are a couple of changes to the logs explorer functionality. To reduce query volumes, consider [filtering logs](/concepts/data-management/filtering/#logs-filtering) or refining your [search query](/concepts/search/) with more specific criteria.
  - Auto-refresh will be disabled.
  - Data shown in the chart will be extrapolated from a sampled amount of the complete dataset.  
  
@@ -67,10 +92,31 @@ When the number of logs returned by a query is too high, there are a couple of c
  
  ![Continue scanning message =1000x](./img/ContinueScanning.png)
 
+## Trace-Connected Debugging Flow
+
+Sentry's trace-connected logs enable a seamless debugging workflow that connects logs, traces, and errors:
+
+1. **Search your logs**: Start by searching for logs related to the issue you're investigating. Use message content, attributes, or filters to narrow down relevant log entries.
+
+2. **Click into a log**: When you find a log entry that looks suspicious or relevant, click on it to open the log details.
+
+3. **Navigate to the trace**: From the log details, click the trace link to open the full [Trace View](/concepts/key-terms/tracing/trace-view/). This shows you the complete execution path, including all spans, operations, and timing information.
+
+4. **Examine related data**: In the trace view, you can see:
+   - **Related errors**: Any errors that occurred during the same trace
+   - **Other logs**: Additional log entries from the same request
+   - **Performance data**: Slow spans, database queries, and API calls
+   - **User context**: User information and session data
+
+5. **Find the root cause**: With full context in hand—logs, traces, spans, and errors all connected—you can quickly identify and resolve the root cause.
+
+Instead of jumping between different tools and trying to correlate timestamps, trace-connected logs give you a **single flow**: Log search → log entry → trace → root cause.
+
+## Log-based Alerts and Dashboard widgets
 
-## Log based Alerts and Dashboard widgets
+You can create [Alert rules](/product/alerts/create-alerts/) and [dashboard widgets](/product/dashboards/widget-builder/) based on your log queries.
 
-You can create Alert rules and dashboard widgets based on your log queries.
+Learn more about [alert types](/product/alerts/alert-types/) and [custom dashboards](/product/dashboards/custom-dashboards/).
 
 ![Log Queries](./img/LogQueries.png)
 
