DebugKit Dio Adapter

A Dio network logging adapter for DebugKit.

Automatically logs Dio network requests, responses, and errors into the DebugKit in-app console with sanitization and lifecycle tracking.

Installation

Add both debug_kit and debug_kit_dio to your pubspec.yaml:

dependencies:
  debug_kit: ^0.11.2
  debug_kit_dio: ^0.6.2

Setup

Initialize DebugKit and pass a DebugKitDioAdapter in the adapters list:

import 'package:dio/dio.dart';
import 'package:debug_kit/debug_kit.dart';
import 'package:debug_kit_dio/debug_kit_dio.dart';

void main() {
  final dio = Dio();

  DebugKit.init(
    enabled: true,
    adapters: [
      DebugKitDioAdapter(dio),
    ],
  );

  runApp(const MyApp());
}

Alternatively, add the interceptor directly to an existing Dio instance:

dio.interceptors.add(DebugKitDioInterceptor(DebugKit.controller));

What is Logged

  • HTTP method plus sanitized URL, host, path, and query metadata
  • Request and response phase updates for the Network Inspector
  • Response status code, duration, and error metadata
  • Backend correlation IDs from allowlisted response headers only
  • Cancelled request status
  • Optional sanitized request/response header previews when enabled
  • Optional request/response body previews when explicitly enabled
  • Pretty-printed JSON previews when prettyPrintJson: true
  • Gzip-decoded previews when decodeGzipBodies: true

The adapter also feeds the DebugKit Network Inspector with the request list, summary strip, detail tabs, and waterfall timing.

DebugKit's console format setting still controls how these Dio-generated summaries are rendered, but it does not shorten developer-authored app logs.

What is NOT Logged

  • Request bodies — never logged by default
  • Response bodies — never logged by default
  • Binary or multipart payloads — always ignored
  • Authorization, Cookie, Set-Cookie, or arbitrary response headers — not stored by default
  • Raw backend headers outside the allowlist below

Security & Sanitization

  • URLs: Sensitive query parameters (e.g., api_key, token, password) are masked using smart length-aware masking.
  • Response headers: Only the allowlisted backend correlation headers below are captured, and values are sanitized and truncated to 64 characters.
  • Headers: request header previews are opt-in and sanitized; response header previews use a safe allowlist only.
  • Bodies: request and response body previews are opt-in and disabled by default.
  • All previews honor the core DebugKitSanitizerConfig passed to DebugKit.init().

Preview Config

Use DebugKitDioConfig when you want safe previews in the Network Inspector:

DebugKit.init(
  adapters: [
    DebugKitDioAdapter(
      dio,
      config: const DebugKitDioConfig(
        captureRequestHeaders: true,
        captureResponseHeaders: true,
        captureRequestBody: false,
        captureResponseBody: false,
        prettyPrintJson: true,
        decodeGzipBodies: true,
      ),
    ),
  ],
);

Console Lifecycle

By default, each request prints two Flutter console lines: a started line on request, and a final result line on response/error. Use networkConsoleLifecycleMode to reduce noise for frequent endpoints — the in-app Network tab always records the full lifecycle regardless of this setting.

dio.interceptors.add(
  DebugKitDioInterceptor(
    DebugKit.controller,
    config: const DebugKitDioConfig(
      networkConsoleLifecycleMode:
          DebugKitNetworkConsoleLifecycleMode.finalOnly,
    ),
  ),
);
  • startAndFinish (default): prints started + final result. Prior behavior.
  • finalOnly: prints only one final success/error line per request.
  • none: no console output for network requests; Network tab only.

Defaults stay safe:

  • captureRequestHeaders: false
  • captureResponseHeaders: false
  • captureRequestBody: false
  • captureResponseBody: false
  • prettyPrintJson: false
  • decodeGzipBodies: false
  • maxBodyPreviewChars: 1000
  • maxBodyBytes: 65536

Allowlisted backend correlation headers

  • x-request-id and request-id → backendRequestId
  • x-correlation-id → backendCorrelationId
  • x-trace-id and trace-id → backendTraceId

Performance

Zero overhead when DebugKit is disabled (enabled: false). The interceptor checks the enabled flag synchronously before any work and never blocks the Dio handler chain.

Limitations

  • Request and response bodies are preview-only and opt-in. The adapter never stores raw payloads.
  • Binary and multipart payloads are always ignored.

Compatibility

debug_kit_dio debug_kit
0.6.2 ^0.11.2
0.6.1 ^0.11.0
0.6.0 ^0.11.0

License

MIT

Libraries

debug_kit_dio
Dio adapter for DebugKit network logging.