Skip to content

History & Logging API

Referenced Files in This Document

Table of Contents

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

  10. Appendices

Introduction

This document provides comprehensive API documentation for Nexo’s history and logging system. It covers endpoints for retrieving action logs, system events, and audit trails; filtering and search capabilities; log level management; rotation policies; storage backends; export functionality; real-time streaming via Server-Sent Events (SSE); analysis queries; performance monitoring integrations; alerting setup; retention and archival strategies; and compliance considerations for audit logging.

The system is implemented as a FastAPI service with database-backed persistence and an optional SSE stream for live monitoring. The frontend includes a Logs page that consumes these APIs and streams.

Project Structure

The logging and history subsystem spans backend routes, data models, database access, logger configuration, and the dashboard UI:

  • Backend routes expose REST endpoints for logs and history, plus SSE streaming.

  • Data models define the structure of action logs and related entities.

  • Database layer implements query builders and pagination helpers.

  • Logger module configures levels, handlers, and rotation.

  • Dashboard pages consume the APIs and render logs and streams.

graph TB

subgraph "Service"

RLOG["routes/logs.py"]

RHIST["routes/history.py"]

LDB["database/logs_db.py"]

LCFG["logger.py"]

end

subgraph "Models"

MLOG["models/action_log.py"]

end

subgraph "Dashboard"

DLOG["pages/Logs.tsx"]

DSSE["services/sse.js"]

end

RLOG --> LDB

RHIST --> LDB

RLOG --> MLOG

RHIST --> MLOG

LCFG -.-> RLOG

DLOG --> RLOG

DLOG --> RHIST

DLOG --> DSSE

Diagram sources

Section sources

Core Components

  • Action Log Model: Defines fields such as timestamp, event type, severity, tags, message, and correlation identifiers used across logs and history.

  • Logs Route: Provides REST endpoints to list, filter, search, paginate, and export logs. Also exposes an SSE endpoint for real-time streaming.

  • History Route: Exposes endpoints for historical actions and decisions, including time-bounded queries and aggregation summaries.

  • Database Layer: Implements efficient querying, filtering by multiple criteria, sorting, and pagination over the logs table.

  • Logger Configuration: Centralizes log level management, handler selection, and rotation policies.

Key responsibilities:

  • Filtering and search across timestamps, event types, severity levels, and custom tags.

  • Exporting logs in multiple formats with optional compression.

  • Streaming new log entries via SSE for live dashboards.

  • Enforcing retention and rotation policies at the application and storage layers.

Section sources

Architecture Overview

The logging architecture combines structured persistence, flexible querying, and real-time delivery:

sequenceDiagram

participant Client as "Client/Dashboard"

participant API as "FastAPI Service"

participant DB as "Database Layer"

participant Store as "Storage Backend"

participant SSE as "SSE Stream"

Client->>API : "GET /api/logs?filters..."

API->>DB : "build_query(filters)"

DB->>Store : "SELECT ... ORDER BY ts DESC LIMIT/PAGINATION"

Store-->>DB : "Rows"

DB-->>API : "Paginated results"

API-->>Client : "JSON response"

Client->>API : "GET /api/logs/stream"

API->>SSE : "Open stream"

Store-->>API : "New log entry"

API-->>Client : "event : log\n data : {...}"

Diagram sources

Detailed Component Analysis

Logs API

Endpoints:

  • List and filter logs

  • Search logs

  • Paginate logs

  • Export logs

  • Real-time streaming (SSE)

Common filters:

  • Time range: start_time, end_time

  • Event type: event_type

  • Severity level: severity

  • Tags: tag (repeatable or comma-separated)

  • Text search: q (message substring)

  • Correlation ID: correlation_id

  • Source/system: source

  • Pagination: page, page_size

  • Sorting: sort_by, sort_order

Export options:

  • Format: json, csv, parquet (if enabled)

  • Compression: gzip, none

  • Scope: filtered subset or full dataset (subject to limits)

SSE:

  • Endpoint: /api/logs/stream

  • Event name: log

  • Payload: single log record

  • Reconnection: client handles reconnects and last-event-id if supported

Example usage patterns:

  • Retrieve errors from the last hour tagged with “scan”:

  • Query parameters include severity=ERROR, start_time=now-1h, tag=scan

  • Export recent warnings as CSV with gzip compression:

  • Parameters include severity=WARNING, format=csv, compression=gzip

Notes:

  • Large exports should use pagination or server-side job IDs to avoid blocking requests.

  • Tag matching supports exact match and contains semantics depending on implementation.

Section sources

History API

Endpoints:

  • List historical actions/events

  • Get details by ID

  • Aggregate counts by time buckets

  • Filter by date ranges, event types, and tags

Use cases:

  • Audit trail retrieval for compliance

  • Trend analysis over time

  • Decision lineage and provenance

Filtering and sorting:

  • Time windows, event types, tags

  • Sort by timestamp descending by default

  • Optional grouping/aggregation endpoints

Section sources

Data Model: Action Log

Fields typically include:

  • id: unique identifier

  • timestamp: ISO 8601 UTC

  • event_type: category of event

  • severity: INFO, WARNING, ERROR, CRITICAL

  • tags: key-value pairs or array

  • message: human-readable text

  • correlation_id: request or operation trace

  • source: component or subsystem

  • metadata: additional structured context

Complexity:

  • Indexes on timestamp, event_type, severity, tags, and correlation_id improve query performance.

  • Tag queries may leverage JSON indexing or normalized tables depending on storage backend.

Section sources

Database Layer

Responsibilities:

  • Build parameterized queries from filters

  • Apply pagination and sorting

  • Optimize common queries with indexes

  • Support export queries with streaming where possible

Optimizations:

  • Use partial indexes for high-cardinality filters like severity and event_type.

  • Materialize aggregates for frequent analytics queries.

  • Stream large result sets to reduce memory pressure.

Section sources

Logger Configuration

Features:

  • Global log level management

  • Multiple handlers (console, file, remote)

  • Rotation policies (size-based, time-based)

  • Structured logging with consistent schema

Policies:

  • Max file size and backup count

  • Retention period before archival/deletion

  • Compression of rotated files

Integration points:

  • Application startup initializes logger

  • Routes and services emit structured logs

  • SSE stream reads from a shared buffer or tailer

Section sources

Dashboard Integration

Frontend components:

  • Logs page displays paginated logs and filters

  • SSE consumer subscribes to live updates

  • Export controls trigger download jobs

Implementation notes:

  • Debounce filter changes to avoid excessive requests

  • Handle SSE reconnection and backoff

  • Render severity and tags with badges for quick scanning

Section sources

Dependency Analysis

High-level dependencies between components:

graph LR

RLOG["routes/logs.py"] --> LDB["database/logs_db.py"]

RHIST["routes/history.py"] --> LDB

RLOG --> MLOG["models/action_log.py"]

RHIST --> MLOG

LCFG["logger.py"] --> RLOG

DLOG["pages/Logs.tsx"] --> RLOG

DLOG --> RHIST

DSSE["services/sse.js"] --> RLOG

Diagram sources

Section sources

Performance Considerations

  • Indexing strategy: Ensure indexes exist on timestamp, event_type, severity, tags, and correlation_id.

  • Pagination defaults: Enforce reasonable page sizes and maximum bounds to prevent heavy queries.

  • Export streaming: For large datasets, prefer server-side streaming or background jobs with polling.

  • SSE scalability: Use a publish-subscribe channel or queue to fan out events to many clients efficiently.

  • Aggregations: Precompute time-series metrics for dashboards to reduce load on primary logs table.

  • Caching: Cache frequent filter combinations with short TTLs when appropriate.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Missing indexes causing slow queries: Add composite indexes for common filter combinations.

  • SSE disconnections: Implement exponential backoff and last-event-id handling on the client.

  • Export timeouts: Switch to async export jobs and provide status endpoints.

  • High cardinality tags: Normalize tags into a separate table or use JSONB with GIN indexes.

  • Log rotation conflicts: Ensure exclusive file locks and graceful restarts during rotation.

Operational checks:

  • Verify log level settings are correct for environments.

  • Confirm rotation policies align with disk capacity and retention requirements.

  • Validate SSE endpoint availability and rate limiting.

Section sources

Conclusion

Nexo’s history and logging system offers robust REST APIs for querying and exporting logs, real-time streaming via SSE, and configurable logging behavior. With proper indexing, pagination, and export strategies, it supports both operational monitoring and compliance needs. The dashboard integrates seamlessly to visualize logs and live events.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

API Reference Summary

  • GET /api/logs

  • Purpose: List and filter logs

  • Filters: start_time, end_time, event_type, severity, tag, q, correlation_id, source, page, page_size, sort_by, sort_order

  • Response: Paginated list of log records

  • GET /api/logs/export

  • Purpose: Export logs

  • Parameters: format=json|csv|parquet, compression=gzip|none, scope=filtered|full, limit

  • Response: Download link or file stream

  • GET /api/logs/stream

  • Purpose: SSE stream of new logs

  • Event: log

  • Payload: Single log record

  • GET /api/history/actions

  • Purpose: List historical actions

  • Filters: time range, event_type, tags

  • Response: Paginated list

  • GET /api/history/actions/{id}

  • Purpose: Get action detail

  • Response: Action record

  • GET /api/history/aggregates

  • Purpose: Time-bucketed counts

  • Parameters: bucket=hour|day|week, group_by=event_type|severity

  • Response: Series of aggregated counts

[No sources needed since this section provides general guidance]

Example Queries

  • Errors in the last hour with tag “scan”:

  • severity=ERROR, start_time=now-1h, tag=scan

  • Warnings exported as CSV with gzip:

  • severity=WARNING, format=csv, compression=gzip

  • Live monitoring:

  • Connect to /api/logs/stream and subscribe to event “log”

[No sources needed since this section provides general guidance]

Log Level Management

  • Global level: Set via configuration at startup

  • Handler-specific levels: Console vs file handlers can differ

  • Dynamic updates: Reload configuration without restart if supported

Section sources

Log Rotation Policies

  • Size-based rotation: Rotate when file exceeds threshold

  • Time-based rotation: Rotate daily/hourly

  • Retention: Keep N backups or delete after days

  • Compression: Compress rotated files to save space

Section sources

Storage Backends

  • Relational database: Primary store for logs and history

  • Object storage: Archival of old logs and exports

  • File system: Local rotation and temporary staging

[No sources needed since this section provides general guidance]

Search Capabilities

  • Timestamp range queries

  • Exact and contains matches for event_type and message

  • Tag filtering with AND/OR semantics

  • Correlation ID tracing across subsystems

Section sources

Real-Time Streaming (SSE)

  • Connection lifecycle: Open, receive events, handle disconnects

  • Client reconnection: Retry with backoff

  • Rate limiting: Throttle per-client to protect server

Section sources

Log Export Functionality

  • Formats: JSON, CSV, Parquet (optional)

  • Compression: Gzip for downloads

  • Job-based export: For large datasets, return job ID and status

Section sources

Log Analysis Queries

  • Top error sources by hour

  • Distribution of severities over time

  • Tag frequency and trends

  • Mean time between critical events

[No sources needed since this section provides general guidance]

Performance Monitoring Integrations

  • Metrics: Log ingestion rate, query latency, SSE connections

  • Tracing: Propagate correlation_id through services

  • Alerts: Thresholds on error rates and lag

[No sources needed since this section provides general guidance]

Alerting System Setup

  • Rule examples: Error rate > X per minute, no logs for Y minutes

  • Channels: Webhook, email, messaging platforms

  • Suppression: Deduplicate alerts and cooldowns

[No sources needed since this section provides general guidance]

Retention and Archival Strategies

  • Hot storage: Recent logs with fast queries

  • Warm storage: Older logs with slower access

  • Cold archive: Long-term retention with compression

  • Automated lifecycle policies based on age and size

[No sources needed since this section provides general guidance]

Compliance Requirements for Audit Logging

  • Immutability: Append-only logs with checksums

  • Integrity: Hash chains or signatures for critical entries

  • Access control: Role-based access to sensitive logs

  • Audit trails: Record who accessed or modified configurations

  • Data minimization: Redact PII where required

[No sources needed since this section provides general guidance]