Configuration

Everything is configured through one object passed to init().

await CodeScout.instance.init(
  freshContextFetcher: () => context,
  configuration: CodeScoutConfiguration(
    logging: LoggingBehavior(...),
    projectCredentials: ProjectCredentials(...),
    sync: LogSyncBehavior(...),
    redaction: RedactionBehavior(...),
    realTime: RealTimeConfig(...),
  ),
);

CodeScoutConfiguration() on its own is a working local-only setup.

LoggingBehavior

What gets captured.

Option	Default	Description
minimumLevel	LogLevel.info	Levels below this are dropped entirely.
enabledTags	{'*'}	Which tagged logs to keep. '*' keeps everything.
allowUntagged	true	Whether logs with no tags are kept when enabledTags is narrowed.
printToConsole	kDebugMode	Console output.
includeCurrentStackTrace	false	Attach a stack trace to every log, not just ones you pass one to.
captureDeviceInfo	true	Record device model, OS name and version.
captureAppContext	true	Record your app’s version and build number.
sessionSampleRate	1.0	Share of launches recorded at all. See Controlling Volume.

ProjectCredentials

Where to send it. Omit entirely to stay local.

Option	Description
link	Your server’s base URL. Absolute, and it must end in /.
projectID	The project UUID from the dashboard.
projectSecret	That project’s secret.

Both credentials travel as headers, X-Project-ID and X-Project-Secret, on every request, and are checked against the server’s project_secrets table.

Caution

The secret is embedded in your app, so treat it as a write credential, not a password. It can upload logs to one project. It cannot read them back, and it grants nothing on the dashboard. Rotate it from Project settings → SDK setup if a build leaks.

LogSyncBehavior

When to upload.

Option	Default	Description
syncInterval	5 minutes	How often the worker looks for pending logs.
maxBatchSize	100	Most logs in one upload.

The worker marks logs as syncing, compresses them in a background isolate, uploads, and deletes them on success, rolling back on failure so nothing is lost.

After five failures in a row it goes quiet for five minutes and then tries again by itself. It pauses, it does not stop, so a server that was down for a minute does not cost you every log until somebody restarts the app.

A 429 or 503 is not counted as a failure at all. The worker reads Retry-After, waits for that long, and resumes, so a server protecting itself can never push the SDK into that pause. The wait is clamped to between one second and 24 hours whatever the header says.

A 413 means the batch was too large for the server to accept. The SDK halves its batch size and the next cycle tries again with a smaller one, halving again if it has to, and growing back once an upload succeeds.

Caution

sync has no default. Without it nothing is uploaded, and nothing is kept either: the SQLite write is the uploader’s queue rather than a store anything reads back, so it is skipped when there is no uploader. Logs still print to the console and fill the in-app panel for the current launch, then go. Adding sync: later recovers nothing. The only complaint is one line in the debug console.

RedactionBehavior

What must never leave the device. Opt-in: see Redaction and Privacy.

Option	Default	Description
headers	{}	Header names to strip.
bodyKeys	{}	Body and metadata keys to strip, at any depth.
maxBodyBytes	32 KB	Bodies larger than this are truncated. 0 disables.

RealTimeConfig

Option	Default	Description
enableLiveStreaming	true	Whether this app may be paired with for live streaming.

Set it to false and the app refuses to join a live session however the request arrives. The Go live control disappears from the in-app panel, and startLiveSession() returns false without attempting a connection, so an app that never wants to be watched cannot be.

Local-only mode

With no projectCredentials, CodeScout is a complete on-device logger: console output and the in-app overlay, which holds the last 500 logs of the current launch. Sync and live streaming stay off, silently, with nothing to configure and no errors to ignore.

Nothing is written to SQLite in this mode, and that is deliberate rather than missing. The SQLite table is the uploader’s queue, not a store anything reads back, so with no uploader to drain it every log an app ever wrote would sit on the user’s phone for good.

This is the intended way to start. Add the dashboard when you want one.

Uploading straight away

Logs are batched and uploaded on syncInterval. When you want them gone now rather than at the next tick, await flush():

await CodeScout.instance.flush();

It completes once the batch has either landed or failed. Everything the scheduled upload does still applies, so calling it while one is already running does not start a second, and nothing is deleted from the device until the server has taken it.

The two moments worth calling it are when the app is about to stop being able to, such as going to the background, and on sign out.