From e23eebd7a91bea8b4374e787788db8c37cebe27d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20Og=C3=B3rek?= <kamil.ogorek@gmail.com>
Date: Tue, 9 Oct 2018 15:38:40 +0200
Subject: [PATCH] docs: Explain getHubFromCarrier in express

---
 .../platforms/javascript/express.md           | 48 ++++++++++++++++---
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/src/collections/_documentation/platforms/javascript/express.md b/src/collections/_documentation/platforms/javascript/express.md
index 7dfe566c25079..2690ce3747313 100644
--- a/src/collections/_documentation/platforms/javascript/express.md
+++ b/src/collections/_documentation/platforms/javascript/express.md
@@ -4,20 +4,21 @@ sidebar_order: 1010
 ---
 
 <!-- WIZARD -->
+
 Our Express integration only requires _@sentry/node_ to be installed then you can use it like this:
 
 ```javascript
 const express = require('express');
 const app = express();
-const Sentry = require('@sentry/node') ;
+const Sentry = require('@sentry/node');
 
-Sentry.init({ dsn:'___PUBLIC_DSN___' });
+Sentry.init({ dsn: '___PUBLIC_DSN___' });
 
 // The request handler must be the first middleware on the app
 app.use(Sentry.Handlers.requestHandler());
 
 app.get('/', function mainHandler(req, res) {
-    throw new Error('Broke!');
+  throw new Error('Broke!');
 });
 
 // The error handler must be before any other error middleware
@@ -25,10 +26,10 @@ app.use(Sentry.Handlers.errorHandler());
 
 // Optional fallthrough error handler
 app.use(function onError(err, req, res, next) {
-    // The error id is attached to `res.sentry` to be returned
-    // and optionally displayed to the user for support.
-    res.statusCode = 500;
-    res.end(res.sentry + '\n');
+  // The error id is attached to `res.sentry` to be returned
+  // and optionally displayed to the user for support.
+  res.statusCode = 500;
+  res.end(res.sentry + '\n');
 });
 
 app.listen(3000);
@@ -55,4 +56,37 @@ app.use(Sentry.Handlers.errorHandler());
 // to
 app.use(Sentry.Handlers.errorHandler() as express.ErrorRequestHandler);
 ```
+
 <!-- ENDWIZARD -->
+
+## Working with Scopes and Hubs
+
+Because of pipeline-like nature of Express.js and it's middlewares, the user has to pass the scope through all the pipes and carry it over with the request. It's required in order to isolate requests from each other.
+
+If you want to set per-requests user data and send it over to Sentry, you need to use `getHubFromCarrier` on the `request` object, instead of directly calling methods like `configureScope` or `captureException`. Here are some examples:
+
+```javascript
+app.get('/foo', (req, res, next) => {
+  Sentry.getHubFromCarrier(req).configureScope(scope => {
+    scope.setTag('foo', 'my-value');
+  });
+
+  throw new Error('foo');
+});
+
+app.get('/foo', (req, res, next) => {
+  Sentry.getHubFromCarrier(req).configureScope(scope => {
+    scope.setTag('foo', 'my-value');
+  });
+
+  if (someCheck()) {
+    Sentry.getHubFromCarrier(req).captureMessage('Invalid eventId');
+    next();
+  } else {
+    res.end();
+  }
+});
+```
+
+All `configureScope` calls that were done directly on initialized `Sentry` object, will be carried to each request, so it's a good way to set some data globally.
+