Network requests

CxHttpClient (dart:http)

By Using CxHttpClient The RUM SDK can catch / monitor the http traffic.

  final client = CxHttpClient(http.Client());
  await client.get(Uri.parse(url));

CxDioInterceptor (Dio)

If your app uses the Dio HTTP client, add CxDioInterceptor to your Dio instance to automatically capture network requests and generate RUM spans — no migration from your existing networking layer required.

Step 1: Add dio to your pubspec.yaml:

dependencies:
  dio: ^5.7.0

Step 2: Attach the interceptor to your Dio instance:

import 'package:dio/dio.dart';
import 'package:cx_flutter_plugin/cx_dio_interceptor.dart';

final dio = Dio();
dio.interceptors.add(CxDioInterceptor());

The interceptor automatically captures for every request:

Field	Description
`url`	Full request URL
`host`	Hostname
`method`	HTTP method (GET, POST, …)
`status_code`	HTTP status code (0 on connection error)
`status_text`	HTTP status message
`duration`	Request duration in milliseconds
`http_response_body_size`	Response body size in bytes
`schema`	URL scheme (https / http)
`fragments`	URL fragment
`request_headers`	Request headers map (only when a matching `CxNetworkCaptureRule` with `reqHeaders` is configured)
`response_headers`	Response headers map (only when a matching `CxNetworkCaptureRule` with `resHeaders` is configured)
`request_payload`	Request body (only when a matching `CxNetworkCaptureRule` with `collectReqPayload: true` is configured)
`response_payload`	Response body (only when a matching `CxNetworkCaptureRule` with `collectResPayload: true` is configured)
`traceId` / `spanId`	W3C traceparent IDs (when tracing is enabled)

Failed requests are still captured as network events (status_code is 0 on a connection error), but exception text is not attached to them. To record the exception itself, catch it and call reportError — it is then reported as an error event (error_context).

W3C Traceparent injection

To automatically inject traceparent headers and correlate RUM spans with backend traces, enable traceParentInHeader in your CXExporterOptions:

var options = CXExporterOptions(
  // ...other options...
  traceParentInHeader: {
    'enable': true,
    'options': {
      'allowedTracingUrls': ['api.example.com', 'backend.example.com'],
    },
  },
);

await CxFlutterPlugin.initSdk(options);

Only requests whose host matches an entry in allowedTracingUrls receive the traceparent header.

Setting instrumentations: {'network': false} turns off the traceparent header as well as network events, whatever traceParentInHeader is set to. The session sample rate does not affect the header: a sampled-out session keeps sending it.

To keep backend correlation without reporting network events, leave network on and drop those events in a beforeSend callback instead.

Note

On the Dart layer the traceparent header is added by the SDK's HTTP wrappers, so this feature depends on them. Requests made through CxHttpClient, or through a Dio instance with CxDioInterceptor attached, carry the header. Enabling traceParentInHeader on its own does not add it to requests made with a plain http.Client or a bare Dio instance.

Network capture rules

By default, no headers or payloads are captured. Use networkCaptureConfig in CXExporterOptions to opt in to capturing headers and payloads on a per-URL basis — useful for collecting diagnostic data while keeping sensitive endpoints clean.

import 'package:cx_flutter_plugin/cx_network_capture_rule.dart';

var options = CXExporterOptions(
  // ...other options...
  networkCaptureConfig: [
    CxNetworkCaptureRule(
      urlPattern: r'.*api\.example\.com.*',
      reqHeaders: ['Accept', 'Content-Type'],
      resHeaders: ['Content-Type', 'Content-Length'],
      collectReqPayload: true,
      collectResPayload: true,
    ),
    CxNetworkCaptureRule(
      url: 'https://analytics.example.com/track',
      // No headers, no payload captured for this URL.
    ),
  ],
);

Rules are evaluated in list order — the first matching rule wins. Use url for exact matches or urlPattern (a Dart RegExp-compatible string) for pattern matches. When networkCaptureConfig is set, URLs that match no rule have their headers and payloads suppressed entirely.

Field	Type	Description
`url`	`String?`	Exact URL to match
`urlPattern`	`String?`	Regex pattern to match against the full URL
`reqHeaders`	`List<String>?`	Allowlist of request header names to capture (case-insensitive)
`resHeaders`	`List<String>?`	Allowlist of response header names to capture (case-insensitive)
`collectReqPayload`	`bool`	Capture the request body (default: `false`)
`collectResPayload`	`bool`	Capture the response body (default: `false`)

Payload size limit: Request and response bodies longer than 1024 characters are dropped entirely — not truncated. If a body exceeds the limit, request_payload / response_payload will be absent from the span.

Dart-layer vs. native-layer rules: networkCaptureConfig enriches only requests made through CxHttpClient or CxDioInterceptor. Requests intercepted by the native iOS/Android SDK (via swizzling / OkHttp) use the native-side rules configured via networkExtraConfig during initSdk.

Last updated on October 27, 2026