Audit Logs

Audit logs are a Flocks Pro feature for recording and querying key system operations. They help administrators trace who did what, when it happened, which resources were affected, and whether the operation succeeded.

1. Purpose

Audit logs answer the question "How can important operations in the platform be traced?" In the Pro edition, account management, License operations, login and logout, session creation and deletion, tool calls, model calls, and some HTTP / Session lifecycle events are written to audit records.

Audit logs are suitable for:

• Security auditing.
• Administrator operation tracing.
• Troubleshooting.
• Compliance evidence.
• Review of account and authorization changes.

2. Permissions and Editions

Audit logs are supported only in Flocks Pro, and usually only administrators can view them.

If the current environment is not Pro, or Pro is not enabled, the page indicates that the current edition does not support audit logs.

3. Page Capabilities

The audit log page supports:

• Viewing the audit event list.
• Filtering by event type.
• Filtering by operator username.
• Filtering by operator ID or user ID.
• Filtering by resource type.
• Filtering by result, such as success or failure.
• Filtering by start time and end time.
• Paginated viewing.
• Expanding payload / metadata details.
• Downloading Excel.

Table fields usually include:

Field	Description
Time	Time when the event occurred.
Event	event_type, such as account.user.create or license.activate.
Operator	Username, user ID, or actor information.
Resource	Resource type and resource ID that were operated on.
Session	Related session_id, useful for tracing a session, IM conversation, or sub-agent execution.
Provider / Model	Model Provider and model ID recorded in model call events.
Tokens / Cost	Token usage and estimated cost recorded in model call events.
Result	Success or failure.
Details	payload or metadata.

4. Common Events

4.1 Account Login Events

Account login, logout, and failed login are audited:

Event Type	Description	Typical Resource
account.login	User login succeeded.	Login Session.
account.login_failed	User login failed. The payload usually contains the username, failure reason, and source IP.	Login attempt.
account.logout	User logged out.	Login Session.

These events are useful for investigating abnormal account logins, password retry errors, and when an account started operating the platform.

4.2 Account Management Events

Account management events include:

Event Type	Description	Typical payload
account.user.create	Administrator created a user.	target_user_id, target_role.
account.user.update_role	Administrator changed a user's role.	target_user_id, new_role.
account.user.delete	Administrator deleted a user.	target_user_id.
account.user.reset_password	Administrator reset a user's password.	target_user_id, force_reset.

Note: Administrators cannot delete the currently logged-in administrator account. Rejected operations of this type are usually returned as API errors and may not form successful audit records.

4.3 License Events

Flocks Pro authorization events include:

Event Type	Description	Typical payload
license.activate	Activate License.	license_id, status.
license.refresh	Refresh or synchronize License.	license_id, active_patch_serial.
license.deactivate	Deactivate the local License.	Usually empty or contains authorization status.
license.import_revocation	Import revocation list.	Imported count.

These events are useful for investigating when Pro authorization was activated, whether refresh succeeded, and whether revocation information was imported.

4.4 Session Events

Session-related events come from the Flocks core audit bridge:

Event Type	Description	Typical payload
session_action	Session action event, mapped to a session.<action> category and its corresponding action.	project_id.
session.create	Session creation event recorded through a lifecycle hook.	Session ID.
session.delete	Session deletion event recorded through a lifecycle hook.	Session ID.
Other session.*	Other lifecycle events that start with session..	Session ID or event attributes.

In the API paths for session creation and deletion, Flocks emits session_action, where action may be create or delete. The Pro audit bridge classifies it under session, with resource type session and resource ID usually set to session_id.

4.5 Tool Call Events

Tool calls are recorded by the Pro lifecycle hook:

Event Type	Description	Typical Fields
tool_call.execute	A tool finished executing.	resource_type=tool, resource_id=tool name, session_id, execution result.

To avoid leaking sensitive data through audit logs, tool call audits do not save full tool inputs and outputs. The payload usually contains only summaries such as Agent, tool call ID, and result title.

These events are useful for answering:

• Which tools were called in a Session.
• Whether a tool fails frequently.
• Whether an Agent triggered high-risk tools.

4.6 Model Call Events

Model calls are recorded by the Pro lifecycle hook:

Event Type	Description	Typical Fields
llm_api_call.after	Audit event after a model call completes.	provider, model, tokens, estimated_cost, session_id.

The payload usually contains summaries such as Agent, execution step, duration, finish reason, and number of tool calls. It does not save the full Prompt or model output.

These events are useful for model usage statistics, investigating whether a model fails frequently, and estimating Token usage and cost.

4.7 HTTP Request Events

The Flocks core audit bridge writes some HTTP request events to Pro audit:

Event Type	Description	Typical Fields
http_request	HTTP request captured by core audit.	method, path, status, duration_ms.

When the HTTP status code is 400 or higher, the audit result is marked as failed. The resource type is usually http, and the resource ID is usually the request path.

4.8 Suppressed Events

The Pro audit sink suppresses api_call.request and does not write it to the audit list by default. This avoids large volumes of low-level API request noise that would make it harder for administrators to review key operations.

5. Audit Fields and Storage

5.1 Audit Event Fields

Audit events share these core fields:

Field	Description
event_type	Event type, such as account.login or tool_call.execute.
category / action	Event category and action, usually split from event_type.
status / result	Status and result. result is usually success or failed.
user_id / user_name	User related to the event.
actor_id / actor_name	Actual operator.
resource_type / resource_id	Type and ID of the operated resource.
session_id	Related Session.
ip / trace_id	Source IP and trace ID.
provider / model	Provider and model related to the model call.
tokens / estimated_cost	Token usage and estimated cost of the model call.
payload / metadata	Event summary details.
created_at	Time when the event was written.

5.2 Storage and Forwarding

Pro audit writes to the local SQLite audit_events_v1 table by default. The system creates indexes for time, operator, event type, user ID, and resource type to make filtered queries efficient.

If FLOCKSPRO_AUDIT_WEBHOOK is configured, audit events are also sent asynchronously to the webhook for integration with external SIEM, logging platforms, or compliance systems. Webhook failures do not block the main platform flow.

6. Usage

6.1 Query Events

Open System Center → Audit Logs, select filters, and click query. Common troubleshooting approaches:

• Query recent operations by administrator username.
• Query account changes or authorization changes by event type.
• Query user, license, session, tool, or http by resource type.
• Trace tool and model calls for a session by Session ID.
• Query operations around an abnormal event by time range.
• Query failed events by result.

6.2 Export Logs

Click Download Excel to export the current query results. Exporting is useful for audit delivery, incident review, or compliance retention.

6.3 View Details

Expand a row to view payload or metadata. This usually includes details such as target user, License ID, resource ID, changed role, tool call summary, and model call summary.

7. FAQ

7.1 Why is the audit log entry point not visible?

Possible causes:

• The current edition is not Pro.
• Pro is not enabled.
• The current user is not an administrator.

Regular users do not see audit log navigation. On the account management page, they can only see their own account.

7.2 Where are audit logs stored?

The Pro audit service uses the local SQLite sink by default to store audit events and provides query interfaces. In specific deployments, it can also be extended to external audit systems through webhooks.

7.3 Do audit logs save Prompts, tool inputs and outputs, or sensitive content?

Audit logs focus on operation summaries, not complete business replay. Tool call and model call events do not save complete tool inputs, complete tool outputs, complete Prompts, or complete model outputs by default, to avoid writing sensitive data into the audit table.

If complete business results need to be saved, have Agent or Workflow write the report to Workspace and manage it according to project permissions.

7.4 Can audit logs replace business reports?

No. Audit logs record system operations. They are not alert triage reports, inspection reports, or Workflow run reports. Business artifacts should still be written to Workspace.

7.5 Why does the list not show all API requests?

Audit logs focus on key operations and security events. Low-level api_call.request is suppressed by default and does not enter the audit list, reducing noise. For HTTP entry-layer tracing, use service access logs, backend logs, and audit logs together.

8. Related Modules

• Account Management: account operations are written to audit.
• Flocks Pro: License operations are written to audit.
• Workspace: where business artifacts and reports are stored.
• Task Center: when troubleshooting scheduled tasks, combine task execution records, Workspace artifacts, and audit logs.
• Tool Inventory: tool calls record summary audit events.
• Model List: model call events record Provider, model, Token, and estimated cost.