stack_trace 1.7.3

This library provides the ability to parse, inspect, and manipulate stack traces produced by the underlying Dart implementation. It also provides functions to produce string representations of stack traces in a more readable format than the native StackTrace implementation.

Traces can be parsed from native StackTraces using Trace.from, or captured using Trace.current. Native StackTraces can also be directly converted to human-readable strings using Trace.format.

Here's an example native stack trace from debugging this library:

#0      Object.noSuchMethod (dart:core-patch:1884:25)
#1      Trace.terse.<anonymous closure> (file:///usr/local/google-old/home/goog/dart/dart/pkg/stack_trace/lib/src/trace.dart:47:21)
#2      IterableMixinWorkaround.reduce (dart:collection:29:29)
#3      List.reduce (dart:core-patch:1247:42)
#4      Trace.terse (file:///usr/local/google-old/home/goog/dart/dart/pkg/stack_trace/lib/src/trace.dart:40:35)
#5      format (file:///usr/local/google-old/home/goog/dart/dart/pkg/stack_trace/lib/stack_trace.dart:24:28)
#6      main.<anonymous closure> (file:///usr/local/google-old/home/goog/dart/dart/test.dart:21:29)
#7      _CatchErrorFuture._sendError (dart:async:525:24)
#8      _FutureImpl._setErrorWithoutAsyncTrace (dart:async:393:26)
#9      _FutureImpl._setError (dart:async:378:31)
#10     _ThenFuture._sendValue (dart:async:490:16)
#11     _FutureImpl._handleValue.<anonymous closure> (dart:async:349:28)
#12     Timer.run.<anonymous closure> (dart:async:2402:21)
#13     Timer.Timer.<anonymous closure> (dart:async-patch:15:15)

and its human-readable representation:

dart:core-patch 1884:25                     Object.noSuchMethod
pkg/stack_trace/lib/src/trace.dart 47:21    Trace.terse.<fn>
dart:collection 29:29                       IterableMixinWorkaround.reduce
dart:core-patch 1247:42                     List.reduce
pkg/stack_trace/lib/src/trace.dart 40:35    Trace.terse
pkg/stack_trace/lib/stack_trace.dart 24:28  format
test.dart 21:29                             main.<fn>
dart:async 525:24                           _CatchErrorFuture._sendError
dart:async 393:26                           _FutureImpl._setErrorWithoutAsyncTrace
dart:async 378:31                           _FutureImpl._setError
dart:async 490:16                           _ThenFuture._sendValue
dart:async 349:28                           _FutureImpl._handleValue.<fn>
dart:async 2402:21                          Timer.run.<fn>
dart:async-patch 15:15                      Timer.Timer.<fn>

You can further clean up the stack trace using Trace.terse. This folds together multiple stack frames from the Dart core libraries, so that only the core library method that was directly called from user code is visible. For example:

dart:core                                   Object.noSuchMethod
pkg/stack_trace/lib/src/trace.dart 47:21    Trace.terse.<fn>
dart:core                                   List.reduce
pkg/stack_trace/lib/src/trace.dart 40:35    Trace.terse
pkg/stack_trace/lib/stack_trace.dart 24:28  format
test.dart 21:29                             main.<fn>

Stack Chains

This library also provides the ability to capture "stack chains" with the Chain class. When writing asynchronous code, a single stack trace isn't very useful, since the call stack is unwound every time something async happens. A stack chain tracks stack traces through asynchronous calls, so that you can see the full path from main down to the error.

To use stack chains, just wrap the code that you want to track in Chain.capture. This will create a new Zone in which stack traces are recorded and woven into chains every time an asynchronous call occurs. Zones are sticky, too, so any asynchronous operations started in the Chain.capture callback will have their chains tracked, as will asynchronous operations they start and so on.

Here's an example of some code that doesn't capture its stack chains:

import 'dart:async';

void main() {
  scheduleAsync();
}

void scheduleAsync() {
  return new Future.delayed(new Duration(seconds: 1))
      .then((_) => runAsync());
}

void runAsync() {
  throw 'oh no!';
}

If we run this, it prints the following:

Uncaught Error: oh no!
Stack Trace: 
#0      runAsync (file:///usr/local/google-old/home/goog/dart/dart/test.dart:13:3)
#1      scheduleAsync.<anonymous closure> (file:///usr/local/google-old/home/goog/dart/dart/test.dart:9:28)
#2      _rootRunUnary (dart:async/zone.dart:717)
#3      _RootZone.runUnary (dart:async/zone.dart:854)
#4      _Future._propagateToListeners.handleValueCallback (dart:async/future_impl.dart:488)
#5      _Future._propagateToListeners (dart:async/future_impl.dart:571)
#6      _Future._complete (dart:async/future_impl.dart:317)
#7      _SyncCompleter.complete (dart:async/future_impl.dart:44)
#8      Future.Future.delayed.<anonymous closure> (dart:async/future.dart:219)
#9      _createTimer.<anonymous closure> (dart:async-patch/timer_patch.dart:11)
#10     _handleTimeout (dart:io/timer_impl.dart:292)
#11     _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:115)

Notice how there's no mention of main in that stack trace. All we know is that the error was in runAsync; we don't know why runAsync was called.

Now let's look at the same code with stack chains captured:

import 'dart:async';

import 'package:stack_trace/stack_trace.dart';

void main() {
  Chain.capture(() {
    scheduleAsync();
  });
}

void scheduleAsync() {
  new Future.delayed(new Duration(seconds: 1))
      .then((_) => runAsync());
}

void runAsync() {
  throw 'oh no!';
}

Now if we run it, it prints this:

Uncaught Error: oh no!
Stack Trace: 
test.dart 17:3                                                runAsync
test.dart 13:28                                               scheduleAsync.<fn>
package:stack_trace/src/stack_zone_specification.dart 129:26  registerUnaryCallback.<fn>.<fn>
package:stack_trace/src/stack_zone_specification.dart 174:15  StackZoneSpecification._run
package:stack_trace/src/stack_zone_specification.dart 177:7   StackZoneSpecification._run
package:stack_trace/src/stack_zone_specification.dart 175:7   StackZoneSpecification._run
package:stack_trace/src/stack_zone_specification.dart 129:18  registerUnaryCallback.<fn>
dart:async/zone.dart 717                                      _rootRunUnary
dart:async/zone.dart 449                                      _ZoneDelegate.runUnary
dart:async/zone.dart 654                                      _CustomizedZone.runUnary
dart:async/future_impl.dart 488                               _Future._propagateToListeners.handleValueCallback
dart:async/future_impl.dart 571                               _Future._propagateToListeners
dart:async/future_impl.dart 317                               _Future._complete
dart:async/future_impl.dart 44                                _SyncCompleter.complete
dart:async/future.dart 219                                    Future.Future.delayed.<fn>
package:stack_trace/src/stack_zone_specification.dart 174:15  StackZoneSpecification._run
package:stack_trace/src/stack_zone_specification.dart 119:52  registerCallback.<fn>
dart:async/zone.dart 706                                      _rootRun
dart:async/zone.dart 440                                      _ZoneDelegate.run
dart:async/zone.dart 650                                      _CustomizedZone.run
dart:async/zone.dart 561                                      _BaseZone.runGuarded
dart:async/zone.dart 586                                      _BaseZone.bindCallback.<fn>
package:stack_trace/src/stack_zone_specification.dart 174:15  StackZoneSpecification._run
package:stack_trace/src/stack_zone_specification.dart 119:52  registerCallback.<fn>
dart:async/zone.dart 710                                      _rootRun
dart:async/zone.dart 440                                      _ZoneDelegate.run
dart:async/zone.dart 650                                      _CustomizedZone.run
dart:async/zone.dart 561                                      _BaseZone.runGuarded
dart:async/zone.dart 586                                      _BaseZone.bindCallback.<fn>
dart:async-patch/timer_patch.dart 11                          _createTimer.<fn>
dart:io/timer_impl.dart 292                                   _handleTimeout
dart:isolate-patch/isolate_patch.dart 115                     _RawReceivePortImpl._handleMessage
===== asynchronous gap ===========================
dart:async/zone.dart 476                                      _ZoneDelegate.registerUnaryCallback
dart:async/zone.dart 666                                      _CustomizedZone.registerUnaryCallback
dart:async/future_impl.dart 164                               _Future._Future._then
dart:async/future_impl.dart 187                               _Future.then
test.dart 13:12                                               scheduleAsync
test.dart 7:18                                                main.<fn>
dart:async/zone.dart 710                                      _rootRun
dart:async/zone.dart 440                                      _ZoneDelegate.run
dart:async/zone.dart 650                                      _CustomizedZone.run
dart:async/zone.dart 944                                      runZoned
package:stack_trace/src/chain.dart 93:20                      Chain.capture
test.dart 6:16                                                main
dart:isolate-patch/isolate_patch.dart 216                     _startIsolate.isolateStartHandler
dart:isolate-patch/isolate_patch.dart 115                     _RawReceivePortImpl._handleMessage

That's a lot of text! If you look closely, though, you can see that main is listed in the first trace in the chain.

Thankfully, you can call Chain.terse just like Trace.terse to get rid of all the frames you don't care about. The terse version of the stack chain above is this:

test.dart 17:3       runAsync
test.dart 13:28      scheduleAsync.<fn>
===== asynchronous gap ===========================
dart:async           _Future.then
test.dart 13:12      scheduleAsync
test.dart 7:18       main.<fn>
package:stack_trace  Chain.capture
test.dart 6:16       main

That's a lot easier to understand!

1.7.3

  • Fix broken links in the README.

1.7.2

  • Trace.foldFrames() and Chain.foldFrames() now remove the outermost folded frame. This matches the behavior of .terse with core frames.

  • Fix bug parsing a friendly frame with spaces in the member name.

  • Fix bug parsing a friendly frame where the location is a data url.

1.7.1

  • Make Trace.parse(), Chain.parse(), treat the VM's new causal asynchronous stack traces as chains. Outside of a Chain.capture() block, new Chain.current() will return a stack chain constructed from the asynchronous stack traces.

1.7.0

  • Add a Chain.disable() function that disables stack-chain tracking.

  • Fix a bug where Chain.capture(..., when: false) would throw if an error was emitted without a stack trace.

1.6.8

  • Add a note to the documentation of Chain.terse and Trace.terse.

1.6.7

  • Fix a bug where new Frame.caller() returned the wrong depth of frame on Dartium.

1.6.6

  • new Trace.current() and new Chain.current() now skip an extra frame when run in a JS context. This makes their return values match the VM context.

1.6.5

  • Really fix strong mode warnings.

1.6.4

  • Fix a syntax error introduced in 1.6.3.

1.6.3

  • Make Chain.capture() generic. Its signature is now T Chain.capture<T>(T callback(), ...).

1.6.2

  • Fix all strong mode warnings.

1.6.1

  • Use StackTrace.current in Dart SDK 1.14 to get the current stack trace.

1.6.0

  • Add a when parameter to Chain.capture(). This allows capturing to be easily enabled and disabled based on whether the application is running in debug/development mode or not.

  • Deprecate the ChainHandler typedef. This didn't provide any value over directly annotating the function argument, and it made the documentation less clear.

1.5.1

  • Fix a crash in Chain.foldFrames() and Chain.terse when one of the chain's traces has no frames.

1.5.0

  • new Chain.parse() now parses all the stack trace formats supported by new Trace.parse(). Formats other than that emitted by Chain.toString() will produce single-element chains.

  • new Trace.parse() now parses the output of Chain.toString(). It produces the same result as Chain.parse().toTrace().

1.4.2

  • Improve the display of data: URIs in stack traces.

1.4.1

  • Fix a crashing bug in UnparsedFrame.toString().

1.4.0

  • new Trace.parse() and related constructors will no longer throw an exception if they encounter an unparseable stack frame. Instead, they will generate an UnparsedFrame, which exposes no metadata but preserves the frame's original text.

  • Properly parse native-code V8 frames.

1.3.5

  • Properly shorten library names for pathnames of folded frames on Windows.

1.3.4

  • No longer say that stack chains aren't supported on dart2js now that sdk#15171 is fixed. Note that this fix only applies to Dart 1.12.

1.3.3

  • When a null stack trace is passed to a completer or stream controller in nested Chain.capture() blocks, substitute the inner block's chain rather than the outer block's.

  • Add support for empty chains and chains of empty traces to Chain.parse().

  • Don't crash when parsing stack traces from Dart VM stack overflows.

1.3.2

  • Don't crash when running Trace.terse on empty stack traces.

1.3.1

  • Support more types of JavaScriptCore stack frames.

1.3.0

  • Support stack traces generated by JavaScriptCore. They can be explicitly parsed via new Trace.parseJSCore and new Frame.parseJSCore.

1.2.4

  • Fix a type annotation in LazyTrace.

1.2.3

  • Fix a crash in Chain.parse.

1.2.2

  • Don't print the first folded frame of terse stack traces. This frame is always just an internal isolate message handler anyway. This improves the readability of stack traces, especially in stack chains.

  • Remove the line numbers and specific files in all terse folded frames, not just those from core libraries.

  • Make padding consistent across all stack traces for Chain.toString().

1.2.1

  • Add terse to LazyTrace.foldFrames().

  • Further improve stack chains when using the VM's async/await implementation.

1.2.0

  • Add a terse argument to Trace.foldFrames() and Chain.foldFrames(). This allows them to inherit the behavior of Trace.terse and Chain.terse without having to duplicate the logic.

1.1.3

  • Produce nicer-looking stack chains when using the VM's async/await implementation.

1.1.2

  • Support VM frames without line or column numbers, which async/await programs occasionally generate.

  • Replace <<anonymous closure>_async_body> in VM frames' members with the terser <async>.

1.1.1

  • Widen the SDK constraint to include 1.7.0-dev.4.0.

1.1.0

  • Unify the parsing of Safari and Firefox stack traces. This fixes an error in Firefox trace parsing.

  • Deprecate Trace.parseSafari6_0, Trace.parseSafari6_1, Frame.parseSafari6_0, and Frame.parseSafari6_1.

  • Add Frame.parseSafari.

1.0.3

  • Use Zone.errorCallback to attach stack chains to all errors without the need for Chain.track, which is now deprecated.

1.0.2

1.0.1

  • Synchronous errors in the [Chain.capture] callback are now handled correctly.

1.0.0

  • No API changes, just declared stable.

0.9.3+2

  • Update the dependency on path.

  • Improve the formatting of library URIs in stack traces.

0.9.3+1

  • If an error is thrown in Chain.capture's onError handler, that error is handled by the parent zone. This matches the behavior of runZoned in dart:async.

0.9.3

  • Add a Chain.foldFrames method that parallels Trace.foldFrames.

  • Record anonymous method frames in IE10 as "<fn>".

1. Depend on it

Add this to your package's pubspec.yaml file:

dependencies:
  stack_trace: 

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support pub. Check the docs for your editor to learn more.

About

A package for manipulating stack traces and printing them readably.

Author

Email misc@dartlang.org Dart Team

Homepage

github.com/dart-lang/stack_trace

Documentation

www.dartdocs.org/documentation/stack_trace/1.7.3/

Source code (hyperlinked)

www.crossdart.info/p/stack_trace/1.7.3/

Uploader

sigmund@google.com
dgrove@google.com
nweiz@google.com
kevmoo@google.com
rnystrom@google.com

Share