ispectify library

Classes

AnsiPen
Pen attributes for foreground and background colors.
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.
BoundedByteBody
Decodes a bounded prefix of a network body for diagnostics.
BoxedLogEntryFormatter
Boxed console output: an opt-in alternative to HumanLogEntryFormatter that frames each entry so individual logs stay distinct in a busy console.
CategoryFilter
Matches logs whose TraceKeys.category is in categories.
ComposerPickedFile
A file selected by the host application for a composed multipart request.
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.
DiagnosticProcessingPolicy
Cooperative scheduling used by diagnostic import and export operations.
DiagnosticResourceLimits
Resource budgets applied while diagnostics are captured and handed off.
ExtendedLoggerFormatter
Applies ANSI color per line and substitutes a placeholder for empty payloads. Layout (level column, indent, metadata) is owned by ILogEntryFormatter; this formatter intentionally does not reshape the incoming message so single-line and multi-line entries align identically.
FakeISpectLogger
Test double for ISpectLogger. Captures all logs for assertions.
FileLogHistory
Extended ILogHistory with daily file-based persistence.
FileLogHistoryOptions
Filter<T>
A generic filter that checks whether a given item satisfies certain conditions. Used as a building block for more specific filter types.
FormUrlEncodedReplayBody
An application/x-www-form-urlencoded payload.
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.
ISpectBaseLogger
Console logger: formats messages via ILoggerFormatter and writes them through a LoggerOutput function.
ISpectDateTimeFormatter
A utility class for formatting DateTime objects into readable strings.
ISpectErrorHandler
A utility class for handling errors and exceptions in ISpectLogger.
ISpectFilter
Composite filter combining log-type-key, runtime type, and search criteria.
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.
ISpectMetadata
Environment/runtime metadata attached to exported log files.
ISpectObserver
Observer for monitoring ISpectLogger events.
ISpectRedaction
Global default policy and kill-switch for all ISpect redaction.
ISpectServiceExtensions
Read-only Dart VM service extensions over the ISpect log history.
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.
JsonReplayBody
A JSON payload serialized with Content-Type: application/json.
JsonTruncator
Pretty-prints JSON objects with depth and size limits.
JsonValueNormalizer
Converts arbitrary diagnostic values into structures accepted by JSON encoders while preserving maps and iterables.
KeyBasedRedaction
Redacts values based on key names: fully-masked keys and sensitive keys.
LogDetails
LogExporter
Utility class for batch export of log data.
LogExportOutput
Shared byte limits for outbound log documents.
LogLevelRangeFilter
Filters logs by a LogLevel range (inclusive).
LogTypeKeyFilter
Matches ISpectLogData items whose ISpectLogData.key is in keys.
MultipartCapture
Shared capture budget for multipart request bodies.
MultipartReplayBody
A multipart/form-data payload combining text fields and file parts.
MultipartReplayField
A single text field of a MultipartReplayBody. Field names may repeat, so parts are modeled as a list rather than a map.
MultipartReplayFile
A single file part of a MultipartReplayBody.
NetworkBaseUrlProvider
Implemented by a NetworkRequestSender whose client sends requests against a base URL.
NetworkFilter<T>
Base class for network filter chain units.
NetworkFilterChain<T>
Immutable, ordered chain of NetworkFilters with short-circuit evaluation.
NetworkInterceptorDefaults
Shared defaults for every ISpect network diagnostics adapter.
NetworkJsonKeys
Canonical JSON key names used across all network interceptor packages.
NetworkLogPayload
Structured request or response data prepared for diagnostic presentation.
NetworkLogPrintOptions
Abstraction describing print preferences and color configuration for network-related logs.
NetworkLogRenderer
Extracts and formats network diagnostics for console and UI presentation.
NetworkMapRedactor
Standard redaction pipeline for network toJson() maps.
NetworkPayloadSanitizer
Provides reusable sanitization helpers for network payloads.
NetworkReplayBody
Transport-agnostic body of a composed/replayed HTTP request.
NetworkReplayRequest
A transport-agnostic description of an HTTP request to send.
NetworkReplayRequestParser
Reconstructs a NetworkReplayRequest from a captured request map.
NetworkReplayResult
Outcome of sending a NetworkReplayRequest through a NetworkRequestSender.
NetworkRequestSender
Sends a composed/replayed request through a real, app-owned client.
NetworkSenderRegistry
Holds the NetworkRequestSenders registered by the host application.
NetworkTransaction
Groups a correlated HTTP request with its response or error.
NetworkUriSnapshot
Bounded URL and path captured from caller-owned URL text.
ParsedReplayRequest
The result of reconstructing a NetworkReplayRequest from a captured log, carrying which values were dropped because they were redacted.
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.
RollingFileLogHistory
SamplingFilter<T>
Logs only every sampleRate-th event (1-based counting).
SearchFilter
Case-insensitive search across the values of ISpectLogData, including values nested in ISpectLogData.additionalData.
SessionStatistics
Snapshot of session metrics and configuration.
SourceFilter
Matches logs whose TraceKeys.source is in sources.
StateObserverPolicy
Capture gates and filter matching shared by the BLoC and Riverpod observers.
StateTracePreparer
Bounds and redacts state-management payloads before they enter a trace.
StatusCodeFilter<T>
Passes only events whose HTTP status code satisfies predicate.
TextReplayBody
A raw text payload sent verbatim.
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 core log kinds in types without reading an overridable runtimeType getter.
UrlExclusionFilter<T>
Suppresses logging for URLs matching any of excludedPatterns.

Enums

DiagnosticCaptureMode
Controls whether diagnostics may use application-defined formatters.
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.
NetworkCapturePolicyMixin
Capture policy shared by network interceptors whose settings extend BaseNetworkInterceptorSettings.
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

ISpectDataX on ISpectLogData
Utility extensions on ISpectLogData: copy, formatting, cURL generation.
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.

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 the placeholder (no partial/edge masking), regardless of whether the key is also in defaultSensitiveKeys.
defaultPlaceholder → const String
The single placeholder substituted for every redacted value across all ispect packages - network, database, export, clipboard, and cURL.
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.
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
Deprecated alias of defaultPlaceholder.
redactionFailedPlaceholder → const String
Placeholder returned when redaction itself throws an exception.
userInfoRedactedPlaceholder → const String
URI-safe form of defaultPlaceholder for redacted userInfo 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
authorizationSchemeRegex → RegExp
Any syntactically valid HTTP authentication scheme followed by credentials.
final
base64LineBreakRegex → RegExp
Line terminators MIME and PEM use to wrap Base64 payloads.
final
base64Regex → RegExp
Characters valid in standard or URL-safe Base64.
final
color_disabled ↔ bool
getter/setter pair
dbCategory → ISpectTraceCategory
final
defaultFullyMaskedKeysLower → Set<String>
Lowercased form of defaultFullyMaskedKeys, computed once. See defaultSensitiveKeysLower.
final
defaultSensitiveKeyPatterns → List<RegExp>
Regex patterns that match sensitive key name fragments.
final
defaultSensitiveKeysLower → Set<String>
Lowercased form of defaultSensitiveKeys, computed once so callers that build a RedactionService with the defaults do not re-lowercase and re-allocate the set on every construction.
final
graphqlCategory → ISpectTraceCategory
final
grpcCategory → ISpectTraceCategory
final
hexIdentifierRegex → RegExp
Hexadecimal identifiers, optionally grouped by - as a UUID is.
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) and protocol-relative URLs embedded in free-form diagnostic text.
final
whitespaceRegex → RegExp
Any whitespace character.
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.
captureISpectLogDataForEgress(ISpectLogData data) → ({Map<String, dynamic>? additionalData, DiagnosticCaptureMode captureMode, Error? error, String? errorText, Object? exception, String? exceptionText, String id, String? key, LogLevel? logLevel, Object? message, AnsiPen? pen, DiagnosticResourceLimits resourceLimits, StackTrace? stackTrace, String? stackTraceText, DateTime time})
Reads the package-owned base storage without dispatching through getters that an external subtype can override.
captureISpectLogWithoutPayload(ISpectLogData data) → ({String? errorText, String? exceptionText, String? key, LogLevel? logLevel, Object? message, DiagnosticResourceLimits resourceLimits, StackTrace? stackTrace, String? stackTraceText, DateTime time})
Reads every captured field except the payload.
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.
currentTraceTransactionId() → String?
Returns the transaction ID of the enclosing ISpectTrace.traceTransaction, or null outside one.
describeRuntimeType(Object? value, {required DiagnosticCaptureMode captureMode, required String fallback, DiagnosticResourceLimits resourceLimits = DiagnosticResourceLimits.balanced}) → String
Returns the concrete class name of value, bounded by resourceLimits.
developerLogOutput(String message, {LogLevel? logLevel, Object? error, StackTrace? stackTrace, DateTime? time}) → void
Routes message to dart:developer's log() as a single ISpect-tagged entry, mapping logLevel to its developer-log level.
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.
guardDiagnostics(ISpectLogger logger, void action(), {required String what}) → void
Runs action and reports a thrown failure as a warning on logger instead of propagating it into the host application.
maskedDiagnosticField(ISpectLogData data, String key) → Object?
Masks a single captured field without materializing the whole masked map.
maskedDiagnosticFields(ISpectLogData data, Iterable<String> keys) → Map<String, Object?>
Masks the captured values under keys in one pass without materializing the whole masked map.
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
safeValueTypeLabel(Object? value, {DiagnosticCaptureMode captureMode = DiagnosticCaptureMode.balanced, DiagnosticResourceLimits resourceLimits = DiagnosticResourceLimits.balanced}) → String
Returns the concrete class name of value, falling back to a coarse type family.
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, int? maxDepth}) → 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

DiagnosticMasker = Map<String, dynamic>? Function(Map<String, dynamic>? value, DiagnosticResourceLimits resourceLimits)
Masks a bounded diagnostic map on its way to a consumer.
FileLogDirectoryProvider = Future<String> Function()
Resolves an existing app-private directory for rolling log persistence.
FileLogHistoryErrorHandler = void Function(FileLogHistoryException error)
ISpectObserverDisposer = void Function()
LoggerOutput = void Function(String message, {Object? error, LogLevel? logLevel, StackTrace? stackTrace, DateTime? time})
Callback signature for custom log output.