JavaScript tracing docs refactor

docs/concepts/key-terms/tracing/distributed-tracing.mdx

@@ -1,6 +1,6 @@
 ---
 title: Distributed Tracing
-sidebar_order: 10
+sidebar_order: 20
 description: With distributed tracing, you can track software performance and measure throughput & latency, while seeing the impact of errors across multiple systems.
 ---
 

docs/concepts/key-terms/tracing/index.mdx

@@ -4,11 +4,73 @@ sidebar_order: 70
 description: "Learn more about the tracing features Sentry offers to help you track your software performance across multiple systems."
 ---
 
-[Distributed tracing](/product/sentry-basics/tracing/distributed-tracing/) provides a connected view of related errors and transactions by capturing interactions among your software systems. With tracing, Sentry tracks your software performance and displays the impact of errors across multiple systems. Tracing issues back through services connects your front-end to your back-end.
+## What's Tracing?
 
-The [Trace View](/product/sentry-basics/tracing/trace-view/) allows you to drill down into the details of a single trace and traverse every transaction in that trace. This accelerates your ability to debug slow services, identify related errors, and root out other bottlenecks.
+Tracing is the process of capturing the timing and flow of requests and operations as they happen in your application. It's a powerful debugging tool, helping you identify which link in a sequence of events may be causing a problem, such as slow performance.
 
-The [Trace Explorer](/product/explore/traces/) allows you to explore traces by querying [span properties](/concepts/search/searchable-properties/spans/). This helps you find relevant distributed traces that will give you more information to debug and optimize your code.
+![An illustrated image of the anatomy of a trace, showing 8 span blocks cascading in a waterfall pattern.](./img/The-anatomy-of-a-trace.png)
+
+### What's Distributed Tracing?
+
+Distributed tracing provides a unified view of how a single request moves from the frontend to the backend and beyond. This is particularly useful in modern applications, which are often composed of multiple separate services working together. To get a distributed view of your application, instrument Sentry in both your frontend and your backend.
+
+With [distributed tracing](/concepts/key-terms/tracing/distributed-tracing/), you can identify performance bottlenecks that are affecting your application across different services and platforms. You can then use Sentry tools such as the [Trace Explorer](/product/explore/traces/) or [Trace View](/concepts/key-terms/tracing/trace-view/) page to dig deeper and find the root cause of the problem. Distributed tracing is particularly helpful for identifying problems that exist in actions taking place between multiple services that you can't debug using console logs, such as race conditions, [N+1 queries](/product/issues/issue-details/performance-issues/n-one-queries/), and [caching issues](/product/insights/caches/).
+
+### What's a Trace?
+
+A trace is a record of a series of connected events and operations coming from your application. Each trace has a string of globally unique characters called a trace ID that's passed between frontend and backend services. The trace ID connects all the actions that take place, starting from the moment a user performs an action on the frontend, all the way through to the actions this triggers across your application and services. Each trace is composed of multiple spans.
+
+### What's a Span?
+
+A span is a named, timed operation that represents a part of the application workflow. The data captured for each span provides granular insights into specific tasks, like API requests or database queries. Multiple spans are pieced together to create a trace, providing a comprehensive overview of how your application works. This makes it easier to troubleshoot and analyze performance issues.
+
+### What are Span Attributes and Metrics?
+
+Span attributes and metrics are key pieces of information that are captured for each span. Attributes are key-value pairs that provide additional context about the span, such as the name of the operation or the user ID. Metrics are numerical values that measure the performance of the span, such as the duration of the operation or the number of database queries.
+
+### What's a Transaction?
+
+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
+
+If you instrument Sentry for a single part of your app (just the frontend for example), looking at a trace will provide useful context for debugging issues within that app or service. But to get the most out of tracing in Sentry, you'll need to instrument the frontend, the backend, and any services in-between with Sentry's SDK. Once this is done, there are several places where you can view and interact with tracing data:
+
+### Traces to Trace View
+
+You can view all the traces in your organization by going to the [Traces](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page in Sentry. You'll see a chart and a list of traces and be able to see at-a-glance how long each trace took to complete and the number of spans it contains.
+
+![A view of the Sentry Traces page showing traces and spans](./img/Traces-page.png)
+
+If you want more information, click on any trace ID. This will take you to the [Trace View](/concepts/key-terms/tracing/trace-view/) page, which provides a more detailed view of the trace and its spans. Here, you'll see a waterfall view of the spans in the trace, which will show you how much time each service and operation took to complete, and may give you an indicator of where a problem may be coming from. 
+
+![A detailed view of the Senty Traces page showing an expaned trace and spans](./img/Trace-view-page.png)
+
+Alternatively, you can use the search bar to look for spans by name, project, or other criteria. You can also use the tags section to filter spans by specific tags. Learn more about the Sentry [Trace Explorer](/product/explore/traces/).
+
+![An illustrated image of the anatomy of a trace, showing 8 span blocks cascading in a waterfall pattern.](./img/Traces-details-page.png)
+
+### Performance to Trace View
+
+Depending on the size and volume of your app, you may have a lot of traces to sort through. The [Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/) page in Sentry is a good place to get a high-level, aggregated view of your application's performance and focus in on the traces you care about. You'll see a list of transactions for specific pages, endpoints and parts of your application. Clicking on the transaction ID will take you to the Trace View page for that transaction. Learn more about using Sentry's [Insights](/product/insights/).
+
+![An overview of the Performance page in Sentry.](./img/Performance-page.png)
+
+## How Tracing Can Help You Debug
+
+Sentry’s tracing lets you follow each request across various services, databases, and functions. This makes it easier to find exactly where an error occured or a performance bottleneck started. Below, you'll find some real-world scenarios where tracing saved the day.
+
+### Debug Slowdowns Across Your Integrations
+
+When debugging integrations or a microservice architecture, you'll likely run into issues where the root cause is tricky to discover, especially when it's a performance issue. At Sentry, we make sure to add spans whenever we’re working with external services, like Slack. Because of this, when our users started experiencing a 4-second delay in receiving Sentry alerts via Slack, we were able to go to the [Trace View](/concepts/key-terms/tracing/trace-view/) and quickly narrow down which task was causing the slowdown and deploy a fix quickly. Read more about the details of [debugging Sentry’s Slack Integration](https://blog.sentry.io/debugging-a-slack-integration-with-sentrys-trace-view/).
+
+### Improve Core Web Vitals
+
+While everyone is sharing Lighthouse scores, we all know that the true determination of healthy web vitals is when your actual users are using your application in their authentic environments. Sentry offers real insights and analysis of your application in the real world, and while tracing can be leveraged to reactively solve issues, you can also use it to proactively discover opportunities to improve your application performance. In fact, this blog post describes [how you can improve performance before your web page even loads](https://blog.sentry.io/how-to-make-your-web-page-faster-before-it-even-loads/).
+
+### Debug New Code Bases Faster
+
+Tracing can even give you the power to debug unfamiliar codebases. Although this benefit is not often discussed, a lot of time can be saved when debugging applications instrumented with Tracing, even if the codebase is completely new to you. Being able to trace actual user journeys throughout your application and see what happens across your entire stack contextualizes issues without even needing to recreate the issue locally. Read more about other ways [tracing helps developers debug](https://blog.sentry.io/everyone-needs-to-know-how-to-trace/) various issues here.
 
 ## Learn More
 

docs/concepts/key-terms/tracing/span-metrics.mdx

@@ -0,0 +1,293 @@
+---
+title: Span Metrics
+description: "Learn how attaching attributes to spans provides enhanced application performance monitoring and improved debugging."
+sidebar_order: 10
+---
+
+Span metrics enable you to attach user defined attributes to spans, which might include application metrics or important debugging context within your application's traces. This approach provides context-rich performance monitoring by connecting attributes directly to the operations that generate them.
+
+These attributes allow you to enrich trace spans with attributes that represent various types of measurement data:
+
+- Performance attributes (memory usage, processing time, latency)
+- Business metrics (transaction value, user engagement rates)
+- Technical indicators (queue depth, cache hit ratios)
+- Debugging context (input parameters, process states)
+
+By attaching attributes directly to spans, you create a unified view of both the execution path and its associated performance data.
+
+```javascript
+// Adding performance metrics to a database span
+// Simple database query with dynamic attributes
+Sentry.startSpan(
+  {
+    name: 'Database Query',
+    op: 'db.query'
+  },
+  () => {
+    // Get active span to set attributes as data becomes available
+    const span = Sentry.getActiveSpan();
+
+    // Execute query and add results to span
+    const result = executeQuery('SELECT * FROM users WHERE active = true');
+
+    // Set attributes with the results data
+    if (span) {
+      span.setAttribute('db.rows_returned', result.length);
+      span.setAttribute('db.execution_time_ms', result.executionTime);
+    }
+
+    return result;
+  }
+);
+```
+
+## Benefits of Configuring Span Attributes
+
+### Contextual Observability
+
+Span attributes provide contextual data that connects execution flow with specific metrics that developers care about, or performance measurements. When investigating an issue, you can view both what occurred (the trace) and the performance characteristics in a single view.
+
+### Unified Telemetry
+
+By integrating these attributes into tracing, you can maintain a single telemetry pipeline rather than managing separate systems for traces and metrics, resulting in simplified instrumentation and more efficient monitoring.
+
+```javascript
+// Adding business context to a payment processing span
+Sentry.startSpan(
+  {
+    name: 'Process Payment',
+    op: 'payment.process',
+    attributes: {
+      'payment.amount': 99.99,
+      'payment.currency': 'USD',
+      'payment.method': 'credit_card',
+      'customer.type': 'returning'
+    }
+  },
+  async () => {
+    // Payment processing implementation
+  }
+);
+```
+
+### Accelerated Troubleshooting
+
+When performance issues arise, these attributes provide the necessary context to quickly identify bottlenecks. For example, when investigating slow checkout processes, you can immediately see which specific component (payment gateway, database query, third-party API) is causing the delay.
+
+### Technical-Business Correlation
+
+Span attributes enable correlation between technical performance data and business outcomes by connecting metrics like response time or error rates directly to business metrics such as conversion rates or revenue.
+
+## Implementation Approaches
+
+There are two primary methods for implementing attributes on spans:
+
+### 1. Enhancing Existing Spans
+
+Augment automatically-created or manually-defined spans with additional attributes:
+
+```javascript
+// Adding metrics to an existing file upload span
+const span = Sentry.getActiveSpan();
+if (span) {
+  // User context
+  span.setAttribute('user.subscription_tier', 'premium');
+
+  // Multiple metrics in a single operation
+  span.setAttributes({
+    'memory.heap_used': 1024000,
+    'processing.total_steps': 5
+  });
+}
+```
+
+### 2. Creating Dedicated Metric Spans
+
+Create spans specifically for grouping related attributes or metrics, particularly useful for complex operations:
+
+```javascript
+// Creating a span for monitoring external API usage
+Sentry.startSpan(
+  {
+    name: 'Third-Party API Usage',
+    op: 'external.api',
+    attributes: {
+      // Performance metrics
+      'api.response_time_ms': 245,
+
+      // Context data
+      'feature.using_api': 'image_recognition',
+      'user.plan': 'enterprise'
+    }
+  },
+  async () => {
+    // API call implementation
+  }
+);
+```
+
+## Implementation Use Cases
+
+The following examples demonstrate how attributes can be applied to common application scenarios:
+
+### User Interface Performance
+
+Monitor client-side performance metrics related to user experience:
+
+```javascript
+// UI performance monitoring
+Sentry.startSpan(
+  {
+    name: 'Page Interaction',
+    op: 'ui.interaction',
+    attributes: {
+      'ui.first_input_delay_ms': 24,
+      'ui.time_to_interactive_ms': 320,
+      'ui.frames_dropped': 0,
+      'user.device_type': 'mobile',
+      'feature.being_used': 'image_carousel'
+    }
+  },
+  async () => {
+    // UI interaction handling
+  }
+);
+```
+
+### Database Operation Monitoring
+
+Track database performance characteristics and their impact on application behavior:
+
+```javascript
+// Database query monitoring
+Sentry.startSpan(
+  {
+    name: 'Product Search Query',
+    op: 'db.query',
+    attributes: {
+      'db.query_type': 'SELECT',
+      'db.table': 'products',
+      'db.execution_time_ms': 145,
+      'db.rows_returned': 87,
+      'db.index_used': 'product_category_idx',
+      'business.search_term': 'winter jacket',
+      'business.search_filters_applied': 3
+    }
+  },
+  async () => {
+    // Database query execution
+  }
+);
+```
+
+### File Processing Operations
+
+Monitor file handling operations across your application stack:
+
+```javascript
+// File processing monitoring
+Sentry.startSpan(
+  {
+    name: 'Process Uploaded Image',
+    op: 'file.process',
+    attributes: {
+      // Technical metrics
+      'file.size_bytes': 2500000,
+      'file.type': 'image/jpeg',
+
+      // Processing metrics
+      'processing.steps_completed': ['virus_scan', 'resize', 'compress'],
+      'processing.total_time_ms': 850,
+
+      // Context data
+      'feature.using_upload': 'user_avatar',
+      'subscription.allows_hd': true
+    }
+  },
+  async () => {
+    // Image processing implementation
+  }
+);
+```
+
+### External Service Integration
+
+Monitor performance and reliability of third-party service interactions:
+
+```javascript
+// Payment gateway monitoring
+Sentry.startSpan(
+  {
+    name: 'Payment Gateway',
+    op: 'payment.gateway',
+    attributes: {
+      // Performance metrics
+      'gateway.response_time_ms': 980,
+      'gateway.retry_count': 0,
+
+      // Transaction data
+      'order.total_amount': 159.99,
+      'order.items_count': 3,
+
+      // Service metrics
+      'gateway.fee_amount': 4.50,
+      'gateway.fee_percent': 0.029
+    }
+  },
+  async () => {
+    // Payment gateway integration
+  }
+);
+```
+
+## Implementation Guidelines
+
+### Best Practices
+
+#### Metric Selection and Design
+
+Select metrics that provide actionable insights for debugging or performance monitoring. Consider which data points would help diagnose issues or make informed decisions about your application.
+
+#### Naming Conventions
+
+Maintain consistent naming patterns following the format `category.metric_name` to ensure metrics are discoverable and understandable across your organization.
+
+#### Data Type Selection
+
+Choose appropriate data types for your metrics:
+- Numeric values for measurements (`response_time_ms`: 250)
+- Boolean values for state indicators (`cache.hit`: true)
+- String values for categorical data (`user.subscription`: 'premium')
+- Arrays for multi-value data (`processing.steps_completed`: ['download', 'process', 'upload'])
+
+#### Performance Considerations
+
+Be mindful of the performance impact of collecting metrics, especially for high-volume operations:
+- Consider implementing sampling for high-frequency operations
+- Prioritize metrics with the highest analytical value
+- Avoid redundant or closely correlated metrics
+
+## Migrating from Standalone Metrics
+
+If you're currently using Sentry's standalone Metrics product, migrating to span attributes offers several advantages:
+
+- **Enhanced context**: Attributes are connected directly to the operations that generate them
+- **Implementation efficiency**: A single consistent API for both traces and metrics
+- **Improved correlation**: Direct association between attributes, traces, and errors
+
+Migration process:
+1. Identify your current metric instrumentation points
+2. Locate corresponding spans in your application
+3. Transfer your metrics to span attributes
+4. Update any dashboards or alerts to reference the new metric sources
+
+## Additional Resources
+
+For more detailed implementation examples, refer to these guides:
+
+- [E-Commerce use case](/platforms/javascript/tracing/span-metrics/examples/#e-commerce-transaction-flow)
+- [LLM integration monitoring](/platforms/javascript/tracing/span-metrics/examples/#llm-integration-monitoring)
+- [File upload and processing](/platforms/javascript/tracing/span-metrics/examples/#file-upload-and-processing-pipeline)
+- [Job scheduling and processing](/platforms/javascript/tracing/span-metrics/examples/#job-scheduling-and-processing-pipeline)
+
+These examples demonstrate how to implement comprehensive attribute tracking across distributed systems, providing end-to-end visibility into application performance and behavior.