Purpose and Scope: This document describes the event logging and telemetry systems in AnythingLLM. Event logging provides an audit trail of administrative actions and security events, while telemetry collects optional usage statistics. For authentication-specific details, see Authentication System. For multi-user management actions that generate events, see Multi-User Management.
AnythingLLM implements two separate tracking systems:
Event logs are always enabled and stored locally, while telemetry is opt-in and sends data externally.
Sources: server/endpoints/system.js1-1400 frontend/src/models/system.js629-651
The EventLogs model provides the primary interface for logging events. It is imported from server/models/eventLogs and used throughout the backend.
Core Methods:
| Method | Signature | Purpose |
|---|---|---|
logEvent | (eventType, metadata, userId?) | Records a new event with optional metadata and user context |
whereWithData | ({}, limit, offset, orderBy) | Queries event logs with pagination and sorting |
count | () | Returns total count of event logs |
delete | ({}) | Clears all event logs (admin only) |
Sources: server/endpoints/system.js44 server/endpoints/admin.js3
Authentication Event Logging:
failed_login_invalid_username - Logged when username doesn't exist. Metadata includes ip and attempted username.
failed_login_invalid_password - Logged when password doesn't match. Metadata includes ip and username.
failed_login_account_suspended - Logged when user account is suspended. Metadata includes ip and username.
login_event - Logged on successful authentication. Metadata includes ip and username. Also logged for multi-user mode status.
failed_login_invalid_temporary_auth_token - Logged when SSO temporary token validation fails.
Sources: server/endpoints/system.js183-377
User Management Event Details:
user_created - Logged when a new user is created. Metadata: userName, createdBy (admin username).
user_deleted - Logged when a user is deleted. Metadata: userName, deletedBy (admin username).
invite_created - Logged when an invite code is generated. Metadata: inviteCode, createdBy.
invite_deleted - Logged when an invite is deactivated. Metadata: deletedBy.
Sources: server/endpoints/admin.js49-221
API key creation and deletion generate audit events:
api_key_created - Logged when a new API key is generated. Metadata: createdBy (username, if available).
api_key_deleted - Logged when an API key is deleted. Metadata: deletedBy (username).
api_user_deleted - Logged when a user is deleted via API. Metadata: userName.
Sources: server/endpoints/system.js1029-1082 server/endpoints/admin.js453-495 server/endpoints/api/admin/index.js215-267
multi_user_mode_enabled - Logged when multi-user mode is activated. No specific metadata beyond the enabling user.
event_logs_cleared - Logged when an administrator clears the event log history. Creates a meta-log entry.
Sources: server/endpoints/system.js591-644 server/endpoints/system.js1126-1143
Each event log entry contains:
| Field | Type | Description |
|---|---|---|
id | Integer | Auto-incrementing primary key |
eventType | String | Event type identifier (e.g., "login_event") |
metadata | JSON | Arbitrary JSON object with event-specific data |
userId | Integer (nullable) | Associated user ID, if applicable |
createdAt | Timestamp | When the event was recorded |
The metadata field is flexible and varies by event type. Common fields include:
ip - IP address (for authentication events)username - Username involved in the eventcreatedBy / deletedBy - Admin who performed the actionSources: server/endpoints/system.js203-320
The EventLogs.whereWithData() method supports paginated queries:
Parameters:
{} for all logs){ id: "desc" } for newest first)Sources: server/endpoints/system.js1106-1123
The frontend System model provides methods to interact with event logs:
API Endpoints:
/system/event-logs - Fetch paginated event logs/system/event-logs - Clear all event logsSources: frontend/src/models/system.js629-651
Key Differences:
| Aspect | Event Logs | Telemetry |
|---|---|---|
| Status | Always enabled | Optional (opt-in) |
| Storage | Local database | External service |
| Purpose | Audit trail, security | Product analytics |
| Data Retention | Permanent (until cleared) | N/A (sent externally) |
| Visibility | Admin UI accessible | Not accessible to users |
| Privacy | Contains identifying info | Anonymous |
Sources: server/endpoints/system.js256-260 server/endpoints/system.js316
The Telemetry model is imported from server/models/telemetry and provides a single method:
Telemetry Events Sent:
login_event - Sent on successful login (both single and multi-user modes)
{ multiUserMode: boolean }enabled_multi_user_mode - Sent when multi-user mode is first enabled
{ multiUserMode: true }Telemetry is intentionally limited to high-level feature usage tracking and does not include sensitive data like usernames, passwords, IP addresses, or document content.
Sources: server/endpoints/system.js183-644
Event logs are accessible from the admin settings interface:
Navigation Path: Settings → Tools → Event Logs
Route: /settings/event-logs (defined as paths.settings.logs())
Access Control: Admin role only (ROLES.admin)
Sources: frontend/src/components/SettingsSidebar/index.jsx366-369 frontend/src/utils/paths.js152-154
The event log viewer displays:
Pagination is controlled by offset, with 10 events per page by default.
Sources: server/endpoints/system.js1106-1123 frontend/src/models/system.js629-651
When an administrator clears event logs:
/system/event-logs endpoint is calledEventLogs.delete() removes all existing logsevent_logs_cleared event is logged (meta-event){ success: true } on completionThis creates a permanent record that logs were cleared, preventing tampering without evidence.
Sources: server/endpoints/system.js1126-1143 frontend/src/models/system.js641-651
Event logs are also accessible via the API:
POST /v1/admin/workspace-chats - While named for workspace chats, this endpoint demonstrates the pagination pattern used for event logs.
Parameters:
Response:
Event logs follow the same pattern with logs, hasPages, and totalLogs fields.
Sources: server/endpoints/api/admin/index.js662-716 server/endpoints/system.js1106-1123
Event logs are designed to provide tamper-evident audit trails:
event_logs_cleared event ensures deletion is recordedEvent log access is strictly controlled:
flexUserRoleValid([ROLES.admin]))Sources: server/endpoints/system.js1108 server/endpoints/system.js1128 frontend/src/components/SettingsSidebar/index.jsx366-369
Event logs may contain personally identifiable information (PII):
Administrators should:
Sources: server/endpoints/system.js203-320
Events should be logged for:
Effective event metadata includes:
createdBy, deletedBy, usernameip, workspaceId, documentIdsuccess, error (for auditing failed operations)Avoid logging:
Sources: server/endpoints/system.js203-320 server/endpoints/admin.js67-215
| Feature | Implementation | Purpose |
|---|---|---|
| Event Logs | EventLogs model, event_logs table | Audit trail and security monitoring |
| Telemetry | Telemetry model, external service | Anonymous usage analytics |
| Event Types | 15+ predefined events | Authentication, user management, API operations |
| Frontend UI | /settings/event-logs | Admin interface for viewing/clearing logs |
| API Access | POST/DELETE /system/event-logs | Programmatic log access |
| Access Control | Admin role required | Prevents unauthorized log access |
Event logging provides comprehensive audit capabilities for AnythingLLM instances, while telemetry offers opt-in product analytics without compromising privacy.
Sources: server/endpoints/system.js1-1400 server/endpoints/admin.js1-500 frontend/src/models/system.js629-651 frontend/src/components/SettingsSidebar/index.jsx366-369
Refresh this wiki