Users
Learn how to configure the SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry.
Users consist of a few critical pieces of information that construct a unique identity in Sentry. Each of these is optional, but one must be present for the Sentry SDK to capture the user:
Your internal identifier for the user.
The username. Typically used as a better label than the internal id.
An alternative, or addition, to the username. Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities.
The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (request.env.REMOTE_ADDR field in JSON), if available. This requires you to set the include.ip option to true in the RequestData integration.
If the user's ip_address is set to "{{auto}}", Sentry will infer the IP address from the connection between your app and Sentry's server.
If the field is omitted, the default value is "{{auto}}". SDKs and other clients should not rely on this behavior and should set IP addresses or "{{auto}}" explicitly.
To ensure your users' IP addresses are never stored in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's server-side data scrubbing to remove $user.ip_address. Adding such a rule ultimately overrules any other logic.
Additionally, you can provide arbitrary key/value pairs beyond the reserved names, and the Sentry SDK will store those with the user.
You can set the user by calling the setUser method on the Sentry SDK:
Sentry.setUser({ email: "john.doe@example.com" });
You can also clear the currently set user:
Sentry.setUser(null);
Sentry.setUser() will set the user for the currently active request - see Request Isolation for more information. For example, if you want to set the user for a single request, you can do this like this:
// Your route handler, for example:
app.get("/my-route", (req, res) => {
// Get the user from somewhere
const user = req.user;
// Set the user data for this request only
Sentry.setUser({
id: user.id,
email: user.email,
username: user.username,
});
res.send("Hello World");
});
Or if you want to set the user for all requests, you could use a middleware like this:
// Add a middleware, for example:
app.use((req, res, next) => {
// Get the user from somewhere
const user = req.user;
// Set the user data for all requests
if (user) {
Sentry.setUser({
id: user.id,
email: user.email,
username: user.username,
});
} else {
Sentry.setUser(null);
}
next();
});
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").