Session Management Infrastructure

[gregory-at-cvs]

PR #2: Session Management Infrastructure

Description

Adds foundational infrastructure for session tracking across all telemetry signals.

This PR includes:

Core Session Utilities

• SessionIdentifiers - Data class for session.id and session.previous_id
• SessionExtensions - Kotlin extensions for adding session IDs to spans/logs/metrics
• SessionIdentifierFacade - Facade pattern for consistent session access
• SessionIdFacade - UUID fallback for session ID generation

Metrics Infrastructure

• SessionMetricExporterAdapter - Adapter pattern for adding session IDs to metrics
• Decorator pattern for all metric data types (Sum, Gauge, Histogram, etc.)
• Factory classes for creating session-enhanced metric data
• 11 wrapper models for different metric types

Key Addition: This enables session-based metrics analytics - a capability
not present in the iOS or JavaScript SDKs! This allows correlating metrics
like memory usage, network bytes, or performance counters to specific user sessions.

Design Patterns Used

• Adapter Pattern - Wraps metric exporters to inject session attributes
• Factory Pattern - Creates session-enhanced metric data
• Decorator Pattern - Adds session attributes without modifying original data
• Facade Pattern - Simplifies session identifier access

Related PRs

This is part 2 of 3 in a comprehensive session management enhancement:

• PR 1: Concurrency fix
• This PR: Session infrastructure (core utilities + metrics)
• PR 3: Session telemetry integration

Dependencies:

• ⚠️ Depends on [PR 1] - Requires thread-safe SessionManager before building infrastructure
• 📦 Provides foundation for [PR 3] - Core utilities will be used by instrumentation integration

Review Strategy:

• ✅ Ready for review now - Can review for design/architecture feedback
• ⚠️ Should not merge until PR #1 merges - Has technical dependency
• 💡 Best reviewed alongside PR 3 - Provides context on how infrastructure is used

Type of Change

• Bug fix
• New feature (non-breaking)
• Breaking change
• Infrastructure improvement

Checklist

• Code follows project style guidelines (spotless applied)
• Self-review completed
• Comprehensive test coverage added
• New and existing tests pass locally
• Documentation added for new components

Testing

• Test coverage for all factories and adapters (~1,400 lines of tests)
• Metric data transformation tests
• Session identifier extraction tests
• Edge cases (empty IDs, null handling, etc.)

Additional Context

Comparison with Other Platforms:

• iOS Swift SDK: Has session support for spans/logs, but NOT metrics
• Web JavaScript SDK: Has interface only, no automatic implementation yet
• This Android implementation: First to support session IDs on metrics!

This infrastructure establishes the foundation for comprehensive session tracking.
PR 3 integrates this across all instrumentation modules.

Why metrics matter: Session-based metrics enable queries like:

• "Average memory usage per session"
• "Network bytes transferred in sessions that crashed"
• "Session duration vs. performance metrics correlation"

None of the other SDKs can answer these questions today!

References

• OpenTelemetry Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/general/session/
• Depends on: [PR 1] - Session concurrency fix
• Used by: [PR 3] - Session telemetry integration

[codecov]

Codecov Report

❌ Patch coverage is 94.91525% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.54%. Comparing base (7e5a63e) to head (582fd4c).

Files with missing lines	Patch %	Lines
...oid/agent/session/factory/SessionManagerFactory.kt	0.00%	4 Missing ⚠️
...ndroid/export/models/DoublePointWithSessionData.kt	81.81%	2 Missing ⚠️
.../android/export/models/LongPointWithSessionData.kt	81.81%	2 Missing ⚠️
...opentelemetry/android/OpenTelemetryRumBuilder.java	83.33%	0 Missing and 1 partial ⚠️
...models/ExponentialHistogramPointWithSessionData.kt	95.00%	1 Missing ⚠️
...oid/export/models/HistogramPointWithSessionData.kt	94.44%	1 Missing ⚠️
.../io/opentelemetry/android/ktx/SessionExtensions.kt	94.44%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1420      +/-   ##
==========================================
+ Coverage   63.65%   65.54%   +1.88%     
==========================================
  Files         159      180      +21     
  Lines        3134     3349     +215     
  Branches      326      340      +14     
==========================================
+ Hits         1995     2195     +200     
- Misses       1042     1054      +12     
- Partials       97      100       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.