Projects & Buckets

Projects

A project maps to one of your applications. When you set projectId: "my-api" in the SDK, the desktop app creates a project called my-api automatically the first time it receives a log.

You don’t register projects. You don’t configure them ahead of time. Just send a log with a projectId and it exists.

Projects appear in the sidebar. You can:

• Rename them (the projectId from the SDK stays the same, just the display name changes)
• Move them between workspaces
• Delete them (deletes all their logs, buckets, and filters)
• Configure log retention per project

Log retention

By default, logs are kept forever. You can set a retention period per project:

• Go to Settings → Projects → [your project]
• Set Log retention days (e.g., 7 days)
• Enable Auto-delete old logs

Logs older than the retention period are purged automatically.

---

Buckets

Buckets are categories within a project. Think of them as labels or namespaces for different types of logs.

// These create three separate buckets under the same project
gun.info({ bucket: "api", message: "Request received" });
gun.info({ bucket: "db", message: "Query executed" });
gun.info({ bucket: "auth", message: "User authenticated" });

Buckets are auto-created on first use, just like projects. In the desktop app, you can filter logs by bucket — show only api logs, or only db logs, or both.

Good bucket names

Think of buckets as the high-level areas of your app:

Bucket	Use for
api	HTTP request/response logs
db	Database queries, connections
auth	Authentication, authorization
jobs	Background jobs, cron tasks
cache	Cache hits, misses, invalidations
ui	Frontend interactions, state changes
perf	Performance metrics, timing
errors	Catch-all for errors (or use the error level instead)

Don’t over-bucket. 3-8 buckets per project is the sweet spot. If you have 50 buckets, you probably want 50 tags instead.

Bucket-level retention

You can override the project’s retention period per bucket. Useful when you want to keep error logs longer than debug logs:

• Go to Settings → Projects → [your project]
• Set per-bucket retention in the bucket settings section

---

The mental model

my-api (project)
├── api (bucket)
│   ├── [info] GET /users → 200
│   ├── [error] POST /orders → 500
│   └── ...
├── db (bucket)
│   ├── [debug] SELECT * FROM users WHERE id = ?
│   └── ...
└── auth (bucket)
    ├── [info] User u_123 logged in
    └── ...

Projects are your apps. Buckets are categories within those apps. Logs are the actual entries, each with a level, message, context, and tags.