From 28d992d6a0efb9eaca6f304a22647f84396140d0 Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Thu, 23 Mar 2017 14:16:39 -0700
Subject: [PATCH] Add explain comment for synthetic trace path

---
 src/raven.js | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/raven.js b/src/raven.js
index b1608a29a5a7..d3648e5178b7 100644
--- a/src/raven.js
+++ b/src/raven.js
@@ -392,9 +392,10 @@ Raven.prototype = {
 
         if (this._globalOptions.stacktrace || (options && options.stacktrace)) {
             var ex;
-            // create a stack trace from this point; just trim
-            // off extra frames so they don't include this function call (or
-            // earlier Raven.js library fn calls)
+            // Generate a "synthetic" stack trace from this point.
+            // NOTE: If you are a Sentry user, and you are seeing this stack frame, it is NOT indicative
+            //       of a bug with Raven.js. Sentry generates synthetic traces either by configuration,
+            //       or if it catches a thrown object without a "stack" property.
             try {
                 throw new Error(msg);
             } catch (ex1) {
@@ -408,6 +409,9 @@ Raven.prototype = {
                 // fingerprint on msg, not stack trace (legacy behavior, could be
                 // revisited)
                 fingerprint: msg,
+                // since we know this is a synthetic trace, the top N-most frames
+                // MUST be from Raven.js, so mark them as in_app later by setting
+                // trimHeadFrames
                 trimHeadFrames: (options.trimHeadFrames || 0) + 1
             }, options);