Configuration Reference

SDK configuration

`createGunsoleClient(config)`

Option	Type	Default	Required	Description
`projectId`	`string`	—	Yes	Project identifier, auto-creates in desktop app
`mode`	`"local" \| "desktop" \| "cloud"`	—	Yes	Determines endpoint URL
`apiKey`	`string`	—	No	API key (required for cloud mode)
`endpoint`	`string`	—	No	Override endpoint URL
`env`	`string`	—	No	Environment label
`appName`	`string`	—	No	Application name
`appVersion`	`string`	—	No	Application version
`defaultTags`	`Record<string, string>`	`{}`	No	Tags merged into every log
`batchSize`	`number`	`10`	No	Logs before auto-flush
`flushInterval`	`number`	`5000`	No	Auto-flush interval (ms)
`maxQueueSize`	`number`	`1000`	No	Drop oldest entries when exceeded
`maxLogRate`	`number`	`10`	No	Logs per second (token bucket, 0 = unlimited)
`maxBurst`	`number`	`100`	No	Burst allowance for rate limiting
`buckets`	`string[]`	—	No	Typed bucket accessors with autocomplete
`beforeSend`	`(entry) => entry \| null`	—	No	Transform or drop logs before batching
`hooks`	`object`	—	No	Lifecycle hooks (see below)
`isDisabled`	`boolean`	`false`	No	Kill switch — disables all logging
`isDebug`	`boolean`	`false`	No	Disables gzip compression
`sessionId`	`string`	auto-generated	No	Override auto-generated session ID
`fetch`	`function`	`globalThis.fetch`	No	Custom fetch implementation

Lifecycle hooks

hooks: {
  onLog: (entry) => void;         // Called after log is added to queue
  onFlush: (logs, success) => void; // Called after batch flush attempt
  onError: (error) => void;       // Called on flush failure
}

Endpoint modes

Mode	URL
`desktop`	`http://localhost:17655`
`local`	`https://local.gunsole.com`
`cloud`	`https://api.gunsole.com`

Log entry fields

`LogOptions` (what you pass to `gunsole.info()`, etc.)

Field	Type	Required	Description
`message`	`string`	Yes	Human-readable log message
`bucket`	`string`	Yes	Category name (auto-created)
`context`	`Record<string, unknown>`	No	Arbitrary structured data
`tags`	`Partial<Tags> \| TagEntry<Tags>[]`	No	Filterable key-value pairs
`traceId`	`string`	No	Links related log entries

`BucketLogOptions` (what you pass to `gunsole.payment()`, etc.)

Field	Type	Required	Description
`context`	`Record<string, unknown>`	No	Arbitrary structured data
`tags`	`Partial<Tags> \| TagEntry<Tags>[]`	No	Filterable key-value pairs
`traceId`	`string`	No	Links related log entries

Auto-populated fields

These are set automatically by the SDK and sent with every log:

Field	Source
`level`	Determined by method: `info()`, `debug()`, `warn()`, `error()`, `fatal()`
`timestamp`	`Date.now()` (unix milliseconds)
`userId`	From `gunsole.setUser({ id: "..." })`
`sessionId`	From `gunsole.setSessionId("...")` or auto-generated
`env`	From config
`appName`	From config
`appVersion`	From config

Reserved names

Reserved bucket names

Cannot be used with buckets config option:

log, info, debug, warn, error, fatal,
setUser, setSessionId, setDebug, flush, destroy, isDestroyed,
drainBatch, projectId, apiKey, logEndpoint,
attachGlobalErrorHandlers, detachGlobalErrorHandlers

Reserved tag keys

Cannot be used as tag schema keys:

bucket, message, level, timestamp, userId, sessionId, env, appName, appVersion

TypeScript exports

Runtime

Export	Description
`createGunsoleClient`	Factory function to create client
`GunsoleClient`	Client class
`persistSession`	(@gunsole/web) Cookie-based session persistence

Types

Export	Description
`GunsoleClientConfig`	Configuration options
`LogEntry`	Log entry structure
`LogLevel`	`"info" \| "debug" \| "warn" \| "error" \| "fatal"`
`LogOptions`	Options passed to log methods
`TagEntry`	Single-key tag entry type
`UserInfo`	User information
`ClientMode`	`"cloud" \| "desktop" \| "local"`
`BucketLogOptions`	Log options for bucket methods (no bucket/message)
`BucketLogger`	Callable bucket accessor interface
`WithBuckets`	Mapped type adding bucket accessors to client
`ReservedBucketName`	Union of reserved bucket names
`ValidateBuckets`	Compile-time bucket name validator
`ReservedTagKey`	Union of reserved tag keys
`ValidTagSchema`	Compile-time tag schema constraint

TypeScript requirements

TypeScript 5.0+ required for const generic inference (bucket literal types)
TypeScript 5.4+ recommended for NoInfer (bucket name compile-time validation)
Target: ES2020

Transport details

The SDK sends logs via HTTP POST:

POST {endpoint}/logs
Content-Type: application/json
Content-Encoding: gzip
X-Gunsole-SDK-Version: 0.2.0
Authorization: Bearer {apiKey}    // only in cloud mode

Retry behavior: 3 attempts with exponential backoff (1s, 2s, 4s) + jitter (0.5-1.5x). HTTP 413 splits the batch and retries. 4xx (except 429) are not retried. Logs are dropped after 10 consecutive flush failures.

Desktop app settings

Project settings

Setting	Default	Description
Log retention (days)	Unlimited	Auto-delete logs older than N days
Auto-delete old logs	Off	Enable/disable retention enforcement

Bucket settings

Setting	Default	Description
Log retention (days)	Inherits project	Override project retention per bucket

App preferences

Setting	Options	Description
Theme	Light / Dark / Auto	UI color scheme

HTTP server

Setting	Value
Default port	`17655`
Host	`localhost` only
CORS	Enabled (all origins)
Compression	gzip accepted on request body

Internal constants

These are compiled into the desktop app and not user-configurable:

Constant	Value	Description
Log batch size	50	Max logs per flush to DB
Batch interval	100ms	Max time between DB flushes
Frontend buffer	~2000 logs	Max in-memory logs in viewer
New log animation	3 seconds	Green fade duration for new entries

Database

Setting	Value
Engine	SQLite (WAL mode)
Location (macOS)	`~/Library/Application Support/gunsole/gunsole.db`
Location (Linux)	`~/.local/share/gunsole/gunsole.db`
Location (Windows)	`%APPDATA%\gunsole\gunsole.db`
Tables	workspaces, projects, buckets, filters, logs, tags, log_tag_map, app_preferences
Foreign keys	Enabled
Migrations	Auto-run on startup