auditlog

auditlog

A PocketBase plugin that records an audit trail of the changes made to your collections.

[!WARNING] This plugin's admin UI is built on PocketBase's UI extensions mechanism, which is still under active development. Expect this plugin's UI to require breaking changes to keep up as PocketBase's own extension APIs evolve.

Installation

With xpb

Include the adapters/xpb submodule when building your PocketBase binary. It registers itself automatically, so no extra code is required:

xpb build --with github.com/pocketbasestore/auditlog/adapters/xpb

The adapter lives in its own Go module so that plain library consumers (below) don't pull in xpb's dependencies. It is configured through pocketbuilds.toml or environment variables — see Configuration.

As a library

Import the package and register it against your app instance. Use MustRegister to panic on failure, or Register to handle the error yourself:

package main

import (
	"log"

	"github.com/pocketbase/pocketbase"

	"github.com/pocketbasestore/auditlog"
)

func main() {
	app := pocketbase.New()

	auditlog.MustRegister(app)

	// or, handling the error explicitly:
	// if err := auditlog.Register(app); err != nil {
	// 	log.Fatal(err)
	// }

	if err := app.Start(); err != nil {
		log.Fatal(err)
	}
}

Settings are passed as registration options — see Configuration.

Configuration

• Log retention — how many days audit log entries are kept before the daily cleanup cron deletes them. 0 keeps them forever.
• Excluded collections — every collection is audited by default; this is a blocklist of the ones to leave out. Collections are referenced by name and resolved to ids at seed time, so a name that doesn't match an existing collection at first boot is skipped with a warning.

Which mechanisms are available depends on how the plugin is installed, and the two sets don't overlap: a binary built with xpb reads pocketbuilds.toml and environment variables, while a library consumer passes registration options in code.

Whatever the source, these only seed a setting's initial value on first boot. Afterwards the values stored in the _auditLogSettings collection — editable from the plugin's settings modal in the admin UI — are the source of truth, and these sources are ignored.

With xpb, a setting can come from either source, and the precedence is env > pocketbuilds.toml > default:

# pocketbuilds.toml
[auditlog]
initial_retention_days = 60
initial_excluded_collections = ["posts", "comments"]

# environment variables
XPB__AUDITLOG__INITIAL_RETENTION_DAYS=60
XPB__AUDITLOG__INITIAL_EXCLUDED_COLLECTIONS=posts,comments

As a library, the equivalent is:

auditlog.MustRegister(app,
	auditlog.WithInitialRetentionDays(60),
	auditlog.WithInitialExcludedCollections("posts", "comments"),
)

Caveats

• Best effort, not atomic. Audit log writes are best effort and are not transactionally tied to the change they describe. If writing the audit entry fails, the error is logged and the original operation still succeeds — so a change may occur without a corresponding audit log entry. Do not rely on this plugin as a guaranteed, tamper-proof record.
• API changes only. Only record mutations that go through the REST API (create / update / delete request hooks) are logged. Changes made programmatically from Go (e.g. app.Save(...)), from cron jobs, or from migrations bypass these hooks and are not recorded.