Logging System & Sockets
Relevant source files
The following files were used as context for generating this wiki page:
The Warpgate logging system is designed to provide real-time observability and historical auditing for all administrative actions and protocol sessions. It integrates directly with the application's runtime to capture structured events, which are then surfaced through the Admin Web UI for monitoring and troubleshooting.
The system encompasses protocol-specific logging (SSH, HTTP, MySQL, PostgreSQL) and administrative logs. For protocols like PostgreSQL, the system tracks specific database queries and internal state transitions, associating them with unique session identifiers.
Sources: warpgate/src/main.rs:13, warpgate-protocol-postgres/src/session.rs:60-68
System Architecture & Initialization
The logging system is initialized early in the application lifecycle. The init_logging function is called within the main entry point, taking the loaded configuration and CLI arguments to set the appropriate log levels and sinks.
The application uses the tracing crate for structured logging, allowing for rich context (spans) to be attached to log entries.
Sources: warpgate/src/main.rs:10, warpgate/src/main.rs:88
Protocol-Specific Session Logging
Each protocol session generates a dedicated logging span. In the PostgreSQL implementation, the span includes the session UUID, the authenticated username, and the client's IP address. This allows for fine-grained filtering of logs by session.
PostgreSQL Logging Context
When a PostgreSQL session is active, the system logs specific frontend messages, such as:
- Query Preparation: Logs when
Parsemessages are received. - Query Execution: Logs when
ExecuteorQuerymessages are processed, including the raw SQL text for standard queries. - Error Responses: Captures
ErrorResponsemessages from the target server.
Sources: warpgate-protocol-postgres/src/session.rs:60-68, warpgate-protocol-postgres/src/session.rs:252-271
Connection Span Structure
| Field | Description | Source |
|---|---|---|
session | Unique UUID for the connection | session.rs:64 |
session_username | The username authenticated via Warpgate | session.rs:64 |
client_ip | The source IP address of the client | session.rs:61 |
Log Retrieval and Visualization
The Admin UI features a LogViewer component that retrieves logs via the getLogs API endpoint. This component supports real-time updates and historical searching.
Log Viewer Logic
The viewer implements a dual-loading strategy:
- loadNewer: Periodically polls the server for logs produced after the latest known timestamp.
- loadOlder: Triggered by user scrolling (via an Intersection Observer) to fetch historical logs before the oldest displayed timestamp.
Log Entry Data Structure
| Field | Type | Description |
|---|---|---|
id | UUID/String | Unique identifier for the log entry |
timestamp | Date | When the event occurred |
username | String (Optional) | User associated with the event |
sessionId | String (Optional) | Link to the specific session |
text | String | The main log message |
values | Object | Key-value pairs for structured data |
Sources: warpgate-web/src/admin/LogViewer.svelte:115-139
Administrative Logging
Administrative actions, such as role mapping updates during SSO login or configuration changes, are explicitly logged. For instance, when a user's roles are synchronized via an SSO provider, the system logs the addition or removal of specific roles.
Sources: warpgate-core/src/config_providers/db.rs:260, warpgate-core/src/config_providers/db.rs:269
Socket and Endpoint Configuration
Warpgate manages multiple listening sockets for different protocols. These are configured during the setup or unattended-setup commands and stored in the configuration file.
Protocol Listeners
The system uses ListenEndpoint to define socket addresses (IP and Port) for the following services:
- HTTP: Used for the Web Admin and HTTP Proxying.
- SSH: Standard SSH bastion port.
- MySQL: Listener for MySQL protocol proxying.
- PostgreSQL: Listener for PostgreSQL protocol proxying.
Sources: warpgate/src/commands/setup.rs:114-168
Setup Command Socket Logic
| Parameter | Default/Docker Value | File Reference |
|---|---|---|
http_port | Configurable (Commonly 8888) | setup.rs:114 |
ssh_port | 2222 (Docker default) | setup.rs:125 |
mysql_port | Enabled by default in Docker | setup.rs:149 |
postgres_port | Enabled by default in Docker | setup.rs:168 |
During interactive setup, the application uses the dialoguer crate to prompt users for these endpoints, resolving provided strings into SocketAddr structures.
Sources: warpgate/src/commands/setup.rs:31-50
Summary
The logging system and socket management in Warpgate provide the foundation for its security auditing capabilities. By combining structured tracing spans at the protocol level with a persistent database store and a dynamic web-based viewer, the system ensures that every interaction—from administrative configuration to individual database queries—is recorded and searchable. Socket management ensures these logs are correctly attributed to the various protocol-specific listeners enabled during initial setup.