Documentation
¶
Overview ¶
Package activitylog emits user-activity audit logs for the Radiance service.
Every audited data mutation is rendered as a single line of JSON on stdout (consumed by Fluentd per the "User Activity Logs" PRD). Two entry points are provided:
- LogActivity — a low-coupling helper any controller/service can call directly with pre-computed field maps.
- RegisterCallbacks (see callback.go) — wires gorm Create/Update/Delete callbacks so mutations are logged automatically, without every call site remembering to log.
Immutability (PRD NFR-03): these logs are strictly WRITE-ONLY. They are emitted to stdout only and are NEVER persisted to an application table, so no HTTP controller or other application code path can update or delete a past entry. Do not add a database destination for these logs.
Index ¶
Constants ¶
const ( ActionCreate = "CREATE" ActionUpdate = "UPDATE" ActionDelete = "DELETE" ActionBulkCreate = "BULK_CREATE" ActionBulkUpdate = "BULK_UPDATE" ActionBulkDelete = "BULK_DELETE" )
Action names emitted in the "action" field of an ActivityLog. The BULK_* variants are used by the gorm callbacks when an operation targets rows via a WHERE condition rather than a single primary key (see callback.go).
const ( CurrentUserIDKey = "activitylog:current_user_id" CurrentUserCtxKey = "activitylog:current_user_ctx" )
Keys used to pass the acting user into a gorm operation so the callbacks can attribute the resulting ActivityLog. Set them per-call with gorm's Set:
db.Set(activitylog.CurrentUserIDKey, userID).Create(&model) // explicit actor db.Set(activitylog.CurrentUserCtxKey, ctx).Save(&model) // system/context flow
Actor precedence (see resolveActor):
- an explicit CurrentUserIDKey value wins;
- else, if only a context is present (system flows that carry no user header) the actor defaults to 0;
- else a WARNING is logged and the actor still defaults to 0 — logging must never block the operation.
Variables ¶
This section is empty.
Functions ¶
func LogActivity ¶
func LogActivity(actorUserID interface{}, action, entity string, entityID interface{}, oldData, newData map[string]interface{}, ctx ...interface{})
LogActivity builds an ActivityLog from the supplied fields and emits it as a single line of JSON to stdout. The timestamp is generated here in UTC and formatted as RFC3339 (e.g. 2026-06-23T10:00:00Z) — callers never pass it.
Passing nil (or a partial map) for oldData/newData is safe: nil becomes a JSON null, and only the fields provided are emitted. Sensitive columns (see sensitiveColumns) are stripped from both maps.
It is defensive by contract: any marshal/write failure — or panic — is reported to Sentry (using the optional ctx args, which helpers/sentry accepts as iris.Context / context.Context) and swallowed, so activity logging can never return an error that would block the caller's business operation.
Usage:
activitylog.LogActivity(actorUserID, activitylog.ActionUpdate, "users", user.ID,
map[string]interface{}{"email": oldEmail},
map[string]interface{}{"email": newEmail},
ctx)
func RegisterCallbacks ¶
RegisterCallbacks wires the activity-log callbacks into a gorm DB so every Create/Update/Delete automatically emits an ActivityLog without call sites having to remember to log. Call once, right after opening the connection — utils.GetDBConnection does this for the shared singleton:
db := utils.GetDBConnection() activitylog.RegisterCallbacks(db)
Create is logged AFTER the row is written (so the generated primary key is available). Update/Delete capture the previous row state in a BEFORE callback (read within the same transaction) and emit in an AFTER callback, so only operations that actually executed are logged and bulk conditions can be read from the executed SQL.
func RemoveSensitive ¶
RemoveSensitive returns a shallow copy of data with any sensitive columns (see sensitiveColumns) dropped, so secrets like passwords never reach the log sink. It is nil-safe: a nil map returns nil.
Types ¶
type ActivityLog ¶
type ActivityLog struct {
Timestamp string `json:"timestamp"`
ActorUserID interface{} `json:"actor_user_id"`
Action string `json:"action"`
Entity string `json:"entity"`
EntityID interface{} `json:"entity_id"`
OldData map[string]interface{} `json:"old_data"`
NewData map[string]interface{} `json:"new_data"`
}
ActivityLog is the JSON payload emitted (one line) per audited mutation.
old_data / new_data are intentionally map[string]interface{} to avoid coupling the logger to any concrete model. For updates a caller may pass ONLY the changed fields (partial maps); this package never diffs objects — it outputs exactly what it is given, after stripping sensitive columns.