ispect library

Classes

AnsiPen
Pen attributes for foreground and background colors.
BaseLogsFile
Abstract base class for cross-platform log file operations.
BaseNetworkInterceptorSettings
Base settings class for network interceptors (Dio, HTTP, etc.).
BaseNetworkInterceptorSettingsBuilder<B extends BaseNetworkInterceptorSettingsBuilder<B, TReq, TRes, TErr>, TReq, TRes, TErr>
Base builder for network interceptor settings.
CategoryFilter
Matches logs whose TraceKeys.category is in categories.
CompositeRedactionStrategy
Runs multiple strategies in order and returns the first redaction result.
ConsoleSettings
Configuration settings for ISpectLogger logger.
ConsoleUtils
Static helpers for console output: border lines and ANSI color mapping.
CorrelationFilter
Matches logs with a specific TraceKeys.correlationId.
CurlUtils
Utility class for generating cURL commands from HTTP request data.
DefaultISpectLoggerHistory
In-memory ILogHistory backed by a ListQueue.
DraggablePanel
DraggablePanel is a widget that can be dragged around the screen and can be docked to the nearest edge of the screen. It can be used to create a floating panel that can be used to show additional information or actions.
DraggablePanelButtonItem
Represents a button item in the draggable panel.
DraggablePanelController
A controller to manage the state and behavior of a draggable panel.
DraggablePanelItem
Represents an item in the draggable panel.
DraggablePanelTheme
Defines the visual properties of a DraggablePanel.
ExtendedLoggerFormatter
Renders single-line logs verbatim and indents continuation lines of multi-line payloads (e.g. network curl dumps, JSON bodies).
FakeISpectLogger
Test double for ISpectLogger. Captures all logs for assertions.
FileLogHistory
Extended ILogHistory with daily file-based persistence.
Filter<T>
A generic filter that checks whether a given item satisfies certain conditions. Used as a building block for more specific filter types.
HeaderRedactionResult
The outcome of a header redaction operation.
HttpMethodFilter<T>
Passes only events whose HTTP method is in allowedMethods.
HumanLogEntryFormatter
Human-readable, grep-friendly console output.
ILogEntryFormatter
Renders a full ISpectLogData entry into a console-ready string.
ILoggerFilter
Determines whether a log message should be recorded based on its content and log level.
ILoggerFormatter
Converts LogDetails into a formatted string for console output.
ILogHistory
Contract for log history storage.
InspectorPlugin
Base class for ISpect inspector plugins.
ISpect
The main entry point for initializing and managing logging/error handling.
ISpectActionItem
Describes a tappable action shown inside the ISpect inspector panel (e.g. in the custom-actions grid).
ISpectBaseLogger
Console logger: formats messages via ILoggerFormatter and writes them through a LoggerOutput function.
ISpectBuilder
A widget that wraps your app with ISpect debugging tools.
ISpectColumnBuilder
A Column whose children are produced lazily from an IndexedWidgetBuilder, mirroring the API of ListView.builder but without a scroll view.
ISpectDateTimeFormatter
A utility class for formatting DateTime objects into readable strings.
ISpectDynamicColor
ISpectErrorHandler
A utility class for handling errors and exceptions in ISpectLogger.
ISpectErrorHandlerOptions
Options for configuring how ISpect installs error/log handlers in the running app.
ISpectFileUtils
A utility class for file-related operations on Web platforms.
ISpectFilter
Composite filter combining log-type-key, runtime type, and search criteria.
ISpectGeneratedLocalization
Callers can lookup localized strings with an instance of ISpectGeneratedLocalization returned by ISpectGeneratedLocalization.of(context).
ISpectLocalization
Localization class which is used to localize app. This class provides handy methods and tools.
ISpectLocalizations
Localization helper for ISpect.
ISpectLogData
Core log entry model. All fields are immutable after construction.
ISpectLogDataJsonUtils
Utility class for ISpectLogData JSON operations.
ISpectLogError
Log entry produced when a Dart Error is captured by the logger.
ISpectLogException
Log entry produced when a Dart Exception is captured by the logger.
ISpectLogger
Customizable logging and inspection utility for mobile applications.
ISpectLoggerOptions
Configuration for ISpectLogger behavior. Per-type colors can be overridden via customColors; defaults come from the ISpectLogType registry.
ISpectLogType
Describes a log type — built-in or user-defined.
ISpectNavigatorObserver
A custom NavigatorObserver for logging navigation events.
ISpectObserver
Observer for monitoring ISpectLogger events.
ISpectOptions
A configuration class for ISpect, defining various options including locale settings, feature toggles, action items, and panel configurations.
ISpectPanelButtonItem
A labelled button displayed in the ISpect expanded panel menu.
ISpectPanelItem
An item displayed in the ISpect floating panel.
ISpectScopeController
Provides the ISpectScopeModel to the widget tree.
ISpectScopeModel
A model class that holds the state of the ISpect scope.
ISpectSelector<T>
Rebuilds builder only when the value returned by selector changes.
ISpectSettingsState
Snapshot of every runtime-configurable ISpect setting exposed in the Settings sheet. Serialized via toJson and restored on app restart through ISpectOptions.initialSettings.
ISpectShareRequest
Describes content to pass into a custom share handler.
ISpectTheme
Defines the theme configuration for ISpect, including colors, icons, and log descriptions.
ISpectToaster
A utility class for displaying various types of toast notifications using SnackBar.
ISpectTraceCategory
Defines a trace category for grouping related log entries.
ISpectTraceConfig
Base configuration for trace operations.
ISpectTraceToken
Token returned by traceStart for manual span timing.
JsonScreen
JsonTruncator
Pretty-prints JSON objects with depth and size limits.
KeyBasedRedaction
Redacts values based on key names: fully-masked keys and sensitive keys.
LogDetails
LogExporter
Utility class for batch export of log data.
LogLevelRangeFilter
Filters logs by a LogLevel range (inclusive).
LogsFileFactory
Factory class for creating platform-appropriate log file handlers.
LogsJsonService
Service for managing JSON export/import operations for logs.
LogTypeKeyFilter
Matches ISpectLogData items whose ISpectLogData.key is in keys.
NativeLogsFile
Native platform implementation for log file operations.
NetworkFilter<T>
Base class for network filter chain units.
NetworkFilterChain<T>
Immutable, ordered chain of NetworkFilters with short-circuit evaluation.
NetworkJsonKeys
Canonical JSON key names used across all network interceptor packages.
NetworkLogPrintOptions
Abstraction describing print preferences and color configuration for network-related logs.
NetworkLogRenderer
Builds the verbose body section (status / payload / headers / error info) of a network log entry from its ISpectLogData.additionalData.
NetworkMapRedactor
Standard redaction pipeline for network toJson() maps.
NetworkPayloadSanitizer
Provides reusable sanitization helpers for network payloads.
NetworkTransaction
Groups a correlated HTTP request with its response or error.
PatternBasedRedaction
Redacts values based on content patterns (tokens, JWTs, base64, binary).
RedactionContext
Provides redaction helpers and configuration to strategies at call-time.
RedactionResult
The outcome of a redaction operation: the redacted data and statistics about what was redacted.
RedactionService
A configurable service that redacts sensitive values in headers and payloads.
RedactionStats
Lightweight counters tracking what a single redaction traversal redacted.
RedactionStrategy
Redaction strategy interface.
SamplingFilter<T>
Logs only every sampleRate-th event (1-based counting).
SearchFilter
Case-insensitive search across all fields of ISpectLogData, including nested ISpectLogData.additionalData.
SessionStatistics
Snapshot of session metrics and configuration.
SourceFilter
Matches logs whose TraceKeys.source is in sources.
StatusCodeFilter<T>
Passes only events whose HTTP status code satisfies predicate.
TraceCategoryIds
Single source of truth for category ID strings.
TraceKeys
Top-level keys in ISpectLogData.additionalData for trace envelope.
TransactionFilter
Matches logs with a specific TraceKeys.transactionId.
TypeFilter
Matches ISpectLogData items whose runtime type is in types.
UrlExclusionFilter<T>
Suppresses logging for URLs matching any of excludedPatterns.
WebLogsFile
Web platform implementation for log file operations.

Enums

LogLevel
SessionCleanupStrategy
Strategy for cleaning up old log files when session limit is exceeded.

Mixins

BaseNetworkInterceptor
Facade mixin combining NetworkLoggerMixin, NetworkRedactionMixin, and NetworkConfigurationMixin for backward compatibility.
NetworkConfigurationMixin
Mixin providing runtime reconfiguration for network interceptors.
NetworkLoggerMixin
Mixin providing core logging utilities for network interceptors.
NetworkRedactionMixin
Mixin providing redaction utilities for network interceptors.

Extensions

HistoryListFlutterText on List<ISpectLogData>
Extension on List<ISpectLogData> to format history text output.
ISpectDataX on ISpectLogData
Utility extensions on ISpectLogData: copy, formatting, cURL generation.
ISpectFlutter on ISpectLogger
Extension on ISpectLogger for Flutter-specific configurations.
ISpectLogDataSerialization on ISpectLogData
Extension for ISpectLogData to add serialization support.
ISpectLogDataX on ISpectLogData
Convenience getters for accessing structured trace data in ISpectLogData.
ISpectLoggerAnalytics on ISpectLogger
Trace helpers for analytics events (screen views, product impressions, etc.).
ISpectLoggerAuth on ISpectLogger
Trace helpers for authentication flows (sign-in, sign-out, refresh, etc.).
ISpectLoggerBloc on ISpectLogger
Trace helpers for BLoC / Cubit lifecycle events.
ISpectLoggerGraphQL on ISpectLogger
Trace helpers for GraphQL queries, mutations, and subscriptions.
ISpectLoggerGrpc on ISpectLogger
Trace helpers for gRPC calls.
ISpectLoggerNavigation on ISpectLogger
Trace helpers for Navigator / router transitions.
ISpectLoggerNetwork on ISpectLogger
Trace helpers for raw HTTP request / response / error events.
ISpectLoggerPayment on ISpectLogger
Trace helpers for payment and in-app purchase flows.
ISpectLoggerPerformance on ISpectLogger
Trace helpers for runtime performance signals (frame jank, slow work).
ISpectLoggerPush on ISpectLogger
Trace helpers for push / remote notifications.
ISpectLoggerRiverpod on ISpectLogger
Trace helpers for Riverpod provider lifecycle events.
ISpectLoggerSSE on ISpectLogger
Trace helpers for Server-Sent Events (SSE) streams.
ISpectLoggerState on ISpectLogger
Trace helpers for state-management layers (BLoC, Cubit, Riverpod, etc.).
ISpectLoggerStorage on ISpectLogger
Trace helpers for object-storage / file-storage operations (S3, Firebase Storage, local fs, etc.).
ISpectLoggerWs on ISpectLogger
Trace helpers for WebSocket send / receive events.
ISpectStringExtension on String?
An extension on nullable String providing truncation.
ISpectTrace on ISpectLogger
LogLevelX on LogLevel
SafeLogExtension on ISpectLogger
Extension on ISpectLogger providing safe logging helpers.
StringBufferExtension on StringBuffer
Extension on StringBuffer to conditionally write a line.

Constants

ansi_default → const String
ansi_esc → const String
ansiDefault → const String
Reset all colors and options for current SGRs to terminal defaults.
ansiEscape → const String
ANSI Control Sequence Introducer, signals the terminal for new settings.
ansiResetBackground → const String
Ansi codes that default the terminal's background color without altering the foreground, when printed.
ansiResetForeground → const String
Ansi codes that default the terminal's foreground color without altering the background, when printed.
conversionFailedPlaceholder → const String
Placeholder used when map/data conversion fails during sanitization.
cookieHeaderKey → const String
Header key name requiring special cookie-aware masking (case-insensitive comparison by caller).
defaultFullyMaskedKeys → const Set<String>
Keys whose values are always fully replaced with placeholder (no partial masking), regardless of whether the key is also in defaultSensitiveKeys.
defaultPlaceholder → const String
Default placeholder text substituted for redacted values.
defaultSensitiveKeys → const Set<String>
The canonical set of sensitive key names used for redaction across all ispect packages. This is the single source of truth — other packages (e.g. ispectify_db) reference this constant instead of maintaining their own lists.
kDefaultLogTruncateLength → const int
Mirrors ISpectLoggerOptions.logTruncateLength default (kDefaultStringTruncateLimit).
kDefaultMaxHistoryItems → const int
Mirrors ISpectLoggerOptions.maxHistoryItems default.
kDefaultSensitiveKeys → const Set<String>
Backward-compatible alias for defaultSensitiveKeys.
kDefaultStackFrameLimit → const int
Default maximum stack frames passed to the console logger.
kDefaultStringTruncateLimit → const int
Default truncation limit for strings across the package.
kISpectEnabled → const bool
Compile-time constant to enable/disable ISpect via --dart-define.
redactedMask → const String
Short mask used for key-based redaction (e.g. passwords, tokens).
redactionFailedPlaceholder → const String
Placeholder returned when redaction itself throws an exception.
userInfoRedactedPlaceholder → const String
URI-safe placeholder for redacted userInfo (username:password) in URLs.

Properties

analyticsCategory → ISpectTraceCategory
NB: analytics uses one key for success and error. Intentional — analytics events rarely have distinct error types.
final
ansiColorDisabled ↔ bool
Globally enable or disable AnsiPen settings.
getter/setter pair
ansiEscapePattern → RegExp
Matches standard ANSI SGR / cursor escape sequences.
final
authCategory → ISpectTraceCategory
final
base64Regex → RegExp
Characters valid in standard or URL-safe Base64.
final
color_disabled ↔ bool
getter/setter pair
dbCategory → ISpectTraceCategory
final
defaultSensitiveKeyPatterns → List<RegExp>
Regex patterns that match sensitive key name fragments.
final
graphqlCategory → ISpectTraceCategory
final
grpcCategory → ISpectTraceCategory
final
jwtRegex → RegExp
JSON Web Token (three dot-separated Base64URL segments).
final
NB: navigation — route push and pop are linked via correlationId.
final
networkCategory → ISpectTraceCategory
Predefined trace categories for built-in domains.
final
paymentCategory → ISpectTraceCategory
final
performanceCategory → ISpectTraceCategory
final
pushCategory → ISpectTraceCategory
final
schemeRegex → RegExp
HTTP authentication scheme prefixes (Bearer, Basic, Digest, etc.).
final
sseCategory → ISpectTraceCategory
final
stateCategory → ISpectTraceCategory
final
storageCategory → ISpectTraceCategory
final
tokenPrefixRegex → RegExp
Well-known token prefixes from popular services.
final
urlPattern → RegExp
HTTP(S) URLs embedded in free-form text (error messages, logs, etc.).
final
whitespaceRegex → RegExp
Any whitespace character (used to sanitize before Base64 checks).
final
wsCategory → ISpectTraceCategory
final

Functions

base64Placeholder(int length) → String
Placeholder for redacted Base64-encoded data, showing approximate length.
binaryPlaceholder(int length) → String
Placeholder for redacted binary data, preserving the original byte count.
cleanMap(Map<String, Object?> map) → Map<String, Object?>
Removes entries with null values or empty-string values from map.
containsAnsi(String value) → bool
Returns true if value contains any ANSI escape sequence.
debugCheckHasISpectAppLocalizations(BuildContext context) → bool
formatBytes(int bytes) → String
Formats a byte count as a human-readable string (B, KB, MB, GB).
generateTraceId() → String
Generates a 16-character hex trace ID from the current timestamp and a random component.
lookupISpectGeneratedLocalization(Locale locale) → ISpectGeneratedLocalization
normalizeStackTrace(StackTrace? stackTrace) → StackTrace?
Returns stackTrace as-is unless it is null or StackTrace.empty, in which case null is returned.
resetBackground() → String
resetForeground() → String
samplePass(double? rate) → bool
Returns true when the operation should proceed based on a probabilistic sampling rate.
stripAnsi(String value) → String
Returns value with all ANSI escape sequences removed.
truncateLeaves(Object? input, {required int maxLength}) → Object?
Recursively truncates string leaves in nested Map/Iterable structures.
truncateStackTrace(StackTrace? stackTrace, {int maxFrames = kDefaultStackFrameLimit}) → StackTrace?
Truncates stackTrace to maxFrames frames while keeping it a proper StackTrace so that tools like Flutter DevTools can still parse and display clickable frame links.
truncateString(String value, {int maxLength = kDefaultStringTruncateLimit}) → String
Truncates value to maxLength, avoiding surrogate pair splits.

Typedefs

ISpectLoadLogContentCallback = Future<String?> Function(BuildContext context)
Invoked when the log viewer needs to load log content from an external source (file picker, clipboard, URL, etc.).
ISpectLogDataBuilder = Widget Function(BuildContext context, ISpectLogData data)
Signature for build custom ISpectLogData widgets
ISpectLogErrorBuilder = Widget Function(BuildContext context, ISpectLogError data)
Signature for build custom ISpectLogError messages in showing Snackbar or another widgets
ISpectLogExceptionBuilder = Widget Function(BuildContext context, ISpectLogException data)
Signature for build custom ISpectLogException messages in showing Snackbar or another widgets
ISpectLogOptions = ISpectErrorHandlerOptions
Renamed to ISpectErrorHandlerOptions in 5.0.0 to disambiguate from ISpectOptions (UI configuration). Will be removed in 6.0.0.
ISpectObserverDisposer = void Function()
ISpectOpenFileCallback = Future<void> Function(String path)
Invoked when the user taps an exported log file path in the viewer.
ISpectScope = ISpectScopeController
Shorter, idiomatic alias for ISpectScopeController.
ISpectSettingsChangedCallback = void Function(ISpectSettingsState settings)
Called when ISpect settings change (logger options, enabled log types, etc.).
ISpectShareCallback = Future<void> Function(ISpectShareRequest request)
Invoked when the user shares logs from the inspector panel.
LoggerOutput = void Function(String message, {Object? error, LogLevel? logLevel, StackTrace? stackTrace, DateTime? time})
Callback signature for custom log output.

Exceptions / Errors

ISpectScopeNotFoundError
Thrown when ISpect.read(context) is called from a widget that is not inside an ISpectBuilder subtree.