User Types

TypeScript interfaces for user identification

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: '[e-mail]'

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: '[e-mail]',
  
  // 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: '[e-mail]',
  username: 'johndoe',
  ip_address: '{{auto}}'
});

With Custom Fields

Sentry.setUser({
  id: 'user-123',
  email: '[e-mail]',
  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: '[e-mail]'
  }
});

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('[e-mail]')
});

Complete Examples

Basic User

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

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

User with Geo Location

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

User with Subscription Info

Sentry.setUser({
  id: 'user-123',
  email: '[e-mail]',
  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: '[e-mail]',
  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: '[e-mail]',
  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: '[e-mail]',
  
  // Useful for filtering and analysis
  segment: 'enterprise',
  cohort: '2024-Q1',
  ab_test_group: 'variant_b'
});

Related

• Scope
• Event Types
• Configuration