| Option | Type | Default | Required | Description |
|---|
projectId | string | — | Yes | Project identifier, auto-creates in desktop app |
apiKey | string | — | Yes | API key (any string works for local mode) |
mode | "local" | "desktop" | "cloud" | — | Yes | Determines endpoint URL |
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) |
fetch | function | globalThis.fetch | No | Custom fetch implementation |
isDebug | boolean | false | No | Disables gzip compression |
| Mode | URL |
|---|
local | http://localhost:17655 |
desktop | http://localhost:8787 |
cloud | https://api.gunsole.com |
| 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 | Record<string, string> | No | Filterable key-value pairs (strings only) |
traceId | string | No | Links related log entries |
These are set automatically by the SDK and sent with every log:
| Field | Source |
|---|
level | Determined by method: info(), debug(), warn(), error() |
timestamp | Date.now() (unix milliseconds) |
userId | From gun.setUser({ id: "..." }) |
sessionId | From gun.setSessionId("...") |
env | From config |
appName | From config |
appVersion | From config |
| Setting | Default | Description |
|---|
| Log retention (days) | Unlimited | Auto-delete logs older than N days |
| Auto-delete old logs | Off | Enable/disable retention enforcement |
| Setting | Default | Description |
|---|
| Log retention (days) | Inherits project | Override project retention per bucket |
| Setting | Options | Description |
|---|
| Theme | Light / Dark / Auto | UI color scheme |
| Setting | Value |
|---|
| Default port | 17655 |
| Host | localhost only |
| CORS | Enabled (all origins) |
| Compression | gzip accepted on request body |
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 |
| Setting | Value |
|---|
| Engine | SQLite |
| Location (macOS) | ~/Library/Application Support/gunsole/gunsole.db |
| Location (Linux) | ~/.local/share/gunsole/gunsole.db |
| Location (Windows) | %APPDATA%\gunsole\gunsole.db |
| Foreign keys | Enabled |
| Migrations | Auto-run on startup |
