description

# dart:developer library

Interact with developer tools such as the debugger and inspector.

This is a specialized library intended for interacting with the Dart runtime programmatically for debugging and inspection. Sample uses include advanced debugging, and creating developer tools.

This library has platform specific implementations for Dart web and Dart Native (VM). A specific platform may not support all operations.

The functionality provided by this library is generally only available to Dart code run in development mode, e.g., `dart run`, and not in production mode, e.g., the output of `dart compile exe`.

## Debugging

The debugger function can be used to stop the program as if a breakpoint was hit. The breakpoint will be placed right after the call to `debugger`. This functionality can be useful for triggering breakpoints based on logic in the code.

Example:

    var counter = 0;
    final someInterestingValue = 1000;
    while (true) {
      if (counter == someInterestingValue) {
        // Trigger a breakpoint in the debugger.
        debugger();
      }
      counter++;
    }

When executed with `dart run --observe`, and opened in DevTools, the debugger will be stopped with `counter` at the value `1000`.

## Inspection

Developer tools, such as Dart DevTools, connected to the runtime system may allow for inspecting execution timing in a "timeline" view. The static methods of Timeline can add extra information and timing events to this view.

Example:

    void main() {
      Timeline.timeSync('Calculation loop', () {
        for (var i = 30; i < 50; i++) {
          Timeline.timeSync('fib($i)', () {
            fibonacci(i);
          });
        }
      });
    }

    int fibonacci(int n) => (n < 2) ? n : fibonacci(n - 2) + fibonacci(n - 1);

When executed with `dart run --observe`, and opened in DevTools, the Performance tab will display a timeline containing the annotations passed to `timeSync`.

## Developer tools

A developer tool, like the debugger built into the `dart` command, may access information about the running application exposed by the runtime system, using the Service and ServiceProtocolInfo classes.

## Classes

CreationLocation
  Holds the source code location where an object was created, when its class was annotated with `@pragma('track-creation-locations')`.
Flow
  A class to represent Flow events.
NativeRuntime
  Functionality available on the native runtime.
Service
  Access information about the service protocol and control the web server that provides access to the services provided by the Dart VM for debugging and inspecting Dart programs.
ServiceExtensionResponse
  A response to a service protocol extension RPC.
ServiceProtocolInfo
  Service protocol is the protocol that a client like the Observatory could use to access the services provided by the Dart VM for debugging and inspecting Dart programs. This class encapsulates the version number and Uri for accessing this service.
Timeline
  Add to the timeline.
TimelineTask
  An asynchronous task on the timeline. An asynchronous task can have many (nested) synchronous operations. Synchronous operations can live longer than the current isolate event. To pass a TimelineTask to another isolate, you must first call pass to get the task id and then construct a new TimelineTask in the other isolate.
UserTag
  A UserTag can be used to group samples in the DevTools CPU profiler.

## Enums

TimelineRecorder
  Types of timeline recorders supported by the VM.
TimelineStream
  Specific sets of events whose recording can be enabled separately.

## Properties

extensionStreamHasListener → bool
  Whether the "Extension" stream currently has at least one listener.
  no setter
reachabilityBarrier → int
  Current reachability barrier state.
  no setter

## Functions

addHttpClientProfilingData(Map<String, dynamic> requestProfile) → void
  Records the data associated with an HTTP request for profiling purposes.
debugger({bool when = true, String? message}) → bool
  If `when` is true, stop the program as if a breakpoint were hit at the following statement.
getCurrentTag() → UserTag
  Returns the current UserTag for the isolate.
getHttpClientProfilingData() → List<Map<String, dynamic>>
  Returns the data added through addHttpClientProfilingData.
inspect(Object? object) → Object?
  Send a reference to `object` to any attached debuggers.
log(String message, {DateTime? time, int? sequenceNumber, int level = 0, String name = '', Zone? zone, Object? error, StackTrace? stackTrace}) → void
  Emit a log event, which can can viewed using the DevTools Logging view.
postEvent(String eventKind, Map eventData, {String stream = 'Extension'}) → void
  Post an event of `eventKind` with payload of `eventData` to the "Extension" event stream.
registerExtension(String method, ServiceExtensionHandler handler) → void
  Register a ServiceExtensionHandler that will be invoked in this isolate for `method`. NOTE: Service protocol extensions must be registered in each isolate.

## Typedefs

ServiceExtensionHandler = Future<ServiceExtensionResponse> Function(String method, Map<String, String> parameters)
  A service protocol extension handler. Registered with registerExtension.
TimelineAsyncFunction = Future Function()
TimelineSyncFunction<T> = T Function()
  A typedef for the function argument to Timeline.timeSync.