Simplify examples to single-span patterns (no nested spans). Emphasize auto-instrumentation; keep attributes minimal and business-focused for easier customization.

Author: codyde

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

@@ -65,41 +65,28 @@ Where to put this in your app:
 - In the `onClick` for the checkout CTA, or inside the submit handler of your checkout form/container component.
 - Auto-instrumentation will add client `fetch` spans; keep the explicit UI span for business context.
 
-**Backend — instrument each business step:**
+**Backend — single span per request; rely on auto-instrumentation:**
 
 ```javascript
 // Example: Node/Express
 app.post("/api/checkout", async (req, res) => {
-  await Sentry.startSpan({ name: "Process order", op: "business.logic" }, async (orderSpan) => {
+  await Sentry.startSpan({ name: "Checkout (server)", op: "http.server" }, async (span) => {
     try {
-      await Sentry.startSpan({ name: "Validate cart", op: "validate" }, async () => {
-        // validate item availability, pricing, coupon
-      });
-
-      const payment = await Sentry.startSpan({ name: "Authorize payment", op: "payment" }, async (span) => {
-        span.setAttribute("payment.provider", "stripe");
-        // call payment provider
-        return { id: "pi_123", status: "authorized" };
-      });
-      orderSpan.setAttribute("payment.status", payment.status);
-
-      await Sentry.startSpan({ name: "Reserve inventory", op: "inventory" }, async () => {
-        // reserve stock in DB or external OMS
-      });
-
-      const orderId = await Sentry.startSpan({ name: "Create order", op: "db.write" }, async () => {
-        // insert order; return internal id
-        return "ord_abc123";
-      });
-      orderSpan.setAttribute("order.id", orderId);
-
-      await Sentry.startSpan({ name: "Send confirmation", op: "email" }, async () => {
-        // enqueue email or call provider
+      // validate, authorize payment, reserve inventory, create order, send email
+      const orderId = await createOrder(req.body);
+
+      // Keep attributes low-cardinality and business-focused
+      span.setAttributes({
+        "order.id": orderId,
+        "payment.provider": "stripe",
+        "payment.status": "authorized",
+        "inventory.reserved": true,
+        "email.enqueued": true,
       });
 
       res.json({ orderId, paymentProvider: "stripe" });
     } catch (e) {
-      orderSpan.setStatus?.("error");
+      span.setStatus?.("error");
       res.status(500).json({ error: "Checkout failed" });
     }
   });
@@ -108,7 +95,7 @@ app.post("/api/checkout", async (req, res) => {
 
 **How the trace works together:**
 - UI span starts on click → fetch carries trace headers → backend continues the trace.
-- Child spans highlight where time is spent (validation, payment, inventory, DB, email).
+- Rely on your SDK's auto-instrumentation for HTTP/DB/external calls; keep this example span simple.
 - Span metrics let you track latency percentiles and failure rates by attributes like `payment.provider`, `cart.item_count`.
 
 What to monitor with span metrics:
@@ -122,7 +109,7 @@ What to monitor with span metrics:
 
 **Solution:** Start a client span when the upload begins; on the backend, create spans for signed-URL issuance, enqueue a job, and instrument worker phases. Propagate trace context via job metadata to stitch the traces.
 
-**Frontend (React) — instrument upload begin and progress:**
+**Frontend (React) — instrument upload begin and completion:**
 
 ```javascript
 Sentry.startSpan(
@@ -132,27 +119,28 @@ Sentry.startSpan(
     attributes: {
       "file.size_bytes": file.size,
       "file.mime_type": file.type,
-      "upload.chunked": true,
     },
   },
   async (span) => {
+    const t0 = performance.now();
     try {
       const urlRes = await fetch("/api/uploads/signed-url", { method: "POST" });
       const { uploadUrl, objectKey } = await urlRes.json();
 
-      // Use XHR for progress; fetch is illustrative here
-      await uploadWithProgress(uploadUrl, file, (progress) => {
-        span.setAttribute("upload.bytes_transferred", progress.bytes);
-        span.setAttribute("upload.percent_complete", progress.percent);
-      });
+      // Upload file to storage (signed URL)
+      await fetch(uploadUrl, { method: "PUT", body: file });
 
+      // Tell backend to start async processing
       await fetch("/api/uploads/start-processing", {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ key: objectKey }),
       });
 
-      span.setAttribute("upload.success", true);
+      span.setAttributes({
+        "upload.success": true,
+        "upload.duration_ms": Math.round(performance.now() - t0),
+      });
     } catch (e) {
       span.setStatus?.("error");
       Sentry.captureException(e);
@@ -165,15 +153,13 @@ Sentry.startSpan(
 
 Place this where the user triggers an upload (dropzone onDrop, file input onChange, or explicit Upload button).
 
-**Backend — signed URL, enqueue job, and worker phases:**
+**Backend — single span per handler; single span in worker:**
 
 ```javascript
 // Issue signed URL
 app.post("/api/uploads/signed-url", async (req, res) => {
-  await Sentry.startSpan({ name: "Get signed URL", op: "storage.sign" }, async (span) => {
-    span.setAttribute("storage.provider", "s3");
-    span.setAttribute("storage.bucket", "media");
-    // generate URL
+  await Sentry.startSpan({ name: "Signed URL", op: "storage.sign" }, async (span) => {
+    span.setAttributes({ "storage.provider": "s3", "storage.bucket": "media" });
     res.json({ uploadUrl: "https://s3...", objectKey: "uploads/abc.jpg" });
   });
 });
@@ -191,14 +177,13 @@ app.post("/api/uploads/start-processing", async (req, res) => {
 // Worker
 worker.on("message", async (msg) => {
   const parentContext = msg.trace; // restore trace/parent if available
-  await Sentry.startSpan({ name: "Process media", op: "worker.job", parentContext }, async (jobSpan) => {
-    await Sentry.startSpan({ name: "Virus scan", op: "security.scan" }, async (span) => {
-      span.setAttribute("scan.engine", "clamav");
+  await Sentry.startSpan({ name: "Process media", op: "worker.job", parentContext }, async (span) => {
+    // Do work (scan, transcode, thumbnail) — rely on auto-instrumentation for sub-operations
+    span.setAttributes({
+      "scan.engine": "clamav",
+      "transcode.preset": "720p",
+      "thumbnail.created": true,
     });
-    await Sentry.startSpan({ name: "Transcode", op: "media.transcode" }, async (span) => {
-      span.setAttribute("transcode.preset", "720p");
-    });
-    await Sentry.startSpan({ name: "Thumbnail", op: "media.thumbnail" }, async () => {});
   });
 });
 ```
@@ -269,31 +254,21 @@ async function runSearch(query, debounceMs = 150) {
 
 Place this in your search input hook/component after applying a debounce.
 
-**Backend — cache, search engine, rank:**
+**Backend — single span with useful attributes:**
 
 ```javascript
 app.get("/api/search", async (req, res) => {
   const q = String(req.query.q || "");
-
-  await Sentry.startSpan({ name: "Search", op: "search" }, async (root) => {
-    const cacheHit = await Sentry.startSpan({ name: "Cache lookup", op: "cache" }, async (span) => {
-      const hit = await cache.get(q);
-      span.setAttribute("cache.hit", Boolean(hit));
-      if (hit) res.json(hit);
-      return Boolean(hit);
-    });
-    if (cacheHit) return;
-
-    const results = await Sentry.startSpan({ name: "Query engine", op: "external.search" }, async (span) => {
-      span.setAttribute("search.engine", "elasticsearch");
-      span.setAttribute("search.index", "products_v2");
-      span.setAttribute("search.mode", q.length < 3 ? "prefix" : "fuzzy");
-      return searchEngine.query(q);
-    });
-
-    await Sentry.startSpan({ name: "Rank results", op: "compute.rank" }, async (span) => {
-      span.setAttribute("rank.model", "bm25");
-      span.setAttribute("rank.version", "2.1");
+  await Sentry.startSpan({ name: "Search", op: "search" }, async (span) => {
+    const hit = await cache.get(q);
+    span.setAttribute("cache.hit", Boolean(hit));
+    if (hit) return res.json(hit);
+
+    const results = await searchEngine.query(q);
+    span.setAttributes({
+      "search.engine": "elasticsearch",
+      "search.mode": q.length < 3 ? "prefix" : "fuzzy",
+      "results.count": results.length,
     });
 
     res.json({ results });
@@ -303,7 +278,7 @@ app.get("/api/search", async (req, res) => {
 
 **How the trace works together:**
 - Each debounced request becomes a client span; aborted ones are marked and short.
-- Server spans show cache effectiveness, engine latency, and ranking time.
+- The server span shows cache effectiveness and search mode; auto-instrumentation will cover network/DB latency.
 
 What to monitor with span metrics:
 - p95 latency of `op:http.client` by `query.length` bucket.