Flutter SDK API

Everything here is on CodeScout.instance unless stated otherwise.

Initialising

init()

Future<void> init({
  CodeScoutConfiguration? configuration,
  FreshContextFetcher? freshContextFetcher,
})

Call once, early. Throws if called twice.

Parameter	Type	Description
configuration	CodeScoutConfiguration?	Everything below. Omit for defaults, which work with no server.
freshContextFetcher	BuildContext Function()?	Supplies a context for the floating overlay. Omit if you do not want the overlay.

Logging works before init() runs and never throws. An observability library must not be the reason an app fails to start.

Logging

Shorthand

void v(
  String message, {
  dynamic error,
  StackTrace? stackTrace,
  Set<String>? tags,
  Map<String, dynamic>? metadata,
  String? requestId,
})
void d(...)  // debug
void i(...)  // info
void w(...)  // warning
void e(...)  // error
void f(...)  // fatal

Fire and forget. They never throw.

log()

void log({
  required LogLevel level,
  required String message,
  dynamic error,
  StackTrace? stackTrace,
  Set<String>? tags,
  Map<String, dynamic>? metadata,
  String? requestId,
})

The full form, for when the level is dynamic.

logMessage()

Future<void> logMessage({
  required LogLevel level,
  required String message,
  dynamic error,
  StackTrace? stackTrace,
  Set<String>? tags,
  Map<String, dynamic>? metadata,
  String? requestId,
})

The same parameters, awaitable, and it propagates errors instead of swallowing them. Use it when you genuinely need to know the log was stored.

Caution

tags is a Set<String>, not a List. A tag is either on a log or it is not.

requestId

The id of the HTTP call a log is about, read from codeScoutRequestId on a code_scout_dio or code_scout_http response. Every logging call above takes it, from code_scout 1.6.0.

The log is shown with that call, in the in-app panel and on the dashboard, and stays an ordinary log: it is not a network log, and it never changes the call’s status. Only a UUID in the standard 8-4-4-4-12 form is kept, in lowercase. Anything else is dropped from the log, with a warning said once per launch that never includes the value. See When the API changes under you.

Identity

setUser()

Future<void> setUser(String? id, {Map<String, dynamic>? traits})

Names the person using the app. Never inferred: nothing appears against a session until you call this. Safe at any point after init() has run. Called before that it returns quietly, because there is no session to attach anything to yet. The session record is re-sent with every batch, so a call made ten minutes in still reaches the dashboard. setUser(null) clears it.

See Sessions and Identity.

Live sessions

startLiveSession()

Future<bool> startLiveSession(String code)

Pairs with a code minted in the dashboard and streams this launch as it happens. Returns false rather than throwing, because a mistyped or expired code is the common case.

stopLiveSession()

Future<void> stopLiveSession()

isLiveStreaming

bool. Whether this launch is being streamed right now.

See Watching a Device Live.

Overlay

void showIcon();
void hideIcon();
void toggleIcon();

The floating button. Tapping it opens a sheet with three tabs.

Logs is everything this launch has written, with search, a toggle per level, tag filters and a pause control. Network is one row per HTTP call. Errors is errors and fatals on their own. Your errors are counted by message and error text, and each failed call is a row of its own.

The sheet’s header carries Info, which reports the connection, what is being captured and the upload state, and the live pairing pill beside it rather than as a tab. A Data icon appears alongside them once the app has called registerDatabase, and browses those databases read only. Nothing is listed until the app names it, so an app that registers nothing never sees the icon.

It reads an in-memory buffer of the current launch, the last 500 entries, so it works with no server configured and starts empty after a restart.

Session facts

Member	Type	Description
currentSessionId	String	This launch’s id.
currentSession	SessionRecord?	Device, OS, app version, install id, user. Null until init() has recorded it.
isInitialized	bool
isSessionSampledIn	bool	Whether this launch is being recorded. See Controlling Volume.

Cleanup

Future<void> dispose()

Companion packages

code_scout_talker

import 'package:talker/talker.dart';
import 'package:code_scout_talker/code_scout_talker.dart';

final talker = Talker(observer: CodeScoutTalkerObserver());

Everything Talker logs is forwarded as well as printed. Your logging calls do not change and TalkerScreen keeps working. Levels map across by name, except Talker’s critical, which arrives as fatal.

Note

Both packages export a LogLevel. If you import package:talker/talker.dart and package:code_scout/code_scout.dart in the same file, hide one of them.

code_scout_dio

import 'package:code_scout_dio/code_scout_dio.dart';

dio.interceptors.add(CodeScoutDioInterceptor());

From 1.1.0, codeScoutRequestId is a getter on Response, DioException and RequestOptions. It returns the id the interceptor gave the call, or null when the interceptor never saw it. A DioException thrown because the body did not fit the type the call asked for still names the call. codeScoutRequestIdKey is the key the id is kept under in RequestOptions.extra.

code_scout_http

import 'package:code_scout_http/code_scout_http.dart';

final client = CodeScoutHttpClient(client: http.Client());

Wraps get, post, put, delete, patch and the rest. Capture never fails the request it observes: every hook does its work inside a try/catch and always forwards.

From 1.1.0, codeScoutRequestId is a getter on http.BaseResponse and http.BaseRequest. It returns the id the client gave the call, or null for one that did not go through a CodeScoutHttpClient.

The request has the id before it is sent. So when you build an http.Request yourself and send it with client.send(request), a call that failed with no response can still be named from your catch. client.get, post and the other shorthands build the request inside the client, and the ClientException or SocketException they throw carries no request. That failure cannot be named, though CodeScout still records it as the call’s error. When a RetryClient wraps CodeScoutHttpClient, the getter on the request you built returns null too, because RetryClient sends a copy of it. The response it returns still names the call.

LogLevel

enum LogLevel {
  all(0),
  system(500),
  verbose(1000),
  debug(2000),
  info(3000),
  warning(4000),
  error(5000),
  fatal(6000),
  off(10000),
}

all and off are thresholds for minimumLevel, not levels to log at. See Log Levels.