debug_kit_dio 0.6.2

Dio network logging adapter for DebugKit. Automatically logs requests, responses, and errors with sanitization.

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.

Links

• DebugKit Core
• Example App
• Package Example

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