History & Logs Viewer¶
Referenced Files in This Document - Historico.tsx - Logs.tsx - LogLine.tsx - history.py - logs.py - history_db.py - logs_db.py - history.py - action_log.py
Table of Contents¶
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction¶
This document explains the History and Logs viewer interface, focusing on how users navigate logs, filter by date ranges, severity levels, and source modules, and view a timeline of system events and user actions. It also covers log line rendering with syntax highlighting, collapsible entries, search across content, export capabilities, real-time streaming, and performance optimizations for large datasets. Finally, it provides guidance for customizing log formatting, adding new sources, and implementing advanced filtering rules.
Project Structure¶
The History and Logs feature spans both frontend pages and backend routes: - Frontend pages: - History page component - Logs page component - Log line component used within the logs list - Backend routes: - History route handlers - Logs route handlers - Data access: - History database helpers - Logs database helpers - Shared schemas and models: - History schema definitions - Action log model
graph TB
subgraph "Frontend"
H["Historico.tsx"]
L["Logs.tsx"]
LL["LogLine.tsx"]
end
subgraph "Backend Routes"
RH["history.py (routes)"]
RL["logs.py (routes)"]
end
subgraph "Data Access"
HD["history_db.py"]
LD["logs_db.py"]
end
subgraph "Shared"
HS["history.py (schemas)"]
AL["action_log.py (model)"]
end
H --> RH
L --> RL
RH --> HD
RL --> LD
RH --> HS
RL --> AL
Diagram sources - Historico.tsx - Logs.tsx - LogLine.tsx - history.py - logs.py - history_db.py - logs_db.py - history.py - action_log.py
Section sources - Historico.tsx - Logs.tsx - LogLine.tsx - history.py - logs.py - history_db.py - logs_db.py - history.py - action_log.py
Core Components¶
- History page: Presents a timeline view of system events and user actions, supports navigation and filtering controls.
- Logs page: Provides paginated log listing with filters for date range, severity level, and source module; includes search across log content.
- Log line component: Renders individual log entries with syntax highlighting, collapsible details, and inline search matching.
Key responsibilities: - History page coordinates fetching history data and rendering a chronological timeline. - Logs page manages pagination state, query parameters for filters, and search input. - Log line component focuses on presentation and interactivity for each log entry.
Section sources - Historico.tsx - Logs.tsx - LogLine.tsx
Architecture Overview¶
The viewer follows a clear separation between UI and data layers: - The frontend pages call backend routes to retrieve history or logs. - Backend routes apply filters and pagination before querying the database layer. - Shared schemas and models define the shape of data exchanged between layers.
sequenceDiagram
participant U as "User"
participant FE as "Logs.tsx"
participant API as "logs.py (routes)"
participant DB as "logs_db.py"
participant M as "action_log.py (model)"
U->>FE : Apply filters and search
FE->>API : GET /api/logs?date_from=&date_to=&severity=&source=&page=&limit=&q=
API->>DB : Fetch filtered logs with pagination
DB->>M : Map records to model
M-->>DB : Model instances
DB-->>API : Paginated results
API-->>FE : JSON payload
FE->>FE : Render LogLine components
Diagram sources - Logs.tsx - logs.py - logs_db.py - action_log.py
Detailed Component Analysis¶
Logs Page: Navigation, Pagination, Filtering, Search¶
Responsibilities: - Maintain query state for date range, severity, source module, search term, page number, and page size. - Build request parameters and fetch paginated logs from the backend. - Render a list of LogLine components based on returned items. - Provide UI controls for changing filters and navigating pages.
Filtering behavior: - Date range filters narrow logs to a specific window. - Severity filters restrict logs to selected levels. - Source module filters limit logs to chosen modules. - Search term matches against log content fields.
Pagination behavior: - Requests include page and limit parameters. - Response includes current page items and metadata such as total count or next page availability.
flowchart TD
Start(["Open Logs Page"]) --> InitState["Initialize default filters<br/>and pagination state"]
InitState --> UserInput{"User changes filters/search?"}
UserInput --> |Yes| UpdateParams["Update query params"]
UpdateParams --> Fetch["Fetch /api/logs with params"]
Fetch --> HasResults{"Has results?"}
HasResults --> |Yes| Render["Render LogLine list"]
HasResults --> |No| ShowEmpty["Show empty state"]
Render --> End(["Ready for interaction"])
ShowEmpty --> End
UserInput --> |No| End
Diagram sources - Logs.tsx - logs.py
Section sources - Logs.tsx - logs.py
Log Line Component: Syntax Highlighting, Collapsible Entries, Inline Search¶
Responsibilities: - Display a single log entry with formatted timestamp, severity, source, and message. - Apply syntax highlighting to structured parts of the message where applicable. - Allow collapsing/expanding detailed content. - Highlight search matches within the message text.
Interactions: - Click to expand/collapse details. - Visual cues for severity levels. - Inline highlight for search terms.
classDiagram
class LogLine {
+string timestamp
+string severity
+string source
+string message
+boolean expanded
+render() JSX
+toggleExpand() void
+highlightMatches(query) string
}
Diagram sources - LogLine.tsx
Section sources - LogLine.tsx
History Timeline View: System Events, User Actions, Processing Activities¶
Responsibilities: - Retrieve history entries via the history route. - Present them chronologically with contextual badges and summaries. - Support basic filtering if provided by the backend.
Timeline characteristics: - Chronological ordering by event timestamp. - Grouped or categorized entries for clarity. - Expandable details for deeper inspection.
sequenceDiagram
participant U as "User"
participant FE as "Historico.tsx"
participant API as "history.py (routes)"
participant DB as "history_db.py"
participant S as "history.py (schemas)"
U->>FE : Open History
FE->>API : GET /api/history[?filters]
API->>DB : Query history records
DB-->>API : Records
API->>S : Validate/transform to schema
S-->>API : Schema objects
API-->>FE : JSON payload
FE->>FE : Render timeline
Diagram sources - Historico.tsx - history.py - history_db.py - history.py
Section sources - Historico.tsx - history.py - history_db.py - history.py
Dependency Analysis¶
The following diagram shows how the frontend pages depend on backend routes, which in turn rely on database helpers and shared schemas/models.
graph LR
FE_H["Historico.tsx"] --> R_H["history.py (routes)"]
FE_L["Logs.tsx"] --> R_L["logs.py (routes)"]
R_H --> D_H["history_db.py"]
R_L --> D_L["logs_db.py"]
R_H --> S_H["history.py (schemas)"]
R_L --> M_AL["action_log.py (model)"]
Diagram sources - Historico.tsx - Logs.tsx - history.py - logs.py - history_db.py - logs_db.py - history.py - action_log.py
Section sources - Historico.tsx - Logs.tsx - history.py - logs.py - history_db.py - logs_db.py - history.py - action_log.py
Performance Considerations¶
- Server-side pagination: Always use page and limit parameters to avoid loading entire datasets into memory.
- Indexing: Ensure database indexes exist on commonly filtered columns (timestamps, severity, source).
- Debounced search: Implement client-side debounce for search inputs to reduce frequent requests.
- Virtualization: For very large lists, consider virtualized rendering to keep DOM size manageable.
- Caching: Cache frequently accessed history snapshots when appropriate.
- Streaming: Use server-sent events or WebSocket streams for real-time logs to avoid polling overhead.
[No sources needed since this section provides general guidance]
Troubleshooting Guide¶
Common issues and resolutions: - Empty results after applying filters: Verify that date ranges are valid and not inverted; confirm severity and source values match available options. - Slow load times: Check pagination parameters and ensure backend applies filters efficiently; review database indexes. - Search not matching expected entries: Confirm search is applied to the correct fields and that special characters are handled consistently. - Real-time updates not appearing: Ensure the stream endpoint is reachable and the client reconnects on errors.
Section sources - Logs.tsx - logs.py - Historico.tsx - history.py
Conclusion¶
The History and Logs viewer provides a robust interface for exploring system activity and operational logs. With pagination, targeted filtering, and a dedicated log line renderer, users can quickly locate relevant information. The architecture cleanly separates concerns between UI, routes, and data access, enabling scalability and maintainability. Extensibility points allow adding new sources, custom formats, and advanced filtering rules while preserving performance and usability.
[No sources needed since this section summarizes without analyzing specific files]
Appendices¶
A. Export Capabilities¶
- Supported formats: CSV, JSON, and plain text.
- Typical workflow:
- Select filters to scope the export.
- Trigger export action from the UI.
- Backend generates file and returns a download link or stream.
- Recommendations:
- Stream large exports to avoid memory spikes.
- Include headers and consistent field ordering.
- Respect existing pagination by exporting only the filtered subset.
[No sources needed since this section provides general guidance]
B. Real-Time Log Streaming¶
- Mechanism: Server-sent events or WebSocket-based streaming.
- Client behavior:
- Connect to the stream endpoint.
- Append incoming log lines to the viewport.
- Auto-scroll with an option to pause.
- Reliability:
- Reconnect on connection loss.
- Buffer recent messages to catch up after reconnection.
[No sources needed since this section provides general guidance]
C. Custom Log Formatting¶
- Define a formatter per source module to normalize timestamps, levels, and structure.
- Use structured logging to enable better parsing and highlighting.
- Keep message templates concise and machine-readable where possible.
[No sources needed since this section provides general guidance]
D. Adding New Log Sources¶
- Steps:
- Create a logger instance tagged with a unique source identifier.
- Emit events using consistent severity levels.
- Ensure backend ingestion persists and indexes required fields.
- Add the new source to the frontend filter dropdown.
- Validation:
- Test with sample logs to verify filtering and search behavior.
[No sources needed since this section provides general guidance]
E. Advanced Filtering Rules¶
- Combine multiple conditions:
- Date range AND severity AND source module.
- Full-text search with optional phrase matching.
- Implementation tips:
- Normalize inputs (trim, lowercase) before building queries.
- Use parameterized queries to prevent injection.
- Return metadata indicating whether additional pages exist.
[No sources needed since this section provides general guidance]