Updating copy across tracing docs for clarify

Author: codyde

docs/platforms/javascript/common/tracing/index.mdx

@@ -4,11 +4,7 @@ description: "Learn how to enable tracing in your app."
 sidebar_order: 4000
 ---
 
-With [tracing](/product/insights/overview/), Sentry tracks your software performance, measuring metrics like throughput and latency, and displaying the impact of errors across multiple systems. Sentry captures distributed traces consisting of transactions and spans, which measure individual services and individual operations within those services. Learn more about our model in [Distributed Tracing](/product/sentry-basics/tracing/distributed-tracing/).
-
-<PlatformSection notSupported={["javascript.bun", "javascript.deno", "javascript.cloudflare", "javascript.cordova", "javascript.capacitor"]}>
-  You can additionally <PlatformLink to="/profiling">set up Profiling</PlatformLink> to get even more detailed tracing information like stack traces and flame graphs.
-</PlatformSection>
+With [tracing](/product/insights/overview/), Sentry automatically tracks your software performance across your application services, measuring metrics like throughput and latency, and displaying the impact of errors across multiple systems. 
 
 <PlatformCategorySection supported={["server", "serverless"]}>
   <Alert>
@@ -34,24 +30,33 @@ With [tracing](/product/insights/overview/), Sentry tracks your software perform
 ## Configure
 
 <PlatformSection supported={["javascript"]}>
-  First, enable tracing and configure the sampling rate for transactions. Set
+  Enable tracing by configuring the sampling rate for transactions. Set
   the sample rate for your transactions by either:
 </PlatformSection>
 
 <PlatformSection notSupported={["javascript"]}>
-  First, configure the sampling rate for transactions. Set the sample rate for
-  your transactions by either:
+  Enable tracing by setting the sample rate for your transactions.
 </PlatformSection>
 
-- Setting a uniform sample rate for all transactions using the <PlatformIdentifier name="traces-sample-rate" /> option in your SDK config to a number between `0` and `1`. (For example, to send 20% of transactions, set <PlatformIdentifier name="traces-sample-rate" /> to `0.2`.)
-- Controlling the sample rate based on the transaction itself and the context in which it's captured, by providing a function to the <PlatformIdentifier name="traces-sampler" /> config option.
+<PlatformContent includePath="performance/configure-sample-rate" />
 
-The two options are meant to be mutually exclusive. If you set both, <PlatformIdentifier name="traces-sampler" /> will take precedence.
+- You can set a uniform sample rate for all transactions using the <PlatformIdentifier name="traces-sample-rate" /> option in your SDK config to a number between `0` and `1`. (For example, to send 20% of transactions, set <PlatformIdentifier name="traces-sample-rate" /> to `0.2`.)
+- For more granular control over sampling, you can set the sample rate based on the transaction itself and the context in which it's captured, by providing a function to the <PlatformIdentifier name="traces-sampler" /> config option.
 
-<PlatformContent includePath="performance/configure-sample-rate" />
+The two options are mutually exclusive. If both are set, <PlatformIdentifier name="traces-sampler" /> will take precedence.
 
 Learn more about tracing <PlatformLink to="/configuration/options/#tracing-options">options</PlatformLink>, how to use the <PlatformLink to="/configuration/sampling/#setting-a-sampling-function">tracesSampler</PlatformLink> function, or how to <PlatformLink to="/configuration/sampling/#sampling-transaction-events">sample transactions</PlatformLink>.
 
+## Distributed Tracing
+
+Sentry captures distributed traces consisting of transactions and spans, which measure individual services and individual operations within those services. Learn more about our model in [Distributed Tracing](/product/sentry-basics/tracing/distributed-tracing/).
+
+
+ <PlatformSection notSupported={["javascript.bun", "javascript.deno", "javascript.cloudflare", "javascript.cordova", "javascript.capacitor"]}>
+ ## Enhancing Trace Data with Profiling 
+  You can additionally <PlatformLink to="/profiling">set up Profiling</PlatformLink> to get even more detailed tracing information like stack traces and flame graphs.
+</PlatformSection>
+
 ## Verify
 
 <PlatformSection supported={["javascript"]} notSupported={["javascript.cordova"]}>
@@ -74,7 +79,7 @@ If you leave your sample rate at `1.0`, a transaction will be sent every time a
 
 You can also manually start spans to instrument specific parts of your code. This is useful when you want to measure the performance of a specific operation or function.
 
-See <PlatformLink to="/tracing/instrumentation/custom-instrumentation">Custom Instrumentation</PlatformLink> to learn how to manually start spans.
+See <PlatformLink to="/tracing/span-metrics/">Sending Span Metrics</PlatformLink> to learn how to manually start spans.
 
 ## Next Steps
 

docs/platforms/javascript/common/tracing/span-metrics/examples.mdx

@@ -1,5 +1,5 @@
 ---
-title: Instrumentation Examples
+title: Example Instrumentation
 description: "Examples of using span metrics to debug performance issues and monitor application behavior across frontend and backend services."
 sidebar_order: 10
 ---
@@ -26,21 +26,55 @@ Sentry.startSpan(
     name: 'Client File Upload',
     op: 'file.upload.client',
     attributes: {
-      // Client-side file preparation
+      // Static details available at the start
       'file.size_bytes': 15728640,  // 15MB
       'file.type': 'image/jpeg',
       'file.name': 'user-profile.jpg',
-      
-      // Client processing metrics
-      'client.compression_applied': true,
-      
-      // Upload progress tracking
-      'upload.retry_count': 0,
-      'upload.total_time_ms': 3500
+      'client.compression_applied': true
     }
   },
   async () => {
-    // Client-side upload implementation
+    // Get the current active span to update during upload
+    const span = Sentry.getActiveSpan();
+    
+    try {
+      // Begin upload process
+      const uploader = new FileUploader(file);
+      
+      // Update progress as upload proceeds
+      uploader.on('progress', (progressEvent) => {
+        if (span) {
+          span.setAttribute('upload.percent_complete', progressEvent.percent);
+          span.setAttribute('upload.bytes_transferred', progressEvent.loaded);
+        }
+      });
+      
+      uploader.on('retry', (retryCount) => {
+        if (span) {
+          span.setAttribute('upload.retry_count', retryCount);
+        }
+      });
+      
+      const result = await uploader.start();
+      
+      // Set final attributes after completion
+      if (span) {
+        span.setAttribute('upload.total_time_ms', result.totalTime);
+        span.setAttribute('upload.success', true);
+        span.setAttribute('upload.server_file_id', result.fileId);
+      }
+      
+      return result;
+    } catch (error) {
+      // Record failure information
+      if (span) {
+        span.setAttribute('upload.success', false);
+        span.setAttribute('upload.error_type', error.name);
+        span.setAttribute('upload.error_message', error.message);
+        span.setStatus({ code: 'ERROR' });
+      }
+      throw error;
+    }
   }
 );
 ```
@@ -94,21 +128,53 @@ Sentry.startSpan(
     name: 'LLM Client Interaction',
     op: 'ai.client',
     attributes: {
-      // User interaction metrics
+      // Initial metrics available at request time
       'input.char_count': 280,
       'input.language': 'en',
-      'input.type': 'question',
-      
-      // UI performance
-      'ui.time_to_first_token_ms': 245,
-      'ui.total_request_time_ms': 3250,
-      
-      // Stream handling
-      'stream.rendering_mode': 'markdown'
+      'input.type': 'question'
     }
   },
   async () => {
-    // Client-side LLM handling
+    const span = Sentry.getActiveSpan();
+    const startTime = performance.now();
+    
+    // Begin streaming response from LLM API
+    const stream = await llmClient.createCompletion({
+      prompt: userInput,
+      stream: true
+    });
+    
+    // Record time to first token when received
+    let firstTokenReceived = false;
+    let tokensReceived = 0;
+    
+    for await (const chunk of stream) {
+      tokensReceived++;
+      
+      // Record time to first token
+      if (!firstTokenReceived && chunk.content) {
+        firstTokenReceived = true;
+        const timeToFirstToken = performance.now() - startTime;
+        
+        if (span) {
+          span.setAttribute('ui.time_to_first_token_ms', timeToFirstToken);
+        }
+      }
+      
+      // Process and render the chunk
+      renderChunkToUI(chunk);
+    }
+    
+    // Record final metrics after stream completes
+    const totalRequestTime = performance.now() - startTime;
+    
+    if (span) {
+      span.setAttribute('ui.total_request_time_ms', totalRequestTime);
+      span.setAttribute('stream.rendering_mode', 'markdown');
+      span.setAttribute('stream.tokens_received', tokensReceived);
+      span.setAttribute('user.perceived_latency_ms', 
+        firstTokenReceived ? totalRequestTime - span.getAttribute('ui.time_to_first_token_ms') : totalRequestTime);
+    }
   }
 );
 ```
@@ -121,27 +187,67 @@ Sentry.startSpan(
     name: 'LLM API Processing',
     op: 'ai.server',
     attributes: {
-      // Model configuration
+      // Model configuration - known at start
       'llm.model': 'claude-3-5-sonnet-20241022',
       'llm.temperature': 0.5,
-      'llm.max_tokens': 4096,
+      'llm.max_tokens': 4096
+    }
+  },
+  async () => {
+    const span = Sentry.getActiveSpan();
+    const startTime = Date.now();
+    
+    // Record queue time if applicable
+    if (requestQueuedAt) {
+      const queueTime = startTime - requestQueuedAt;
+      if (span) {
+        span.setAttribute('llm.queue_time_ms', queueTime);
+      }
+    }
+    
+    try {
+      // Check rate limits before processing
+      const rateLimits = await getRateLimits();
+      if (span) {
+        span.setAttribute('llm.rate_limit_remaining', rateLimits.remaining);
+      }
 
-      // Token usage metrics
-      'llm.prompt_tokens': 425,
-      'llm.completion_tokens': 632,
-      'llm.total_tokens': 1057,
+      // Make the actual API call to the LLM provider
+      const response = await llmProvider.generateCompletion({
+        model: 'claude-3-5-sonnet-20241022',
+        prompt: preparedPrompt,
+        temperature: 0.5,
+        max_tokens: 4096
+      });
 
-      // Performance tracking
-      'llm.api_latency_ms': 2800,
-      'llm.queue_time_ms': 150,
+      // Record token usage and performance metrics
+      if (span) {
+        span.setAttribute('llm.prompt_tokens', response.usage.prompt_tokens);
+        span.setAttribute('llm.completion_tokens', response.usage.completion_tokens);
+        span.setAttribute('llm.total_tokens', response.usage.total_tokens);
+        span.setAttribute('llm.api_latency_ms', Date.now() - startTime);
+        
+        // Calculate and record cost based on token usage
+        const cost = calculateCost(
+          response.usage.prompt_tokens, 
+          response.usage.completion_tokens,
+          'claude-3-5-sonnet-20241022'
+        );
+        span.setAttribute('llm.cost_usd', cost);
+      }
 
-      // Cost tracking
-      'llm.cost_usd': 0.076,
-      'llm.rate_limit_remaining': 95
+      return response;
+    } catch (error) {
+      // Record error details
+      if (span) {
+        span.setAttribute('error', true);
+        span.setAttribute('error.type', error.name);
+        span.setAttribute('error.message', error.message);
+        span.setAttribute('error.is_rate_limit', error.code === 'rate_limit_exceeded');
+        span.setStatus({ code: 'ERROR' });
+      }
+      throw error;
     }
-  },
-  async () => {
-    // Server-side LLM processing
   }
 );
 ```

docs/platforms/javascript/common/tracing/span-metrics/index.mdx

@@ -1,19 +1,19 @@
 ---
-title: Span Metrics
-description: "Learn how to add custom metrics to your spans for enhanced performance monitoring and debugging."
+title: Sending Span Metrics
+description: "Learn how to add and send custom metrics to your spans for performance monitoring and debugging."
 sidebar_order: 10
 ---
 
 <Alert>
 
-To use span metrics effectively, you must first <PlatformLink to="/tracing/">set up tracing</PlatformLink> in your application.
+To use span metrics, you must first <PlatformLink to="/tracing/">configure tracing</PlatformLink> in your application.
 
 </Alert>
 
-Span metrics allow you to track custom performance data and debugging information within your application's traces. There are two main approaches to instrumenting metrics:
+Span metrics allow you to extend the default metrics that are collected by tracing and track custom performance data and debugging information within your application's traces. There are two main approaches to instrumenting metrics:
 
-1. Adding metrics to existing spans
-2. Creating dedicated spans with custom metrics
+1. [Adding metrics to existing spans](#adding-metrics-to-existing-spans)
+2. [Creating dedicated spans with custom metrics](#creating-dedicated-metric-spans)
 
 ## Adding Metrics to Existing Spans
 

docs/platforms/javascript/common/tracing/span-metrics/performance-metrics.mdx

@@ -1,5 +1,5 @@
 ---
-title: Performance Metrics
+title: Sending Performance Metrics
 description: "Learn how to attach performance metrics to your transactions."
 sidebar_order: 20
 notSupported:

redirects.js

@@ -1013,11 +1013,7 @@ const userDocsRedirects = [
   {
     source: '/platforms/javascript/guides/:guide/tracing/instrumentation/custom-instrumentation/:path*',
     destination: '/platforms/javascript/guides/:guide/tracing/instrumentation/:path*',
-  },
-  {
-    source: '/platforms/javascript/tracing/instrumentation/:path*',
-    destination: '/platforms/javascript/tracing/span-metrics/performance-metrics/:path*',
-  },
+  }
 ];
 
 /**