Emitting Activity Events
Lesli Core exposes account and user logging methods when LesliAudit is installed. Both methods return without writing when enable_logs is false. When logging is enabled, persistence errors are intentionally raised.
User Events
Use Lesli::User#log for an operation performed by or specifically associated with a user:
current_user.log(
engine: MyEngine,
source: self.class.name,
action: action_name,
operation: "ticket_closed",
description: "Ticket closed successfully",
session_id: session[:user_session_id],
subject: ticket,
details: { status: ["open", "closed"] }
)
The service stores only this allowlisted metadata:
| Field | Purpose |
|---|---|
engine | Engine or subsystem that owns the operation |
source | Controller, service, or job that emitted it |
action | Source action or method |
operation | Required stable event name |
description | Human-readable explanation without secrets |
session_id | Optional opaque session reference |
subject | Optional record whose type and ID are snapshotted |
details | Explicit domain data stored as a JSON object; defaults to {} |
The user's uid is copied into actor_uid. This snapshot remains available if the user is later hard-deleted and the nullable user reference is cleared.
details must be a Hash constructed by the emitting service. Use it for before/after values, stable resource identifiers, permission differences, or counts needed to explain the operation. Both user and account event tables support it through ActivityAudit. The event detail view shows this JSON without interpreting its keys, keeping LesliAudit independent of each domain.
Controllers inheriting from Lesli::ApplicationLesliController can use its convenience method, which supplies engine, source, action, session, and user:
log(
operation: "ticket_closed",
description: "Ticket closed successfully",
subject: ticket
)
Account Events
Use Lesli::Account#log for tenant-level lifecycle operations:
account.log(
"billing_policy_changed",
"Billing policy updated",
user: current_user
)
The optional user: argument records the actor and its immutable UID snapshot.
Choose the event type from the subject of the evidence, not only from the actor:
- use
User#logwhen the history belongs to a specific user, such as a profile change, authentication outcome, or user permission change; - use
Account#logwhen the history belongs to the tenant, such as account initialization, a global policy change, or an account-wide security action.
An account event may still have a user actor. Conversely, do not emit both types for the same operation unless the product genuinely requires two independent audit histories.
Transaction Boundary
For an operation that requires audit evidence, write the business change and the event in the same database transaction:
Ticket.transaction do
ticket.update!(status: "closed")
current_user.log(
engine: MyEngine,
source: self.class.name,
action: "close",
operation: "ticket_closed",
description: "Ticket closed successfully",
subject: ticket
)
end
Do not rescue and discard an audit persistence error inside this transaction. If the event cannot be stored, the business change must roll back as well.
Event Naming and Sensitive Data
Use stable, past-tense operation names such as ticket_closed and distinct names for lifecycle outcomes such as session_creation_attempted, session_creation_failed, and session_creation_succeeded.
Never place credentials, tokens, cookies, authorization headers, request parameters, raw user-agent strings, or unrestricted serialized payloads in the description or details. Construct a small domain-specific Hash for details instead of passing params, a complete model's attributes, or JSON encoded inside the description. Events, including their details, remain append-only.
Requests and journals must never be promoted into activity events after the fact. Their presence proves that Rails observed a request, not that the intended business operation completed. Emit the log from the code that knows the final outcome.
Last Update: 2026/11/12