The logs module in src/cluster_erp/modules/logs/ gives read access to three records of what happened in the system: the request activity log, the error log, and the permanent change history. The server middleware writes the activity and error logs; the core change-history hook writes the change history. The module itself adds a read API, one write route for client error reports, metadata for the screens, and privacy handlers. How the change history is written is on change history.
At a glance¶
| Item | Value | Source |
|---|---|---|
| Package | src/cluster_erp/modules/logs/ |
folder |
| Module class | Module |
src/cluster_erp/modules/logs/module.py:15 |
name / version |
logs / 0.1.0 |
src/cluster_erp/modules/logs/module.py:16-22 |
| API prefix | /api/v1/logs (ModuleBase.api_prefix) |
src/cluster_erp/core/module_base.py:37-38, src/cluster_erp/modules/logs/module.py:31-44 |
| Sub-modules | 3 with source: activity_log, error_log, change_history; the folder deleted_records holds no Python source at this commit |
folder listing |
| Tables | 2: activity_log, error_log; the change history table core_change_history belongs to the core |
__tablename__ in the two models.py files, src/cluster_erp/core/change_history.py |
| Entities in metadata | 3 keys in entities |
src/cluster_erp/modules/logs/module.py:124-130 |
| Routes | 9 route decorators in the package | grep for @...router.get/post/put/patch/delete |
| Actions | 0 ActionMeta entries |
grep "ActionMeta(" in the package |
| Migrations | 6 files | files in migrations/versions/ whose text contains one of the two table names |
| Contracts | consumes 2, produces 0 | see the section "Events and queries" |
| Web app presence | Part of the system catalogue app settings (modules auth and logs) |
src/cluster_erp/modules/app_store/catalog.json (entry settings) |
| Desktop presence | src/cluster_erp/desktop/modules/logs/ (activity_log_view.py, error_log_view.py) |
folder |
What the module does¶
- Lists and reads activity log rows: who called which method and path, the status code, the duration, and the record touched (
src/cluster_erp/modules/logs/activity_log/models.py:15-96,src/cluster_erp/modules/logs/activity_log/routes.py:18-68). - Lists and reads error log rows by id or by trace id (
src/cluster_erp/modules/logs/error_log/routes.py:47-105). - Records client crash reports from the web and desktop clients (
src/cluster_erp/modules/logs/error_log/routes.py:22-44). - Lists and reads the change history, read-only by design (
src/cluster_erp/modules/logs/change_history/routes.py:18-85).
Sub-modules¶
| Sub-module | Purpose | Main entities | Router | Source |
|---|---|---|---|---|
activity_log |
Request activity log | ActivityLog |
/activities |
src/cluster_erp/modules/logs/activity_log/routes.py:18 |
error_log |
Server and client errors | ErrorLog |
/errors |
src/cluster_erp/modules/logs/error_log/routes.py:19 |
change_history |
Read view over core_change_history |
ChangeHistory (core model) |
/change-history |
src/cluster_erp/modules/logs/change_history/routes.py:18-19 |
Data model¶
| Entity | Table | Key fields | Notes | Source |
|---|---|---|---|---|
ActivityLog |
activity_log |
actor_id, actor_username, method, path, status_code, duration_ms, ip, user_agent, module, entity_type, entity_id, entity_name, request_body_summary, summary, trace_id, occurred_at |
plain Base, ULID id; no soft-delete columns |
src/cluster_erp/modules/logs/activity_log/models.py:15-96 |
ErrorLog |
error_log |
trace_id, error_code, error_message, http_status, actor_id, actor_username, method, path, request_body_summary, ip, user_agent, stack_trace, exception_type, error_details, occurred_at |
plain Base |
src/cluster_erp/modules/logs/error_log/models.py:15-92 |
The activity middleware writes an ActivityLog row for a successful POST, PUT, or PATCH, and for a GET of one record; it writes an ErrorLog row for a response of 400 or above that carries error details (src/cluster_erp/server/middleware.py:580-582, src/cluster_erp/server/middleware.py:619-660). Request bodies are summarised with sensitive keys removed, under operator settings (src/cluster_erp/server/middleware.py:65-66, src/cluster_erp/server/middleware.py:135). The middleware is described on request pipeline and middleware.
Screens and metadata¶
get_metadata declares a sidebar group System Logs (Turkish Sistem Günlükleri) with two custom sections: Activity Log (activity_log_view) and Error Log (error_log_view) (src/cluster_erp/modules/logs/module.py:84-123). The entity change_history is the permanent change store; the code comment calls it the replacement for the old deletion vault (src/cluster_erp/modules/logs/module.py:124-130). The web settings screen lists deactivated records from this history; see records, documents, viewer, and share. The desktop views are described on desktop module screens.
Status and actions¶
The module has no statuses and declares no ActionMeta. The change history has no create, update, or delete route (src/cluster_erp/modules/logs/change_history/routes.py:18-19).
Business rules¶
- The change history list filters by search text, entity type, table, action, actor, and date range, with a page size from 1 to 500. Actor user names are resolved for display (
src/cluster_erp/modules/logs/change_history/routes.py:29-62,src/cluster_erp/modules/logs/change_history/services.py:26-111). GET /change-history/tableslists the distinct table names with a loose index scan instead of a fullDISTINCT(src/cluster_erp/modules/logs/change_history/services.py:113-139).POST /errors/clientaccepts a report from any signed-in user and records the user, the client address, and theUser-Agentheader (src/cluster_erp/modules/logs/error_log/routes.py:22-44).- Activity and error log rows age out on a daily pass after
activity_log_retention_days(default 90) anderror_log_retention_days(default 365) (src/cluster_erp/config/settings.py:638-639,src/cluster_erp/server/app.py:1267-1290). See settings reference.
Events and queries¶
The module consumes 2 contracts and produces none, counted as on the fleet module page.
| Direction | Contract class | Handler or emitter | Source |
|---|---|---|---|
| subscribes | CollectSubjectData, AnonymiseSubject |
privacy_handlers.py |
src/cluster_erp/modules/logs/module.py:46-62 |
The full list is on the contracts reference.
Permissions¶
| Permission key | Used by | Source |
|---|---|---|
activity_log.read |
activity log | src/cluster_erp/modules/logs/activity_log/routes.py:33, src/cluster_erp/modules/logs/activity_log/routes.py:61 |
error_log.read |
error log reads | src/cluster_erp/modules/logs/error_log/routes.py:58-98 |
change_history.read |
change history | src/cluster_erp/modules/logs/change_history/routes.py:40-77 |
POST /errors/client needs a signed-in user and no permission key (src/cluster_erp/modules/logs/error_log/routes.py:22-28).
Privacy, retention, and history¶
privacy_handlers.py reports counts and the time span of log rows about a person. Anonymisation removes the user name, the record names, and the body summaries from rows made by or about the person; the rows stay, minimised, until the log retention window ends (src/cluster_erp/modules/logs/privacy_handlers.py:1-9). See privacy and data-subject requests. The purge of change history is on records module.
Analytics facts¶
This module has no analytics_facts.py.
Settings and reference data¶
The module has no settings section. The log settings activity_log_retention_days and error_log_retention_days are server settings (src/cluster_erp/config/settings.py:638-639).
Tests¶
Found by name and by a grep for change_history and log in tests/*.py.
| Kind | File | Covers |
|---|---|---|
| e2e | web-client/_e2e_logs_profile.mjs |
log screens |
| pytest | tests/test_change_history_redaction.py, tests/test_change_history_tables_live.py |
change history redaction and the table list |
| pytest | tests/test_log_sanitizer.py |
body summary sanitising |
Discrepancies¶
Terms introduced¶
| Term | Code identifier | Definition | Turkish term | Source |
|---|---|---|---|---|
| activity log | ActivityLog |
The record of every logged request with actor, path, status, duration, and the affected record. | etkinlik günlüğü | src/cluster_erp/modules/logs/activity_log/models.py:15 |
| error log | ErrorLog |
One row per server or client error with its trace id. | Hata günlüğü | src/cluster_erp/modules/logs/error_log/models.py:15 |
Related pages¶
Verified against commit 92f8051 on 2026-11-13.