feat: sessions (#899)

* feat: sessions

* feat: add SessionLogRecordProcessor

* fix test

* sessionTimeout as TimeInterval

* 100% test coverage

* update previous-id in docs

---------

Co-authored-by: Bryce Buchanan <[email protected]>

Author: williazz

Package.swift

@@ -24,6 +24,7 @@ let package = Package(
     .library(name: "InMemoryExporter", targets: ["InMemoryExporter"]),
     .library(name: "OTelSwiftLog", targets: ["OTelSwiftLog"]),
     .library(name: "BaggagePropagationProcessor", targets: ["BaggagePropagationProcessor"]),
+    .library(name: "Sessions", targets: ["Sessions"]),
     .executable(name: "loggingTracer", targets: ["LoggingTracer"]),
     .executable(name: "StableMetricSample", targets: ["StableMetricSample"])
   ],
@@ -113,6 +114,16 @@ let package = Package(
       ],
       path: "Sources/Contrib/Processors/BaggagePropagationProcessor"
     ),
+    .target(
+      name: "Sessions",
+      dependencies: [
+        .product(name: "OpenTelemetryApi", package: "opentelemetry-swift-core"),
+        .product(name: "OpenTelemetrySdk", package: "opentelemetry-swift-core")
+
+      ],
+      path: "Sources/Instrumentation/Sessions",
+      exclude: ["README.md"]
+    ),
     .testTarget(
       name: "OTelSwiftLogTests",
       dependencies: ["OTelSwiftLog"],
@@ -159,6 +170,14 @@ let package = Package(
         "InMemoryExporter"
       ]
     ),
+    .testTarget(
+      name: "SessionTests",
+      dependencies: [
+        "Sessions",
+        .product(name: "OpenTelemetrySdk", package: "opentelemetry-swift-core")
+      ],
+      path: "Tests/InstrumentationTests/SessionTests"
+    ),
     .executableTarget(
       name: "LoggingTracer",
       dependencies: [

README.md

@@ -94,6 +94,7 @@ Metrics is implemented using an outdated spec, is fully functional but will chan
 * `NetworkStatus`
 * `SDKResourceExtension`
 * `SignPostIntegration`
+* `SessionsEventInstrumentation`
 
 ### Third-party exporters
 In addition to the specified OpenTelemetry exporters, some third-party exporters have been contributed and can be found in the following repos: 

Sources/Instrumentation/Sessions/README.md

@@ -0,0 +1,239 @@
+# Session Instrumentation
+
+Automatic session tracking for OpenTelemetry Swift applications. Creates unique session identifiers, tracks session lifecycle events, and automatically adds session context to all telemetry data.
+
+## Features
+
+- **Automatic Session Management** - Creates and manages session lifecycles with configurable timeouts
+- **Session Events** - Emits OpenTelemetry log records for session start/end events
+- **Span Attribution** - Automatically adds session IDs to all spans via span processor
+- **Persistence** - Sessions persist across app restarts using UserDefaults
+- **Thread Safety** - All components are thread-safe for concurrent access
+
+## Setup
+
+**Basic Setup** (default 30-minute timeout):
+
+```swift
+import Sessions
+import OpenTelemetrySdk
+
+// Record session start and end events
+let sessionInstrumentation = SessionEventInstrumentation()
+
+// Add session attributes to spans
+let sessionSpanProcessor = SessionSpanProcessor()
+let tracerProvider = TracerProviderBuilder()
+    .add(spanProcessor: sessionSpanProcessor)
+    .build()
+
+// Add session atttributes to log records
+let sessionProcessor = SessionLogRecordProcessor(
+    nextProcessor: SimpleLogRecordProcessor(logRecordExporter: ConsoleLogRecordExporter())
+)
+let builder = LoggerProviderBuilder()
+  .with(processors: [sessionProcessor])
+  .with(resource: resource)
+```
+
+**Custom Configuration**:
+
+```swift
+let sessionConfig = SessionConfigBuilder()
+    .with(sessionTimeout: 45 * 60) // 45 minutes
+    .build()
+let sessionManager = SessionManager(configuration: sessionConfig)
+SessionManagerProvider.register(sessionManager: sessionManager)
+```
+
+**Getting Session Information**:
+
+```swift
+// Get current session (extends session if active)
+let session = SessionManagerProvider.getInstance().getSession()
+print("Session ID: \(session.id)")
+
+// Peek at session without extending it
+if let session = SessionManagerProvider.getInstance().peekSession() {
+    print("Current session: \(session.id)")
+}
+```
+
+## Components
+
+### SessionManager
+
+Manages session lifecycle with automatic expiration and renewal.
+
+```swift
+let manager = SessionManager(configuration: SessionConfig(sessionTimeout: 1800))
+let session = manager.getSession() // Creates or extends session
+let session = manager.peekSession() // Peek without extending
+```
+
+### SessionManagerProvider
+
+Provides thread-safe singleton access to SessionManager.
+
+```swift
+// Register a custom session manager
+let manager = SessionManager(configuration: SessionConfig(sessionTimeout: 3600))
+SessionManagerProvider.register(sessionManager: manager)
+
+// Access from anywhere
+let session = SessionManagerProvider.getInstance().getSession()
+```
+
+### SessionSpanProcessor
+
+Automatically adds session IDs to all spans.
+
+```swift
+let processor = SessionSpanProcessor(sessionManager: sessionManager)
+// Adds session.id and session.previous_id attributes to spans
+```
+
+### SessionLogRecordProcessor
+
+Automatically adds session IDs to all log records.
+
+```swift
+let processor = SessionLogRecordProcessor(nextProcessor: yourProcessor)
+// Adds session.id and session.previous_id attributes to log records
+```
+
+### SessionEventInstrumentation
+
+Creates OpenTelemetry log records for session lifecycle events.
+
+```swift
+let instrumentation = SessionEventInstrumentation()
+// Emits session.start and session.end log records
+```
+
+### Session Model
+
+Represents a session with ID, timestamps, and expiration logic.
+
+```swift
+let session = Session(
+    id: "unique-session-id",
+    expireTime: Date(timeIntervalSinceNow: 1800),
+    previousId: "previous-session-id"
+)
+
+print("Expired: \(session.isExpired())")
+print("Duration: \(session.duration ?? 0)")
+```
+
+## Configuration
+
+### SessionConfig
+
+| Field            | Type  | Description                                                        | Default         | Required |
+| ---------------- | ----- | ------------------------------------------------------------------ | --------------- | -------- |
+| `sessionTimeout` | `TimeInterval` | Duration in seconds after which a session expires if left inactive | `1800` (30 min) | No       |
+
+```swift
+let config = SessionConfigBuilder()
+    .with(sessionTimeout: 30 * 60)
+    .build()
+```
+
+### Session Timeout Behavior
+
+- Sessions automatically expire after the configured timeout period of inactivity
+- Accessing a session via `getSession()` extends the expiration time
+- Expired sessions trigger `session.end` events and create new sessions with `previous_id` links
+
+## Session Events
+
+Emits OpenTelemetry log records following semantic conventions:
+
+### Session Start
+
+A `session.start` log record is created when a new session begins.
+
+**Example session.start Event**:
+
+```json
+{
+  "body": "session.start",
+  "attributes": {
+    "session.id": "550e8400-e29b-41d4-a716-446655440000",
+    "session.start_time": 1692123456789000000,
+    "session.previous_id": "71260ACC-5286-455F-9955-5DA8C5109A07"
+  }
+}
+```
+
+**Session Start Attributes**:
+
+| Attribute             | Type   | Description                                   | Example                                  |
+| --------------------- | ------ | --------------------------------------------- | ---------------------------------------- |
+| `session.id`          | string | Unique identifier for the current session     | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `session.start_time`  | double | Session start time in nanoseconds since epoch | `1692123456789000000`                    |
+| `session.previous_id` | string | Identifier of the previous session (if any)   | `"71260ACC-5286-455F-9955-5DA8C5109A07"`                  |
+
+### Session End
+
+A `session.end` log record is created when a session expires.
+
+**Example session.end Event**:
+
+```json
+{
+  "body": "session.end",
+  "attributes": {
+    "session.id": "550e8400-e29b-41d4-a716-446655440000",
+    "session.start_time": 1692123456789000000,
+    "session.end_time": 1692125256789000000,
+    "session.duration": 1800000000000,
+    "session.previous_id": "71260ACC-5286-455F-9955-5DA8C5109A07"
+  }
+}
+```
+
+**Session End Attributes**:
+
+| Attribute             | Type   | Description                                   | Example                                  |
+| --------------------- | ------ | --------------------------------------------- | ---------------------------------------- |
+| `session.id`          | string | Unique identifier for the ended session       | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `session.start_time`  | double | Session start time in nanoseconds since epoch | `1692123456789000000`                    |
+| `session.end_time`    | double | Session end time in nanoseconds since epoch   | `1692125256789000000`                    |
+| `session.duration`    | double | Session duration in nanoseconds               | `1800000000000` (30 minutes)             |
+| `session.previous_id` | string | Identifier of the previous session (if any)   | `"71260ACC-5286-455F-9955-5DA8C5109A07"`                  |
+
+## Span and Log Attribution
+
+`SessionSpanProcessor` and `SessionLogRecordProcessor` automatically add session attributes to all spans and log records:
+
+| Attribute             | Type   | Description                                  | Example                                  |
+| --------------------- | ------ | -------------------------------------------- | ---------------------------------------- |
+| `session.id`          | string | Current active session identifier            | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `session.previous_id` | string | Previous session identifier (when available) | `"71260ACC-5286-455F-9955-5DA8C5109A07"`                  |
+
+**Special Handling**: For `session.start` and `session.end` log records, the processors preserve the existing session attributes rather than overriding them with current session data, ensuring historical accuracy of session events.
+
+## Best Practices
+
+1. **Use SessionManagerProvider** - Register your session manager as a singleton for consistent access
+2. **Configure Appropriate Timeouts** - Set session timeouts based on your app's usage patterns
+3. **Add Span Processor Early** - Register the SessionSpanProcessor before creating spans
+4. **Handle Session Events** - Set up SessionEventInstrumentation to capture session lifecycle
+
+## Persistence
+
+Sessions are automatically persisted to UserDefaults and restored on app restart:
+
+- Active sessions continue from their previous state
+- Expired sessions create new sessions with proper `previous_id` linking
+- Session data is saved periodically (every 30 seconds) to minimize disk I/O
+
+## Thread Safety
+
+All components are designed for concurrent access:
+
+- `SessionManager` uses locks for thread-safe session access
+- `SessionManagerProvider` provides thread-safe singleton access
+- `SessionStore` handles concurrent persistence operations safely

Sources/Instrumentation/Sessions/Session.swift

@@ -0,0 +1,90 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import Foundation
+
+/// Represents an OpenTelemetry session with lifecycle management.
+///
+/// A session tracks user activity with automatic expiration and renewal capabilities.
+/// Sessions include unique identifiers, timestamps, and linkage to previous sessions.
+///
+/// Example:
+/// ```swift
+/// let session = Session(
+///     id: UUID().uuidString,
+///     expireTime: Date(timeIntervalSinceNow: 1800),
+///     previousId: "previous-session-id"
+/// )
+///
+/// if session.isExpired() {
+///     print("Session ended at: \(session.endTime!)")
+///     print("Duration: \(session.duration!) seconds")
+/// }
+/// ```
+public struct Session: Equatable {
+  /// Unique identifier for the session
+  public let id: String
+  /// Expiration time for the session
+  public let expireTime: Date
+  /// Unique identifier of the user's previous session, if any
+  public let previousId: String?
+  /// Start time of the session
+  public let startTime: Date
+  /// The duration in seconds after which this session expires if inactive
+  public let sessionTimeout: TimeInterval
+
+  /// Creates a new session
+  /// - Parameters:
+  ///   - id: Unique identifier for the session
+  ///   - expireTime: Expiration time for the session
+  ///   - previousId: Unique identifier of the user's previous session, if any
+  ///   - startTime: Start time of the session, defaults to current time
+  ///   - sessionTimeout: Duration in seconds after which the session expires if inactive
+  public init(id: String,
+              expireTime: Date,
+              previousId: String? = nil,
+              startTime: Date = Date(),
+              sessionTimeout: TimeInterval = SessionConfig.default.sessionTimeout) {
+    self.id = id
+    self.expireTime = expireTime
+    self.previousId = previousId
+    self.startTime = startTime
+    self.sessionTimeout = sessionTimeout
+  }
+
+  /// Two sessions are considered equal if they have the same ID, prevID, startTime, and expiry timestamp
+  public static func == (lhs: Session, rhs: Session) -> Bool {
+    return lhs.expireTime == rhs.expireTime &&
+      lhs.id == rhs.id &&
+      lhs.previousId == rhs.previousId &&
+      lhs.startTime == rhs.startTime &&
+      lhs.sessionTimeout == rhs.sessionTimeout
+  }
+
+  /// Checks if the session has expired
+  /// - Returns: True if the current time is past the session's expireTime time
+  public func isExpired() -> Bool {
+    return expireTime <= Date()
+  }
+
+  /// The time when the session ended (only available for expired sessions).
+  ///
+  /// For expired sessions, this returns the calculated end time based on when the session
+  /// was last active. For active sessions, this returns nil.
+  /// - Returns: The session end time, or nil if the session is still active
+  public var endTime: Date? {
+    guard isExpired() else { return nil }
+    return expireTime.addingTimeInterval(-Double(sessionTimeout))
+  }
+
+  /// The total duration the session was active (only available for expired sessions).
+  ///
+  /// Calculates the time between session start and end. Only available for expired sessions.
+  /// - Returns: The session duration in seconds, or nil if the session is still active
+  public var duration: TimeInterval? {
+    guard let endTime = endTime else { return nil }
+    return endTime.timeIntervalSince(startTime)
+  }
+}