DEMRUM-1307: Implement local sampling (#305)

* feat: Implement session (agent) sampling mechanism and related logic

* chore: Self review

* chore: Add sampling configuration to DevelApp

* fix: Fix various compilation errors in tests

* fix: Properly fix Agent tests, introduce .shared singleton resetting helper method

* fix: Fix SplunkCrashReportsTests crashreporter dependency

Author: c0mtru1se

Applications/DevelApp/DevelApp/DevelAppApp.swift

@@ -28,6 +28,9 @@ struct DevelAppApp: App {
             deploymentEnvironment: "dev"
         )
             .enableDebugLogging(true)
+            // Sampled-out agent
+            //.sessionSamplingRate(0)
+            .sessionSamplingRate(1)
 
         let agent = try! SplunkRum.install(with: agentConfig)
 

Package.swift

@@ -177,7 +177,11 @@ func generateMainTargets() -> [Target] {
         ),
         .testTarget(
             name: "SplunkCrashReportsTests",
-            dependencies: ["SplunkCrashReports", "SplunkCommon", "PLCrashReporter"],
+            dependencies: [
+                "SplunkCrashReports",
+                "SplunkCommon",
+                .product(name: "CrashReporter", package: "PLCrashReporter")
+            ],
             path: "SplunkCrashReports/Tests"
         ),
 

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Random Number Providers/SystemRandomNumberProvider.swift

@@ -0,0 +1,44 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import Foundation
+
+/// A protocol designed for objects that can provide random numbers.
+protocol RandomNumberProvider {
+
+    /// Generates a random `Double` within the specified inclusive range.
+    ///
+    /// - Parameters:
+    ///   - range: A `ClosedRange<Double>` specifying the lower and upper bounds for the random number.
+    /// - Returns: A random `Double` within the specified range.
+    func randomNumber(in range: ClosedRange<Double>) -> Double
+}
+
+/// A default implementation of `RandomNumberProvider` that utilizes the
+/// system's `Double.random(in:)` function for generating random numbers.
+///
+/// This provider is suitable for most general-purpose statistical samplers.
+struct SystemRandomNumberProvider: RandomNumberProvider {
+
+    /// Generates a random `Double` using `Double.random(in: range)`.
+    ///
+    /// - Parameter range: The inclusive range within which to generate the random number.
+    /// - Returns: A random `Double` within the specified range.
+    func randomNumber(in range: ClosedRange<Double>) -> Double {
+        return Double.random(in: range)
+    }
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Samplers/BaseSampler.swift

@@ -0,0 +1,29 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// A protocol defining the fundamental behaviour for all samplers.
+protocol BaseSampler: AnyObject {
+
+    /// Calculates a sampling decision.
+    ///
+    /// This function determines whether an item (or session) should be recorded or sampled out
+    /// based on the sampler's specific logic and configuration.
+    ///
+    /// - Returns: A `SamplingDecision` indicating whether to sample in (`.notSampledOut`)
+    ///            or sample out (`.sampledOut`).
+    func sample() -> SamplingDecision
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Samplers/Sampler Factory/AlwaysOffAgentSampler.swift

@@ -0,0 +1,46 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// An internal helper implementation of `AgentSessionSampler` that always returns `.sampledOut`.
+final class AlwaysOffAgentSampler: AgentSessionSampler {
+
+    // MARK: - Constants
+
+    let upperBound: Double = 0
+
+    let lowerBound: Double = 0
+
+    let probability: Double = 0
+
+
+    // MARK: - Configuration
+
+    /// A non-operational configuration method.
+    ///
+    /// - Parameter configuration: The agent configuration (ignored).
+    func configure(with configuration: any AgentConfigurationProtocol) {}
+
+
+    // MARK: - Sampling
+
+    /// A non-operational sampling method.
+    ///
+    /// - Returns: Always returns `.sampledOut`.
+    func sample() -> SamplingDecision {
+        return .sampledOut
+    }
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Samplers/Sampler Factory/AlwaysOnAgentSampler.swift

@@ -0,0 +1,46 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// An internal helper implementation of `AgentSessionSampler` that always returns `.notSampledOut`.
+final class AlwaysOnAgentSampler: AgentSessionSampler {
+
+    // MARK: - Constants
+
+    let probability: Double = 1.0
+
+    let upperBound: Double = 1.0
+
+    let lowerBound: Double = 0.0
+
+
+    // MARK: - Configuration
+
+    /// A non-operational configuration method.
+    ///
+    /// - Parameter configuration: The agent configuration (ignored).
+    func configure(with configuration: any AgentConfigurationProtocol) {}
+
+
+    // MARK: - Sampling
+
+    /// A non-operational sampling method.
+    ///
+    /// - Returns: Always returns `.notSampledOut`.
+    func sample() -> SamplingDecision {
+        return .notSampledOut
+    }
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Samplers/Sampler Factory/SamplerFactory.swift

@@ -0,0 +1,34 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// A factory enum providing convenient constructors for common `AgentSessionSampler` instances.
+enum SamplerFactory {
+
+    /// Creates an agent session sampler that always returns `.notSampledOut`.
+    ///
+    /// - Returns: An `AgentSessionSampler` instance.
+    static func alwaysOnSampler() -> AgentSessionSampler {
+        return AlwaysOnAgentSampler()
+    }
+
+    /// Creates an agent session sampler that always  returns `.sampledOut`.
+    ///
+    /// - Returns: An instance of `NoOpAgentSessionSampler`.
+    static func alwaysOffSampler() -> AgentSessionSampler {
+        return AlwaysOffAgentSampler()
+    }
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Samplers/StatisticalSampler.swift

@@ -0,0 +1,82 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// A protocol for samplers that calculate decisions based on statistical probability.
+protocol StatisticalSampler: BaseSampler {
+
+    /// The target probability of sampling an item.
+    var probability: Double { get }
+
+    /// The upper bound of the interval used for generating random numbers in the sampling decision.
+    var upperBound: Double { get }
+
+    /// The lower bound of the interval used for generating random numbers in the sampling decision.
+    var lowerBound: Double { get }
+}
+
+extension StatisticalSampler {
+
+    // MARK: - Default sampling function implementation
+
+    /// Provides a default sampling decision logic for statistical samplers.
+    ///
+    /// This implementation compares a randomly generated number against the sampler's `probability`.
+    /// - If `probability` is 1.0, it always returns `.notSampledOut`.
+    /// - If `probability` is 0.0, it always returns `.sampledOut`.
+    /// - Otherwise, it generates a random number within the `[lowerBound, upperBound]` range.
+    ///   If this random number is less than or equal to `probability`, it returns `.notSampledOut`, otherwise, it returns `.sampledOut`.
+    ///   For miss-configured bounds, it returns `.sampledOut`.
+    ///
+    /// - Parameter randomNumberProvider: An object conforming to `RandomNumberProvider`
+    ///   used to generate the random number. Defaults to `SystemRandomNumberProvider()`.
+    /// - Returns: A `SamplingDecision`.
+    func sample(randomNumberProvider: RandomNumberProvider = SystemRandomNumberProvider()) -> SamplingDecision {
+
+        // Filter out miss-configured bounds.
+        guard lowerBound <= upperBound, lowerBound >= 0.0, upperBound <= 1.0 else {
+            return .sampledOut
+        }
+
+        // The user-configured sampling rate is 1, meaning we want to record all Agent sessions.
+        if probability == 1.0 {
+            return .notSampledOut
+        }
+
+        // The user-configured sampling rate is 0, meaning we want to record no Agent sessions.
+        if probability == 0.0 {
+            return .sampledOut
+        }
+
+        // For any other value, we want to generate a random constant...
+        let randomNumber = randomNumberProvider.randomNumber(in: lowerBound ... upperBound)
+
+        // ... and do a bound comparison against the configured sampling rate.
+        if randomNumber <= probability {
+            return .notSampledOut
+        }
+
+        return .sampledOut
+    }
+
+    /// Calculates a sampling decision using the default system random number provider by
+    /// calling the default `sample(randomNumberProvider: RandomNumberProvider)` function.
+    ///
+    /// - Returns: A `SamplingDecision`.
+    func sample() -> SamplingDecision {
+        return sample(randomNumberProvider: SystemRandomNumberProvider())
+    }
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/SamplingDecision.swift

@@ -0,0 +1,26 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// Defines a sampling decision, calculated as the result of a `BaseSampler`'s `sample()` function call.
+enum SamplingDecision {
+
+    /// Indicates that the item/session should be sampled out.
+    case sampledOut
+
+    /// Indicates that the item/session should not be sampled out.
+    case notSampledOut
+}

SplunkAgent/Sources/SplunkAgent/Agent/Sampling/Session Sampling/AgentSessionSampler.swift

@@ -0,0 +1,28 @@
+//
+/*
+Copyright 2025 Splunk Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/// A specialized `StatisticalSampler` for agent-based session sampling.
+///
+/// It adds a mechanism to configure the sampler agent-specific session sampling rate.
+protocol AgentSessionSampler: StatisticalSampler {
+
+    /// Configures the session sampler with agent-specific configuration.
+    ///
+    /// - Parameter configuration: A `AgentConfigurationProtocol` object which provides
+    ///                           the necessary `sessionSamplingRate` configuration.
+    func configure(with configuration: any AgentConfigurationProtocol)
+}