expo-app-metrics 58.0.0 → 58.0.2

package/.npmignore

@@ -20,3 +20,8 @@ __rsc_tests__
 # Ensure native dirs aren't excluded by root .gitignore
 !/ios
 !/android
+
+# Exclude native build output (pnpm pack ignores nested .gitignore files)
+.cxx/
+.gradle/
+/android/build/

package/CHANGELOG.md

@@ -10,6 +10,16 @@
 
 ### 💡 Others
 
+## 58.0.2 — 2026-09-15
+
+### 💡 Others
+
+- Add an internal `setNetworkTracesConfig` to gate and filter network span recording at capture time. ([#48891](https://github.com/expo/expo/pull/48891) by [@tsapeta](https://github.com/tsapeta))
+
+## 58.0.1 — 2026-09-14
+
+_This version does not introduce any user-facing changes._
+
 ## 58.0.0 — 2026-09-10
 
 ### 🛠 Breaking changes

package/android/src/main/java/expo/modules/appmetrics/AppMetricsModule.kt

@@ -16,6 +16,7 @@ import expo.modules.appmetrics.networkrequests.NetworkRequestFilter
 import expo.modules.appmetrics.networkrequests.NetworkRequestMonitor
 import expo.modules.appmetrics.networkrequests.NetworkRequestObserver
 import expo.modules.appmetrics.networkrequests.NetworkRequestPersistence
+import expo.modules.appmetrics.networkrequests.NetworkTracesConfiguration
 import expo.modules.appmetrics.logevents.Severity
 import expo.modules.appmetrics.logevents.sanitizeLogEventAttributes
 import expo.modules.appmetrics.logevents.validateDisplayName
@@ -69,8 +70,9 @@ class AppMetricsModule : Module(), UpdatesStateChangeListener {
   lateinit var mainSession: SessionSharedObject
 
   /**
-   * The span producer installed on the monitor in `OnCreate`, kept so `OnDestroy` can
-   * uninstall it when the module is torn down (a JS reload).
+   * The span producer installed on the monitor in `OnCreate`, kept so `setNetworkTracesConfig`
+   * can apply a new recording policy to the live instance and `OnDestroy` can uninstall it
+   * when the module is torn down (a JS reload).
    */
   private var networkRequestPersistence: NetworkRequestPersistence? = null
 
@@ -136,6 +138,22 @@ class AppMetricsModule : Module(), UpdatesStateChangeListener {
         GlobalAttributes.set(attributes)
       }
 
+      Function("setNetworkTracesConfig") { config: NetworkTracesConfigParam ->
+        val configuration = NetworkTracesConfiguration(
+          enabled = config.enabled,
+          hosts = config.filter?.hosts,
+          methods = config.filter?.methods
+        )
+        // Persisted before the hop, so a configure racing startup is either read from
+        // preferences by the installing producer or applied to the live one below.
+        AppMetricsPreferences.setNetworkTracesConfiguration(context, configuration)
+        scope.launch {
+          // `modulesQueue` is a single thread fed from the JS thread, so rapid calls land in
+          // order. iOS re-reads instead, because its actor hops carry no such guarantee.
+          networkRequestPersistence?.setConfiguration(configuration)
+        }
+      }
+
       OnCreate {
         sessionManager = SessionManager(context)
 
@@ -167,6 +185,7 @@ class AppMetricsModule : Module(), UpdatesStateChangeListener {
           val persistence = NetworkRequestPersistence(
             database = MetricsDatabase.getDatabase(context),
             scope = scope,
+            initialConfiguration = AppMetricsPreferences.getNetworkTracesConfiguration(context),
             sessionId = mainSession.sessionId
           )
           networkRequestPersistence = persistence
@@ -390,3 +409,13 @@ data class MetricAttributes(
   @Field val routeName: String? = null,
   @Field val params: Map<String, Any>? = null
 ) : Record
+
+/**
+ * Payload of `setNetworkTracesConfig`: the normalized `networkTraces` setting pushed down by
+ * `Observe.configure`.
+ */
+@OptimizedRecord
+data class NetworkTracesConfigParam(
+  @Field val enabled: Boolean = true,
+  @Field val filter: NetworkRequestFilter? = null
+) : Record

package/android/src/main/java/expo/modules/appmetrics/AppMetricsPreferences.kt

@@ -2,10 +2,12 @@ package expo.modules.appmetrics
 
 import android.content.Context
 import androidx.core.content.edit
+import expo.modules.appmetrics.networkrequests.NetworkTracesConfiguration
 
 private const val PREFS_NAME = "dev.expo.app-metrics"
 private const val KEY_ENVIRONMENT = "environment"
 private const val KEY_LAST_PROCESSED_EXIT_MILLIS = "lastProcessedExitMillis"
+private const val KEY_NETWORK_TRACES_CONFIGURATION = "networkTracesConfiguration"
 
 object AppMetricsPreferences {
   /**
@@ -41,4 +43,26 @@ object AppMetricsPreferences {
   fun getDefaultEnvironment(): String? {
     return if (BuildConfig.DEBUG) "development" else null
   }
+
+  /**
+   * Last-applied network traces recording policy, or the default when JS never configured one.
+   * Persisted so requests observed before the JS bundle configures the SDK (early startup, or
+   * the next launch) follow the last-known setting.
+   */
+  fun getNetworkTracesConfiguration(context: Context): NetworkTracesConfiguration {
+    val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+    val json = prefs.getString(KEY_NETWORK_TRACES_CONFIGURATION, null)
+      ?: return NetworkTracesConfiguration()
+    return NetworkTracesConfiguration.fromJson(json)
+  }
+
+  fun setNetworkTracesConfiguration(
+    context: Context,
+    configuration: NetworkTracesConfiguration
+  ) {
+    val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+    // `apply()` rather than `commit()`: this runs inline on the JS thread, and iOS persists
+    // through `UserDefaults` without a synchronous flush either.
+    prefs.edit { putString(KEY_NETWORK_TRACES_CONFIGURATION, configuration.toJson()) }
+  }
 }

package/android/src/main/java/expo/modules/appmetrics/networkrequests/NetworkRequestPersistence.kt

@@ -23,16 +23,37 @@ private const val TAG = "ExpoAppMetrics"
 class NetworkRequestPersistence(
   private val database: MetricsDatabase,
   private val scope: CoroutineScope,
+  initialConfiguration: NetworkTracesConfiguration = NetworkTracesConfiguration(),
   // A plain value rather than a provider: the id is constant for an instance, and resolving it
   // eagerly keeps the monitor's record path off module state a teardown could have invalidated.
   private val sessionId: String
 ) {
+  /**
+   * Capture-time recording policy. Volatile because the monitor reads it from OkHttp dispatcher
+   * threads while reconfigures land on the modules queue.
+   */
+  @Volatile
+  private var configuration: NetworkTracesConfiguration = initialConfiguration
+
+  /**
+   * Applies a new recording policy. Affects future requests only; rows already written stay.
+   */
+  fun setConfiguration(configuration: NetworkTracesConfiguration) {
+    this.configuration = configuration
+  }
+
   /**
    * Records one completed request as a span.
    */
   fun persist(request: NetworkRequest) {
-    // Converts and inserts on `scope`, so OkHttp dispatcher threads pay neither the URL parsing
-    // and JSON building nor the database write. Matches `persistBuffered`.
+    // Checked before dispatching: a request the policy excludes costs nothing beyond this. A
+    // `hosts` list does parse the URL here, on the dispatcher thread, which is the price of
+    // deciding before the hop.
+    if (!configuration.allows(request.url, request.method)) {
+      return
+    }
+    // Converts and inserts on `scope`, so past the gate the dispatcher threads pay neither the
+    // span building nor the database write. Matches `persistBuffered`.
     scope.launch {
       val span = request.toSpan(sessionId) ?: return@launch
       try {
@@ -60,7 +81,15 @@ class NetworkRequestPersistence(
     // with the session INSERT and crash-report processing, so converting up to 200 requests
     // there would be the most expensive place to do it.
     scope.launch {
+      // Snapshotted once, unlike `persist`, which samples the policy per request. Everything in
+      // this batch was observed before the install that triggered the drain, so one policy keeps
+      // their treatment from depending on how far the loop happened to get before a reconfigure
+      // landed.
+      val policy = configuration
       for (request in requests) {
+        if (!policy.allows(request.url, request.method)) {
+          continue
+        }
         val span = request.toSpan(sessionId) ?: continue
         try {
           database.spanDao().insert(span)

package/android/src/main/java/expo/modules/appmetrics/networkrequests/NetworkTracesConfiguration.kt

@@ -0,0 +1,67 @@
+// Copyright 2025-present 650 Industries. All rights reserved.
+
+package expo.modules.appmetrics.networkrequests
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Which network requests get recorded as spans. Unlike the dispatch-side gates, a request
+ * rejected here never reaches disk.
+ *
+ * Persisted, so requests observed before JS configures anything follow the last-applied setting.
+ * Mirrors the iOS `NetworkTracesConfiguration`, except for how a partially corrupt blob decodes:
+ * this side recovers the readable fields, while iOS falls back to the default wholesale.
+ */
+data class NetworkTracesConfiguration(
+  val enabled: Boolean = false,
+  /**
+   * Allowed hosts, compared for exact, case-insensitive equality. `null` allows every host;
+   * an empty list allows none.
+   */
+  val hosts: List<String>? = null,
+  /** Allowed HTTP methods, compared case-insensitively. `null` allows every method. */
+  val methods: List<String>? = null
+) {
+  /**
+   * Whether a request should be recorded. Matching is delegated to `NetworkRequestFilter`, so
+   * the capture gate and the JS-facing observer can't drift apart.
+   */
+  fun allows(url: String, method: String): Boolean {
+    if (!enabled) {
+      return false
+    }
+    return filter.matches(url, method)
+  }
+
+  // `persist` gates on the OkHttp dispatcher thread, before the hop to the database queue, so this
+  // is built once instead of per request. The instance is immutable, so the filter is too.
+  private val filter by lazy { NetworkRequestFilter(hosts = hosts, methods = methods) }
+
+  /** JSON form for the preferences store. */
+  fun toJson(): String {
+    val json = JSONObject()
+    json.put("enabled", enabled)
+    hosts?.let { json.put("hosts", JSONArray(it)) }
+    methods?.let { json.put("methods", JSONArray(it)) }
+    return json.toString()
+  }
+
+  companion object {
+    /** Parses the preferences-store form; a malformed blob falls back to the default policy. */
+    fun fromJson(json: String): NetworkTracesConfiguration {
+      return runCatching {
+        val obj = JSONObject(json)
+        NetworkTracesConfiguration(
+          enabled = obj.optBoolean("enabled", false),
+          hosts = obj.optJSONArray("hosts")?.let { array ->
+            List(array.length()) { index -> array.getString(index) }
+          },
+          methods = obj.optJSONArray("methods")?.let { array ->
+            List(array.length()) { index -> array.getString(index) }
+          }
+        )
+      }.getOrDefault(NetworkTracesConfiguration())
+    }
+  }
+}

package/build/module.web.d.ts

@@ -10,11 +10,12 @@ declare class ExpoAppMetricsModule extends NativeModule implements ExpoAppMetric
     markInteractive(attributes?: MetricAttributes): Promise<void>;
     logEvent(name: string, options?: LogEventOptions): void;
     setGlobalAttributes(attributes?: Record<string, LogAttributeValue> | null): void;
+    setNetworkTracesConfig(): void;
     clearStoredEntries(): Promise<void>;
     getInactiveSessions(): Promise<never[]>;
     reportError(): void;
     getMainSession(): Session;
     getForegroundSession(): Promise<null>;
 }
-declare const _default: typeof ExpoAppMetricsModule;
+declare const _default: ExpoAppMetricsModule;
 export default _default;

package/build/module.web.js

@@ -31,6 +31,7 @@ class ExpoAppMetricsModule extends NativeModule {
     async markInteractive(attributes) {}
     logEvent(name, options) {}
     setGlobalAttributes(attributes) {}
+    setNetworkTracesConfig() {}
     async clearStoredEntries() {}
     async getInactiveSessions() {
         return [];

package/build/module.web.js.map

@@ -1 +1 @@
-{"version":3,"sources":["module.web.ts"],"sourcesContent":[null],"names":["NativeModule","registerWebModule","SharedObject","NetworkRequestObserverWeb","WebSession","globalThis","expo","id","startDate","Date","toISOString","type","isActive","getEndDate","getMetrics","getLogs","addMetric","_metric","ExpoAppMetricsModule","NetworkRequestObserver","Session","mainSession","markFirstRender","markInteractive","attributes","logEvent","name","options","setGlobalAttributes","clearStoredEntries","getInactiveSessions","reportError","getMainSession","getForegroundSession"],"mappings":"AAAA,SAASA,YAAY,EAAEC,iBAAiB,EAAEC,YAAY,QAAQ,OAAO;AAerE,cAAc,UAAU;AAExB,MAAMC,kCAAkCD;AAGxC;AAEA,MAAME,mBAAmBC,WAAWC,IAAI,CAACJ,YAAY;;IAC1CK,KAAK,cAAc;IACnBC,YAAY,IAAIC,OAAOC,WAAW,GAAG;IAE9C,YAAY,AAASC,OAAoB,MAAM,CAAE;QAC/C,KAAK,SADcA,OAAAA;IAErB;IAEA,MAAMC,WAA6B;QACjC,OAAO;IACT;IACA,MAAMC,aAAqC;QACzC,OAAO;IACT;IACA,MAAMC,aAAgC;QACpC,OAAO,EAAE;IACX;IACA,MAAMC,UAAgC;QACpC,OAAO,EAAE;IACX;IACA,MAAMC,UAAUC,OAAoB,EAAiB,CAAC;AACxD;AAEA,MAAMC,6BAA6BlB;IACjCmB,yBACEhB,0BAA2F;IAC7FiB,UAAUhB,WAAwC;IAE1CiB,cAAiC,KAAK;IAE9C,MAAMC,kBAAkB,CAAC;IACzB,MAAMC,gBAAgBC,UAA6B,EAAE,CAAC;IACtDC,SAASC,IAAY,EAAEC,OAAyB,EAAE,CAAC;IACnDC,oBAAoBJ,UAAqD,EAAE,CAAC;IAC5E,MAAMK,qBAAqB,CAAC;IAC5B,MAAMC,sBAAsB;QAC1B,OAAO,EAAE;IACX;IACAC,cAAc,CAAC;IACfC,iBAA0B;QACxB,IAAI,CAACX,WAAW,KAAK,IAAIjB,WAAW;QACpC,OAAO,IAAI,CAACiB,WAAW;IACzB;IACA,MAAMY,uBAAuB;QAC3B,OAAO;IACT;AACF;AAEA,eAAehC,kBAAkBiB,sBAAsB,kBAAkB"}
+{"version":3,"sources":["module.web.ts"],"sourcesContent":[null],"names":["NativeModule","registerWebModule","SharedObject","NetworkRequestObserverWeb","WebSession","globalThis","expo","id","startDate","Date","toISOString","type","isActive","getEndDate","getMetrics","getLogs","addMetric","_metric","ExpoAppMetricsModule","NetworkRequestObserver","Session","mainSession","markFirstRender","markInteractive","attributes","logEvent","name","options","setGlobalAttributes","setNetworkTracesConfig","clearStoredEntries","getInactiveSessions","reportError","getMainSession","getForegroundSession"],"mappings":"AAAA,SAASA,YAAY,EAAEC,iBAAiB,EAAEC,YAAY,QAAQ,OAAO;AAerE,cAAc,UAAU;AAExB,MAAMC,kCAAkCD;AAGxC;AAEA,MAAME,mBAAmBC,WAAWC,IAAI,CAACJ,YAAY;;IAC1CK,KAAK,cAAc;IACnBC,YAAY,IAAIC,OAAOC,WAAW,GAAG;IAE9C,YAAY,AAASC,OAAoB,MAAM,CAAE;QAC/C,KAAK,SADcA,OAAAA;IAErB;IAEA,MAAMC,WAA6B;QACjC,OAAO;IACT;IACA,MAAMC,aAAqC;QACzC,OAAO;IACT;IACA,MAAMC,aAAgC;QACpC,OAAO,EAAE;IACX;IACA,MAAMC,UAAgC;QACpC,OAAO,EAAE;IACX;IACA,MAAMC,UAAUC,OAAoB,EAAiB,CAAC;AACxD;AAEA,MAAMC,6BAA6BlB;IACjCmB,yBACEhB,0BAA2F;IAC7FiB,UAAUhB,WAAwC;IAE1CiB,cAAiC,KAAK;IAE9C,MAAMC,kBAAkB,CAAC;IACzB,MAAMC,gBAAgBC,UAA6B,EAAE,CAAC;IACtDC,SAASC,IAAY,EAAEC,OAAyB,EAAE,CAAC;IACnDC,oBAAoBJ,UAAqD,EAAE,CAAC;IAC5EK,yBAAyB,CAAC;IAC1B,MAAMC,qBAAqB,CAAC;IAC5B,MAAMC,sBAAsB;QAC1B,OAAO,EAAE;IACX;IACAC,cAAc,CAAC;IACfC,iBAA0B;QACxB,IAAI,CAACZ,WAAW,KAAK,IAAIjB,WAAW;QACpC,OAAO,IAAI,CAACiB,WAAW;IACzB;IACA,MAAMa,uBAAuB;QAC3B,OAAO;IACT;AACF;AAEA,eAAejC,kBAAkBiB,sBAAsB,kBAAkB"}

package/build/types.d.ts

@@ -470,6 +470,20 @@ export type DebugSession = {
     /** Crash report attached to the session, if any. */
     crashReport?: CrashReport | null;
 };
+/**
+ * Normalized form of `Observe.configure({ networkTraces })`, persisted natively.
+ * @hidden
+ */
+export type NetworkTracesConfig = {
+    /**
+     * Whether completed network requests are written to the local `spans` table.
+     */
+    enabled: boolean;
+    /**
+     * Only requests matching the filter are recorded. An omitted filter records every request.
+     */
+    filter?: NetworkRequestFilter | null;
+};
 export interface ExpoAppMetricsModuleType {
     markFirstRender(): void;
     markInteractive(attributes?: MetricAttributes): void;
@@ -484,6 +498,12 @@ export interface ExpoAppMetricsModuleType {
      * @param options Optional body, attributes, and severity overrides.
      */
     logEvent(name: string, options?: LogEventOptions): void;
+    /**
+     * Applies and persists the network traces recording setting. Affects future captures only;
+     * spans already written keep dispatching.
+     * @hidden
+     */
+    setNetworkTracesConfig(config: NetworkTracesConfig): void;
     /**
      * Sets attributes merged into every subsequent metric and log event.
      * Per-record keys win on collision. Pass `null`, `undefined`, or an empty

package/build/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["types.ts"],"sourcesContent":[null],"names":[],"mappings":"AAufA,WAkHC"}
+{"version":3,"sources":["types.ts"],"sourcesContent":[null],"names":[],"mappings":"AAsgBA,WAwHC"}

package/expo-module.config.json

@@ -9,7 +9,7 @@
     "publication": {
       "groupId": "expo.modules.appmetrics",
       "artifactId": "expo.modules.appmetrics",
-      "version": "58.0.0",
+      "version": "58.0.2",
       "repository": "local-maven-repo"
     }
   }

package/ios/AppMetricsAppDelegateSubscriber.swift

@@ -14,7 +14,12 @@ public class AppMetricsAppDelegateSubscriber: ExpoAppDelegateSubscriber {
       // From here on every completed request is written to the database, attributed to the main
       // session. The session's row INSERT was enqueued on the actor when `mainSession` was first
       // touched above, so it lands before any request row that references it.
-      NetworkRequestMonitor.shared.persistence = NetworkRequestPersistence(database: AppMetrics.database) {
+      // The persisted recording policy applies from the first observed request; JS can replace
+      // it later via `setNetworkTracesConfig`, affecting subsequent requests only.
+      NetworkRequestMonitor.shared.persistence = NetworkRequestPersistence(
+        database: AppMetrics.database,
+        configuration: AppMetricsUserDefaults.networkTracesConfiguration ?? NetworkTracesConfiguration()
+      ) {
         return AppMetrics.mainSession.id
       }
     }

package/ios/AppMetricsModule.swift

@@ -64,6 +64,23 @@ public final class AppMetricsModule: Module, UpdatesStateChangeListener {
       GlobalAttributes.set(attributes)
     }
 
+    Function("setNetworkTracesConfig") { (config: NetworkTracesConfigParam) in
+      let configuration = NetworkTracesConfiguration(
+        enabled: config.enabled,
+        hosts: config.filter?.hosts,
+        methods: config.filter?.methods
+      )
+      // Persisted before the hop, so a configure racing startup is either read from
+      // `UserDefaults` by the installing producer or applied to the live one below.
+      AppMetricsUserDefaults.networkTracesConfiguration = configuration
+      AppMetricsActor.isolated {
+        // Re-read rather than captured: actor hops are unordered, so two rapid calls could
+        // otherwise apply out of order. Android captures, since its queue is a single thread.
+        let latest = AppMetricsUserDefaults.networkTracesConfiguration ?? NetworkTracesConfiguration()
+        NetworkRequestMonitor.shared.persistence?.setConfiguration(latest)
+      }
+    }
+
     AsyncFunction("getAppStartupTimesAsync") {
       return await AppMetrics.mainSession.appStartupMonitor.metrics
     }
@@ -195,6 +212,14 @@ private func storedSession(id: String) throws -> StoredSession? {
   return StoredSession(from: row)
 }
 
+/// Payload of `setNetworkTracesConfig`: the normalized `networkTraces` setting pushed down by
+/// `Observe.configure`.
+@Record
+internal struct NetworkTracesConfigParam {
+  var enabled: Bool = true
+  var filter: NetworkRequestFilter?
+}
+
 struct MetricAttributes: Record {
   @Field var routeName: String?
   @Field var params: [String: Any]?

package/ios/AppMetricsUserDefaults.swift

@@ -8,6 +8,7 @@ public final class AppMetricsUserDefaults: UserDefaults {
   private enum Keys: String {
     case lastAppLaunchState
     case environment
+    case networkTracesConfiguration
   }
 
   private init() {
@@ -41,4 +42,15 @@ public final class AppMetricsUserDefaults: UserDefaults {
       defaults.set(codable: newValue, forKey: Keys.lastAppLaunchState.rawValue)
     }
   }
+
+  /// Last-applied network traces policy, or `nil` when JS never configured one. Persisted so
+  /// early-startup requests follow the last-known setting.
+  static var networkTracesConfiguration: NetworkTracesConfiguration? {
+    get {
+      return defaults.codable(forKey: Keys.networkTracesConfiguration.rawValue, as: NetworkTracesConfiguration.self)
+    }
+    set {
+      defaults.set(codable: newValue, forKey: Keys.networkTracesConfiguration.rawValue)
+    }
+  }
 }

package/ios/NetworkRequests/NetworkRequestFilter.swift

@@ -15,13 +15,10 @@ import Foundation
 /// unset places no constraint on its dimension, while a field set to an empty array allows nothing
 /// through it (an empty allow-list matches no value), so any empty field drops every request. A
 /// filter with no fields set matches every request, matching the no-filter default.
-public struct NetworkRequestFilter: Record, Sendable {
-  public init() {}
-
-  @Field
+@Record
+public struct NetworkRequestFilter: Sendable {
   public var hosts: [String]?
 
-  @Field
   public var methods: [String]?
 
   /// Returns whether a request with the given URL and method passes this filter. Host and method

package/ios/NetworkRequests/NetworkRequestPersistence.swift

@@ -15,13 +15,28 @@ final class NetworkRequestPersistence: Sendable {
   /// the app delegate finished wiring it.
   private let sessionId: @Sendable () -> String
 
-  init(database: MetricsDatabase?, sessionId: @escaping @Sendable () -> String) {
+  private var configuration: NetworkTracesConfiguration
+
+  init(
+    database: MetricsDatabase?,
+    configuration: NetworkTracesConfiguration = NetworkTracesConfiguration(),
+    sessionId: @escaping @Sendable () -> String
+  ) {
     self.database = database
+    self.configuration = configuration
     self.sessionId = sessionId
   }
 
+  /// Applies a new recording policy. Affects future requests only; rows already written stay.
+  func setConfiguration(_ configuration: NetworkTracesConfiguration) {
+    self.configuration = configuration
+  }
+
   /// Records one completed request as a span.
   func persist(_ request: NetworkRequest) {
+    guard configuration.allows(url: request.url, method: request.method) else {
+      return
+    }
     guard let database, let row = SpanRow.from(request: request, sessionId: sessionId()) else {
       return
     }

package/ios/NetworkRequests/NetworkTracesConfiguration.swift

@@ -0,0 +1,27 @@
+// Copyright 2025-present 650 Industries. All rights reserved.
+
+import Foundation
+
+/// Which network requests get recorded as spans. Unlike the dispatch-side gates, a request
+/// rejected here never reaches disk.
+///
+/// Persisted, so requests observed before JS configures anything follow the last-applied setting.
+internal struct NetworkTracesConfiguration: Codable, Sendable {
+  var enabled: Bool = false
+
+  /// Allowed hosts, compared for exact, case-insensitive equality. `nil` allows every host;
+  /// an empty array allows none.
+  var hosts: [String]?
+
+  /// Allowed HTTP methods, compared case-insensitively. `nil` allows every method.
+  var methods: [String]?
+
+  /// Whether a request should be recorded. Matching is delegated to `NetworkRequestFilter`, so the
+  /// capture gate and the JS-facing observer can't drift apart.
+  func allows(url: URL, method: String) -> Bool {
+    guard enabled else {
+      return false
+    }
+    return NetworkRequestFilter(hosts: hosts, methods: methods).matches(url: url, method: method)
+  }
+}

package/ios/Tests/NetworkRequestPersistenceTests.swift

@@ -458,11 +458,66 @@ struct NetworkRequestPersistenceTests {
     )
   }
 
+  @Test
+  func `drops every request while recording is disabled`() throws {
+    try withTemporaryDatabase { database in
+      try insertSession(id: "s", into: database)
+      let persistence = NetworkRequestPersistence(
+        database: database,
+        configuration: NetworkTracesConfiguration(enabled: false)
+      ) {
+        return "s"
+      }
+      persistence.persist(makeRequest())
+      #expect(try database.getSpans(afterId: -1).isEmpty)
+    }
+  }
+
+  @Test
+  func `records only requests matching the configured filter`() throws {
+    try withTemporaryDatabase { database in
+      try insertSession(id: "s", into: database)
+      let persistence = NetworkRequestPersistence(
+        database: database,
+        configuration: NetworkTracesConfiguration(enabled: true, hosts: ["API.myapp.com"], methods: nil)
+      ) {
+        return "s"
+      }
+      persistence.persist(makeRequest(url: "https://api.example.com/skip"))
+      persistence.persist(makeRequest(url: "https://api.myapp.com/keep"))
+      let rows = try database.getSpans(afterId: -1)
+      #expect(rows.count == 1)
+      let attributes = try attributesDict(#require(rows.first))
+      #expect(attributes["url.full"] as? String == "https://api.myapp.com/keep")
+    }
+  }
+
+  @Test
+  func `applies a configuration change to subsequent requests only`() throws {
+    // "Applies forward": rows persisted before the change stay in the table and still dispatch.
+    try withTemporaryDatabase { database in
+      try insertSession(id: "s", into: database)
+      let persistence = NetworkRequestPersistence(
+        database: database,
+        configuration: NetworkTracesConfiguration(enabled: true)
+      ) {
+        return "s"
+      }
+      persistence.persist(makeRequest())
+      persistence.setConfiguration(NetworkTracesConfiguration(enabled: false))
+      persistence.persist(makeRequest())
+      #expect(try database.getSpans(afterId: -1).count == 1)
+    }
+  }
+
   @Test
   func `persists a completed request as a span attributed to the provided session`() throws {
     try withTemporaryDatabase { database in
       try insertSession(id: "main-session", into: database)
-      let persistence = NetworkRequestPersistence(database: database) {
+      let persistence = NetworkRequestPersistence(
+        database: database,
+        configuration: NetworkTracesConfiguration(enabled: true)
+      ) {
         return "main-session"
       }
       persistence.persist(makeRequest())
@@ -479,7 +534,10 @@ struct NetworkRequestPersistenceTests {
     try withTemporaryDatabase { database in
       try insertSession(id: "main-session", into: database)
       let monitor = NetworkRequestMonitor()
-      monitor.persistence = NetworkRequestPersistence(database: database) {
+      monitor.persistence = NetworkRequestPersistence(
+        database: database,
+        configuration: NetworkTracesConfiguration(enabled: true)
+      ) {
         return "main-session"
       }
       monitor.record(makeRequest(method: "GET"))
@@ -494,7 +552,10 @@ struct NetworkRequestPersistenceTests {
     // The sessions FK protects referential integrity; persistence must degrade to a dropped
     // row rather than throw into the monitor's record path.
     try withTemporaryDatabase { database in
-      let persistence = NetworkRequestPersistence(database: database) {
+      let persistence = NetworkRequestPersistence(
+        database: database,
+        configuration: NetworkTracesConfiguration(enabled: true)
+      ) {
         return "never-inserted"
       }
       persistence.persist(makeRequest())