Session Instrumentation

Generates: Events (Log Records)

Manages session lifecycle and stamps every span and log with a session.id for session-scoped analysis in the Pulse dashboard.

How It Works

On SDK initialization, a new session is created with a unique 32-character hex ID. The session ID is injected into every span and log record by the SDK's processor chain. Sessions expire based on two configurable limits:

• Max lifetime: The session expires after a fixed duration from its start time
• Background inactivity timeout: The session expires if the app remains backgrounded for longer than this period

When a session expires, a new one is automatically created on the next foreground event.

Configuration

Sessions are enabled by default.

Pulse.shared.initialize(
    endpointBaseUrl: "https://your-backend.com",
    apiKey: "your-api-key",
    instrumentations: { config in
        config.sessions { sessions in
            sessions.enabled(true)
            sessions.maxLifetime(4 * 60 * 60)             // 4 hours (default)
            sessions.backgroundInactivityTimeout(15 * 60)  // 15 minutes (default)
        }
    }
)

Configuration Options

Option	Type	Default	Description
enabled(Bool)	Bool	true	Enable/disable session tracking
maxLifetime(TimeInterval?)	TimeInterval?	14400 (4 h)	Fixed session duration from start. Pass nil to disable the hard cap
backgroundInactivityTimeout(TimeInterval?)	TimeInterval?	900 (15 min)	Time app can stay backgrounded before session expires. Pass nil to disable

warning

Change these defaults with care. Session lifetime directly defines how Pulse groups telemetry into sessions — modifying it will change what counts as a "session" across all analysis, dashboards, and alerts. It also affects Session Replay: a session boundary triggers a new replay recording, so tuning the timeout too aggressively will fragment replays or cause premature cutoffs.

What Gets Tracked

The session instrumentation emits two log events:

Session Start

Emitted when a new session begins.

Attribute	Description	Example
pulse.type	"session.start"	—
session.id	New session identifier	"f40364c92b85ec0c19c35a65be42b97f"
session.start_time	Session start epoch ms	1732694400000
session.previous_id	Prior session ID	"a1b2c3..." (if any)

Session End

Emitted when a session expires.

Attribute	Description	Example
pulse.type	"session.end"	—
session.id	Ending session identifier	"f40364c92b85ec0c19c35a65be42b97f"
session.start_time	When session started	1732694400000
session.end_time	When session ended	1732708800000
session.duration	Duration in ms	14400000

Disabling Sessions

config.sessions { $0.enabled(false) }

When disabled, no session.id is attached to spans or logs, and session start/end events are not emitted.