What to log

The hardest part of integrating Recalled is not the SDK call, it is deciding what is worth logging. Log too little and your audit trail is useless. Log too much and you blow your quota, slow your app and drown the signal in noise.

This page is the opinionated guide. Follow these rules and you will have a clean, useful, compliant audit log without thinking about it.

The 3 rules

1. Log state changes, not reads. A user reading their dashboard 50 times a day is not an audit event. A user changing their email address once is. If the action does not mutate something in your system or in the user's account, it does not belong in Recalled.

2. Log actions with consequences, not technical noise. A failed health check, a cache miss, a 304 response, a CDN purge: not audit events. They belong in your APM tool. Recalled is for actions a human or an auditor would care about in 6 months.

3. Log what tells a story. Imagine someone in 6 months asking "who deleted this invoice and why". The answer must come from a single event: the actor, the target, the reason if any, the IP, the time. If your log entry does not let you reconstruct the story, it is incomplete.

Decision flowchart

When you are about to add a client.events.create() call somewhere, ask:

1. Does this change a piece of state in our system? No → do not log.
2. Would the legal, support or security team ever ask "who did this and when"? No → do not log.
3. Is the cardinality reasonable? (less than 10 events per active user per session) Yes → log it. No → consider sampling or aggregating client-side.

If you answer yes to 1 and 2 and the cardinality is reasonable, log it. Otherwise skip it.

Catalogue by category

The standard list of what most B2B and B2C SaaS should log. Pick the categories that apply to your product, copy the action names, adapt to your domain. Each tab carries the events to log, the ones to skip, and a metadata hint.

Naming conventions

Follow this schema for everything: <domain>.<subject>.<verb_past_tense> or <domain>.<verb_past_tense> when there is no separate subject.

Rules:

1. All lowercase, dot-separated, snake_case if needed inside a segment.
2. Past tense verbs: .created not .create, .updated not .update, .deleted not .delete.
3. Domain first, subject second, verb last: invoice.line_item.added is better than added.invoice.line_item.
4. Be consistent: pick a verb and stick with it. Do not mix .deleted and .removed for the same domain. Do not mix .failed and .errored.
5. Keep it stable: action names end up in your dashboards, retention rules and notification filters. Renaming them later breaks history.

Standard verbs to reach for, ranked by frequency:

Metadata schema

metadata is a free-form JSON object. Keep it small (a few hundred bytes is plenty), structured, and useful in 6 months. The patterns below work across most action categories.

Always include when relevant

• source: where the action came from. Values: web, mobile, api, admin_panel, automation, import, webhook.
• reason: free text reason if the user or admin provided one (metadata.reason: "duplicate").
• request_id: your own correlation id for tracing back to logs.
• result: success or failure. Default to success so you can filter failures later.

For updates

{
  "metadata": {
    "changed_fields": ["status", "due_date"],
    "before": { "status": "draft" },
    "after": { "status": "paid" }
  }
}

Only include the changed fields, not the full object. If the diff is huge, just keep changed_fields and skip before/after.

For money

Always serialise amounts in integer cents (or smallest currency unit), never floats:

{
  "metadata": {
    "amount_cents": 4200,
    "currency": "EUR",
    "stripe_payment_intent_id": "pi_..."
  }
}

For failures

{
  "metadata": {
    "result": "failure",
    "reason": "card_declined",
    "code": "insufficient_funds"
  }
}

Antipatterns

Do not put any of these in metadata:

• Plaintext secrets, passwords, full tokens, full credit card numbers. If it should not be in your logs, it should not be in Recalled.
• Full document bodies, file contents, blobs, images. Recalled is not a document store. Put the resource id in targets and let the consumer fetch the body if they need it.
• PII you do not need. If you log an action on a user, you already have actor.id. You do not also need their full address, phone number, etc. Less PII = less GDPR exposure.
• Server-side debug data. Stack traces, SQL queries, internal IDs that mean nothing to a human auditor. Send those to your APM.
• Anything bigger than ~2 KB. Large metadata slows down list queries and inflates your storage bill.

Volume guidance

Recalled bills by event count per month. The right ratio for most B2B SaaS:

• 1 to 5 events per active user per session (login, a couple of actions, logout)
• 0 events when a user is just reading
• A handful per day for system actions (cron, billing, backups)

If you find yourself logging more than 10 events per active user per day, you are probably over-logging reads or capturing technical noise. Re-read the 3 rules at the top.

Worked example

A fictional B2B invoicing SaaS. Here is the complete list of events its team would push to Recalled. Notice how it stays focused.

# Auth (5)
user.signed_up
user.logged_in
user.logged_out
user.login_failed
user.password_changed

# Team (4)
member.invited
member.joined
member.removed
member.role_changed

# Invoices, the core business object (6)
invoice.created
invoice.updated
invoice.sent
invoice.paid
invoice.refunded
invoice.deleted

# Customers (3)
customer.created
customer.updated
customer.deleted

# Billing for the SaaS itself (4)
subscription.created
subscription.plan_changed
subscription.canceled
payment_method.added

# Admin (2)
admin.impersonation_started
admin.impersonation_ended

# Exports (2)
export.started
export.completed

That is 26 distinct actions, more than enough for a clean audit trail. Your real list will be similar in size.

Next step

Once you have your list, drop it in the Events API and start sending. The dashboard's list_actions_summary tool helps you see in real time which actions you are logging the most, so you can spot over-logging or gaps.