0
# Session Timing
1

2
Adds session duration information to all events, tracking time since Sentry initialization. This integration provides temporal context for errors and helps understand application session lifecycle.
3

4
## Capabilities
5

6
### Modern Function-based Integration
7

8
```typescript { .api }
9
/**
10
 * Adds session timing information to all events
11
 * @returns Integration instance that tracks session duration
12
 */
13
function sessionTimingIntegration(): Integration;
14
```
15

16
### Legacy Class-based Integration (Deprecated)
17

18
```typescript { .api }
19
/**
20
 * Legacy class-based session timing integration
21
 * @deprecated Use sessionTimingIntegration() instead
22
 */
23
class SessionTiming implements Integration {
24
  name: string;
25
  processEvent(event: Event): Event;
26
}
27
```
28

29
## Behavior
30

31
The integration adds three timing properties to the `extra` field of every event:
32

33
### Session Start Time
34

35
- **Property**: `session:start`
36
- **Value**: Timestamp (milliseconds) when integration was initialized
37
- **Purpose**: Reference point for session duration calculations
38

39
### Session Duration
40

41
- **Property**: `session:duration`  
42
- **Value**: Milliseconds elapsed since session start
43
- **Purpose**: How long the application has been running when event occurred
44

45
### Event Time
46

47
- **Property**: `session:end`
48
- **Value**: Timestamp (milliseconds) when event was processed
49
- **Purpose**: Exact moment when the event was created
50

51
## Usage Examples
52

53
```typescript
54
import { sessionTimingIntegration } from '@sentry/integrations';
55
import * as Sentry from '@sentry/browser';
56

57
// Add session timing to all events
58
Sentry.init({
59
  dsn: 'YOUR_DSN',
60
  integrations: [
61
    sessionTimingIntegration()
62
  ]
63
});
64

65
// Session timing works with any error or message
66
setTimeout(() => {
67
  throw new Error('Error after 5 seconds');
68
}, 5000);
69

70
// The error event will include timing information:
71
// extra: {
72
//   'session:start': 1640995200000,
73
//   'session:duration': 5000,
74
//   'session:end': 1640995205000
75
// }
76
```
77

78
## Event Enhancement
79

80
All events processed by this integration receive additional timing context:
81

82
```typescript
83
// Original event
84
{
85
  message: "User action failed",
86
  extra: {
87
    userId: "12345"
88
  }
89
}
90

91
// Enhanced with session timing
92
{
93
  message: "User action failed", 
94
  extra: {
95
    userId: "12345",
96
    "session:start": 1640995200000,    // Session initialized
97
    "session:duration": 15000,         // 15 seconds since start
98
    "session:end": 1640995215000       // Current timestamp
99
  }
100
}
101
```
102

103
## Use Cases
104

105
### Error Context Analysis
106

107
Understanding when errors occur during the application lifecycle:
108
- **Immediate errors**: Problems during application startup
109
- **Long-running sessions**: Issues that appear after extended usage
110
- **Session patterns**: Correlating error frequency with session duration
111

112
### Performance Monitoring
113

114
Tracking application behavior over time:
115
- **Memory leaks**: Errors increasing with session duration
116
- **Resource exhaustion**: Problems appearing after certain runtime thresholds
117
- **Lifecycle issues**: Errors specific to application startup or long usage
118

119
### User Experience Analysis
120

121
Understanding user interaction patterns:
122
- **Quick exits**: Errors causing immediate user departure
123
- **Extended usage**: Problems affecting long-term users
124
- **Session quality**: Correlation between session length and error rates
125

126
## Integration with Other Tools
127

128
### Custom Dashboards
129

130
Session timing data enables temporal analysis:
131
```typescript
132
// Query events by session duration ranges
133
// 0-30s: startup errors
134
// 30s-5min: short session errors  
135
// 5min+: long session errors
136
```
137

138
### Alert Configuration
139

140
Set up alerts based on session timing:
141
```typescript
142
// Alert on errors occurring very early in sessions
143
if (event.extra['session:duration'] < 10000) {
144
  // Potential startup issue
145
}
146
```
147

148
## No Configuration Required
149

150
This integration has no configuration options - it automatically tracks timing for all events from the moment it's initialized. The timing starts when the integration is created, not when Sentry.init() is called, providing accurate session duration measurement.
151

152
This integration is lightweight and provides valuable temporal context for debugging and analysis without any performance impact or additional setup requirements.