Network requests

Open in ChatGPTOpen in Claude

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 will receive the traceparent header.

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.