devtools_profiler_core library

Pure-Dart profiling backend for DevTools-inspired automation flows.

This library is the programmatic entrypoint behind the profiler CLI and MCP server. It can launch or attach to VM-service targets, capture whole-session and region-scoped CPU and memory data, persist session artifacts, and build higher-level summaries such as call trees, method tables, hotspot explanations, comparisons, and trend analyses.

Most users should start with devtools_profiler_cli. Import this library directly when you are building another automation layer that needs the same capture and analysis primitives without terminal or MCP transport code.

import 'package:devtools_profiler_core/devtools_profiler_core.dart';

Future<void> main() async {
  final runner = ProfileRunner();
  final result = await runner.run(
    const ProfileRunRequest(
      command: ['dart', 'run', 'bin/main.dart'],
      workingDirectory: '/path/to/app',
    ),
  );

  print(result.sessionId);
  print(result.overallProfile?.sampleCount);
}

The most common starting points are ProfileRunner, ProfileRunRequest, ProfileAttachRequest, ProfileRunResult, and ProfileRegionResult.

Classes

AllocationAttribution: A single allocation-attribution entry for a memory class, showing the top call sites that were on the CPU stack during its growth.
ClassMemoryDelta: Per-class difference between two memory snapshots.
DebugDumpResult: Results from a Flutter debug dump call.
DebugDumpService: Calls Flutter debug dump service extensions for diagnostics.
DiscoveredApp: A running Dart or Flutter application discovered on the local machine.
FrameAnalysisResult: Results from a frame/jank analysis session.
FrameAnalyzer: Captures frame timing data from a running Dart VM service.
LogEntry: A single log entry captured from a VM service stream.
LogStreamCapture: Captures log and output streams from a running Dart VM service.
MemoryClassEntry: A single class allocation entry from a memory snapshot.
MemorySnapshot: A memory snapshot captured from a running VM service.
MemorySnapshotCapture: Captures memory allocation snapshots from a running VM service.
MemorySnapshotDelta: Result of comparing two MemorySnapshots.
ProfileArtifacts: Utilities for reading and summarizing profiler artifacts.
ProfileArtifactStore: Writes session and region artifacts for a profiling run.
ProfileAttachRequest: A request to profile an already-running Dart or Flutter VM service.
ProfileCallTree: A hierarchical CPU profile tree built from VM CPU samples.
ProfileCallTreeNode: A single node in a hierarchical CPU profile tree.
ProfileFrame: Metadata for a resolved CPU profile frame.
ProfileFrameDelta: A delta for a merged frame between two prepared profile summaries.
ProfileFrameSummary: A summary of a single frame observed during CPU sampling.
ProfileHotspotInsight: A single hotspot insight derived from a prepared profile.
ProfileHotspotMethodContext: Compact method context attached to a hotspot insight.
ProfileHotspotPath: A representative call path for a hotspot insight.
ProfileHotspotPathFrame: A frame in a representative hotspot call path.
ProfileHotspotSummary: A structured explanation of a prepared profile's hotspots.
ProfileMemoryClassDelta: A per-class memory delta between two profiled windows.
ProfileMemoryClassSummary: A per-class memory summary for a profiled region or session.
ProfileMemoryComparison: A memory diff between two profiled windows.
ProfileMemoryResult: Memory summary data captured for a profiled region or session.
ProfileMethodCandidate: A compact candidate entry returned for ambiguous or failed method lookups.
ProfileMethodComparison: A structured comparison for one selected method across two profiles.
ProfileMethodDelta: A delta for a merged method between two method tables.
ProfileMethodInspection: A structured inspection result for one selected method.
ProfileMethodPath: A representative occurrence path for a selected method.
ProfileMethodPathFrame: A single frame entry within a representative method path.
ProfileMethodRelation: A caller or callee relationship for a method table entry.
ProfileMethodRelationDelta: A delta for a caller or callee relation on a selected method.
ProfileMethodSearchResult: A structured result for searching methods within one prepared profile.
ProfileMethodSummary: A method-table entry summarizing a merged method across the CPU profile.
ProfileMethodTable: A DevTools-style method table for a CPU profile.
ProfileNumericDelta: Shared models for profile comparisons and regression summaries. A numeric baseline/current comparison with derived delta values.
ProfileRecurringRegression: A recurring regression subject observed across multiple trend steps.
ProfileRegionComparison: A structured comparison between two profiled regions or session profiles.
ProfileRegionOptions: Shared region options passed between the helper and backend.
ProfileRegionResult: A summary of profiling data for a marked region.
ProfileRegressionInsight: A structured regression insight derived from a profile comparison.
ProfileRegressionSummary: A prioritized regression summary for a profile comparison.
ProfileRunner: Launches profiled Dart processes and reads stored artifacts.
ProfileRunRequest: A request to launch and profile a Dart or Flutter command.
ProfileRunResult: A full profiling session result.
ProfileTrendPoint: A compact point in a profile trend series.
ProfileTrendSeriesEntry: One prepared profile entry in a multi-session trend series.
ProfileTrendStep: A consecutive step in a multi-session trend series.
ProfileTrendSummary: A structured cross-session trend summary for one selected profile.
ScreenshotCaptureService: Captures screenshots of running Flutter applications via VM service extension.
ShaderCompilationEvent: A timeline event related to shader compilation.
TimelineHotspot: A hotspot insight extracted from the VM timeline.
WidgetInspectorQueryResult: The result of a Flutter widget inspector service query.
WidgetInspectorQueryService: Queries Flutter widget inspector service extensions.
WidgetTreeCapture: Captured Flutter widget tree with metadata.
WidgetTreeCaptureService: Captures Flutter widget trees from a running application via VM service extension calls.
WidgetTreeNode: A node in the captured Flutter widget tree.

Enums

ProfileCallTreeView: Supported hierarchical CPU profile tree views.
ProfileCaptureKind: Supported profiler capture kinds.
ProfileHotspotSeverity: Severity for a hotspot insight.
ProfileIsolateScope: Supported isolate scopes for a profiling region.
ProfileMethodComparisonStatus: The overall state of a method comparison request.
ProfileMethodInspectionStatus: The lookup state for a method inspection request.
ProfileMethodSearchSort: Ordering modes for method search results.
ProfileMethodSearchStatus: Availability state for method search against a profile target.
ProfileProcessIoMode: How the profiled process should receive standard IO.
ProfileRegressionSeverity: Severity for a regression insight.

Constants

defaultProfileCaptureKinds → const List<ProfileCaptureKind>: The default capture kinds for a region request.

Functions

analyzeProfileTrends({required List<ProfileTrendSeriesEntry> entries, int? frameLimit, int? methodLimit, int? memoryClassLimit, int maxInsights = 5, int recurringLimit = 5}) → ProfileTrendSummary: Builds a cross-session trend summary from a series of prepared profiles.
attributeAllocationsToCallers(ProfileMemoryResult memory, CpuSamples cpuSamples) → List<AllocationAttribution>: Cross-references CPU samples with memory class deltas to attribute allocations to the functions that were on the CPU stack during heap growth.
buildBottomUpTree({required CpuSamples cpuSamples, ProfileFramePredicate? includeFrame}) → ProfileCallTree: Builds a DevTools-style bottom-up tree from raw VM CPU samples.
buildCallTree({required CpuSamples cpuSamples, ProfileFramePredicate? includeFrame}) → ProfileCallTree: Builds a top-down call tree from raw VM CPU samples.
buildMethodTable({required CpuSamples cpuSamples, ProfileFramePredicate? includeFrame}) → ProfileMethodTable: Builds a DevTools-style method table from raw VM CPU samples.
compareProfileMethods({required ProfileMethodInspection baseline, required ProfileMethodInspection current, int? relationLimit}) → ProfileMethodComparison: Compares one selected method across two inspected profiles.
compareProfileRegions({required ProfileRegionResult baseline, required ProfileRegionResult current, ProfileMethodTable? baselineMethodTable, ProfileMethodTable? currentMethodTable, int? frameLimit, int? methodLimit, int? memoryClassLimit, ProfileMemoryResult? baselineMemoryOverride, ProfileMemoryResult? currentMemoryOverride}) → ProfileRegionComparison: Builds a structured comparison between two prepared profile summaries.
discoverActiveApps() → Future<List<DiscoveredApp>>: Discovers running Dart and Flutter applications by scanning OS processes.
displayNameForFunction(ProfileFunction function) → String: Returns a human-readable name for a VM profile function.
explainProfileHotspots(ProfileRegionResult region, {ProfileMethodTable? methodTable, ProfileCallTree? callTree, ProfileCallTree? bottomUpTree, int maxInsights = 6, int relationLimit = 3}) → ProfileHotspotSummary: Builds prioritized hotspot insights from a prepared profile summary.
filterStackFrames(List<int> stack, List<ProfileFunction> functions, {ProfileFramePredicate? includeFrame}) → List<ProfileFrame>
heapSampleFromMemoryUsage({required MemoryUsage? memoryUsage, required int timestampMicros}) → HeapSample
inspectProfileMethod({required String query, required String queryKind, required ProfileMethodTable? methodTable, ProfileCallTree? callTree, ProfileCallTree? bottomUpTree, int? pathLimit}) → ProfileMethodInspection: Inspects a single method using a DevTools-style method table and optional call trees.
lineForFunction(ProfileFunction function) → int?: Returns the approximate source line number for function, or null if the line number is unavailable.
locationForFunction(ProfileFunction function) → String?: Returns the best source location available for a VM profile function.
mergeCpuSamples(Iterable<CpuSamples> cpuSamplesByIsolate) → CpuSamples: Merges multiple isolate-local CPU sample payloads into one synthetic profile.
normalizeProfileCaptureKinds(Iterable<ProfileCaptureKind> captureKinds) → List<ProfileCaptureKind>: Normalizes capture kinds by removing duplicates while preserving order.
normalizeProfileIsolateScopes(Iterable<ProfileIsolateScope> isolateScopes) → List<ProfileIsolateScope>: Normalizes isolate scopes by removing duplicates while preserving order.
profileFrameFromFunction(List<ProfileFunction> functions, int functionIndex) → ProfileFrame
readMemoryClassesFromArtifact(String rawProfilePath, {ProfileMemoryClassPredicate? includeClass, int topClassCount = 50}) → Future<ProfileMemoryResult>: Reads a raw memory_profile.json artifact from rawProfilePath and returns a ProfileMemoryResult with optional class filtering.
rebuildMemoryProfileFromArtifact(Map<String, Object?> rawArtifact, {required String rawProfilePath, ProfileMemoryClassPredicate? includeClass, int topClassCount = 50}) → ProfileMemoryResult: Parses a raw ProfileMemoryArtifact JSON map and returns a ProfileMemoryResult with optional class filtering.
searchProfileMethods({required ProfileMethodTable? methodTable, String? query, ProfileMethodSearchSort sortBy = ProfileMethodSearchSort.total, int? limit}) → ProfileMethodSearchResult: Searches a DevTools-style method table for candidate methods.
summarizeCpuSamples({required String regionId, required String name, required Map<String, String> attributes, required String isolateId, List<String>? isolateIds, List<ProfileCaptureKind> captureKinds = defaultProfileCaptureKinds, ProfileIsolateScope isolateScope = ProfileIsolateScope.current, String? parentRegionId, ProfileMemoryResult? memory, required int startTimestampMicros, required int endTimestampMicros, required CpuSamples cpuSamples, required String summaryPath, String? rawProfilePath, int topFrameCount = 10, ProfileFramePredicate? includeFrame, Map<String, Object?> extra = const {}}) → ProfileRegionResult: Builds a ProfileRegionResult from raw VM CPU samples.
summarizeMemoryProfile({required HeapSample start, required HeapSample end, required Iterable<ClassHeapStats> startClasses, required Iterable<ClassHeapStats> endClasses, required String rawProfilePath, int topClassCount = 10, ProfileMemoryClassPredicate? includeClass}) → ProfileMemoryResult: Builds a ProfileMemoryResult from start and end allocation snapshots.
summarizeProfileRegressions(ProfileRegionComparison comparison, {int maxInsights = 5}) → ProfileRegressionSummary: Builds prioritized regression insights from a structured comparison.

Typedefs

ProfileFramePredicate = bool Function(ProfileFrame frame): A predicate that determines whether a ProfileFrame should be included.
ProfileMemoryClassPredicate = bool Function(ProfileMemoryClassSummary summary): Predicate used to retain or hide memory class summaries.

devtools_profiler_core library

Classes

Enums

Constants

Functions

Typedefs

devtools_profiler_core package

devtools_profiler_core library