Skip to main content
User types define the structure of user information attached to events.

​
User Interface

From packages/core/src/types-hoist/user.ts: 
export interface User {
  [key: string]: any;
  id?: string | number;
  ip_address?: string | null;
  email?: string;
  username?: string;
  geo?: GeoLocation;
}

​
Fields

​
id

​
id
string | number
Unique identifier for the user. Can be a string or number.
id: 'user-123'
id: 12345

​
email

​
email
string
User’s email address.
email: '[email protected]'

​
username

​
username
string
User’s username or display name.
username: 'johndoe'

​
ip_address

​
ip_address
string | null
User’s IP address. Use '{{auto}}' to automatically capture from request.
ip_address: '192.168.1.1'
ip_address: '{{auto}}' // Auto-capture from request
ip_address: null // Explicitly don't capture

​
geo

​
geo
GeoLocation
Geographic location information.
geo: {
  country_code: 'US',
  region: 'California',
  city: 'San Francisco'
}

​
Custom Fields

The User interface allows arbitrary custom fields: 
const user: User = {
  id: 'user-123',
  email: '[email protected]',
  
  // Custom fields
  subscription_plan: 'premium',
  account_age_days: 365,
  is_beta_tester: true,
  signup_date: '2024-01-01',
  preferences: {
    theme: 'dark',
    notifications: true
  }
};

​
GeoLocation Interface

export interface GeoLocation {
  country_code?: string;
  region?: string;
  city?: string;
}

​
Fields

​
country_code
string
Two-letter ISO country code.
country_code: 'US'
​
region
string
State, province, or region name.
region: 'California'
​
city
string
City name.
city: 'San Francisco'

​
Setting User Context

​
Using Scope

import * as Sentry from '@sentry/node';

Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'johndoe',
  ip_address: '{{auto}}'
});

​
With Custom Fields

Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'johndoe',
  
  // Custom fields
  subscription: 'premium',
  signup_date: '2024-01-01',
  is_verified: true
});

​
Clearing User

// Clear user context
Sentry.setUser(null);

​
Per-Event User

import * as Sentry from '@sentry/node';

Sentry.captureException(error, {
  user: {
    id: 'user-456',
    email: '[email protected]'
  }
});

​
Privacy Considerations

​
Automatic IP Capture

// Capture IP automatically from request
Sentry.setUser({
  id: 'user-123',
  ip_address: '{{auto}}'
});

​
Disable IP Capture

// Explicitly don't capture IP
Sentry.setUser({
  id: 'user-123',
  ip_address: null
});

// Or configure globally
Sentry.init({
  dsn: 'your-dsn',
  sendDefaultPii: false
});

​
Hashing Emails

import { createHash } from 'crypto';

function hashEmail(email: string): string {
  return createHash('sha256').update(email).digest('hex');
}

Sentry.setUser({
  id: 'user-123',
  // Use hashed email instead of plain text
  email_hash: hashEmail('[email protected]')
});

​
Complete Examples

​
Basic User

import * as Sentry from '@sentry/node';

Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'johndoe'
});

​
User with Geo Location

Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  geo: {
    country_code: 'US',
    region: 'California',
    city: 'San Francisco'
  }
});

​
User with Subscription Info

Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'johndoe',
  
  subscription_plan: 'premium',
  subscription_status: 'active',
  mrr: 99.99,
  signup_date: '2024-01-01',
  trial_end_date: null
});

​
User in Express Middleware

import * as Sentry from '@sentry/node';
import type { Request, Response, NextFunction } from 'express';

app.use((req: Request, res: Response, next: NextFunction) => {
  if (req.user) {
    Sentry.setUser({
      id: req.user.id,
      email: req.user.email,
      username: req.user.username,
      role: req.user.role,
      ip_address: '{{auto}}'
    });
  }
  next();
});

​
User with Authentication Context

import * as Sentry from '@sentry/node';

function setAuthenticatedUser(user: AuthUser, authMethod: string) {
  Sentry.setUser({
    id: user.id,
    email: user.email,
    username: user.username,
    
    // Authentication details
    auth_method: authMethod,
    auth_time: new Date().toISOString(),
    session_id: user.sessionId,
    
    // User attributes
    account_type: user.accountType,
    permissions: user.permissions.join(','),
    two_factor_enabled: user.has2FA
  });
}

setAuthenticatedUser(currentUser, 'oauth');

​
Best Practices

​
1. Always Set User ID

// Minimum: Always include user ID
Sentry.setUser({
  id: 'user-123'
});

​
2. Clear User on Logout

function handleLogout() {
  // Clear user context
  Sentry.setUser(null);
  
  // Perform logout
  performLogout();
}

​
3. Don’t Include Sensitive Data

// Bad - includes sensitive data
Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  password_hash: '...',  // Never include
  ssn: '123-45-6789',    // Never include
  credit_card: '...'     // Never include
});

// Good - only non-sensitive data
Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  subscription_plan: 'premium'
});

​
4. Use Consistent ID Format

// Choose one format and stick with it
Sentry.setUser({ id: 'user-123' });     // String format
Sentry.setUser({ id: 123 });            // Numeric format

// Don't mix formats
// Sentry.setUser({ id: 'user-123' });
// Sentry.setUser({ id: 456 });          // Inconsistent

​
5. Include User Segments

Sentry.setUser({
  id: 'user-123',
  email: '[email protected]',
  
  // Useful for filtering and analysis
  segment: 'enterprise',
  cohort: '2024-Q1',
  ab_test_group: 'variant_b'
});

Build docs developers (and LLMs) love

Get started for freeTalk to us