Connection History & Analytics¶

Track and analyze all your SSH tunnel connections with StormTunnel's comprehensive history and analytics system.

Overview¶

StormTunnel's Connection History & Analytics feature provides complete visibility into your tunnel usage patterns, connection reliability, and error trends. This premium feature automatically captures every connection event and provides powerful tools for analysis and troubleshooting.

What Connection History Tracks¶

The history system automatically records:

• Connection Events: Every time you connect or disconnect a tunnel
• Connection Errors: Failed connection attempts with detailed error messages
• Connection Stages: Preflight, authentication, and completion states
• SSH Mode Changes: Transitions between NIOSSH and CLI modes
• Session Durations: Time spent connected for each tunnel
• Connection Metadata: Local port, remote host, SSH key used, and more
• Retry Attempts: Automatic reconnection attempts and their outcomes

License Requirements¶

Connection History is a premium feature with tiered access:

Free users can see the last 5 connection events only. Full history access and analytics dashboard require a Premium license.

Premium users get unlimited connection history, advanced analytics, and detailed usage statistics to monitor tunnel performance and identify issues.

When to Use Connection History¶

Connection History is valuable for:

• Troubleshooting: Investigate why connections fail and identify error patterns
• Performance Monitoring: Track connection reliability and success rates over time
• Usage Analysis: Understand which tunnels you use most frequently
• Compliance & Auditing: Review connection activity for security auditing
• Debugging: Reproduce intermittent issues by examining historical data
• Capacity Planning: Identify peak usage periods for resource allocation

Viewing Connection History¶

Access and view all tunnel connections across your account.

Accessing History¶

The Connection History window is available from several locations in the application:

1. From Main Application Menu: Navigate to history through the app menu
2. From Settings: View connection history settings and manage tracking preferences

Check your application menu for keyboard shortcuts assigned to opening the history window.

Window Layout Overview¶

The Connection History window is organized into several key sections:

┌─────────────────────────────────────────────────────────┐
│ Header: Connection History                             │
│ Subtitle: Global timeline of all tunnel connections     │
│                                    [Clear All]      │
├─────────────────────────────────────────────────────────┤
│ Filters Bar                                        │
│ [Search] [Event Type▼] [Tunnel▼] [Time Range]   │
├─────────────────────────────────────────────────────────┤
│ Connection Statistics (Premium Only)                   │
│ ┌──────┬──────┬──────┬──────┐                  │
│ │Total │Success│Failed│Rate  │                  │
│ └──────┴──────┴──────┴──────┘                  │
│ [Connection Timeline Chart]                          │
│ [SSH Mode Usage] [Tunnel Type Usage]               │
├─────────────────────────────────────────────────────────┤
│ Connection History List                              │
│ │✓ Production Server - Connected (NIOSSH)        │ │
│ │  Remote: prod.example.com - Port: 5432        │ │
│ │  Time: Dec 29, 2025 at 2:45 PM            │ │
│ └───────────────────────────────────────────────────────│
│ │✓ Production Server - Disconnected (Duration: 2h)│ │
│ └───────────────────────────────────────────────────────│
└─────────────────────────────────────────────────────────┘

First-Time User Experience¶

When you first open Connection History:

• New Users: The history list will be empty. Connect to tunnels to build your history.
• Free Tier Users: You'll see the last 5 connection events only.
• Premium Users: Full history with all filtering and analytics capabilities.
• Users Without Data: If you have no connections yet, you'll see an empty state message prompting you to connect to tunnels.

Connection history is automatically saved to your local application data. You don't need to manually save or export history.

Understanding the History List¶

Each connection history entry displays:

• Tunnel Name: The configured tunnel name
• Status Icon: Visual indicator of connection state
  • ● Connected (green circle)
  • ○ Disconnected (gray circle)
  • ✗ Error (red X)
  • → Stage changed (blue arrow)
  • 🔄 Mode changed (orange arrows)
• Event Type: Connected, Disconnected, Error, Stage Changed, or Mode Changed
• SSH Mode: Which implementation was used (NIOSSH, CLI)
• Duration: For disconnections, shows how long the connection lasted
• Remote Host: The server endpoint connected to
• Local Port: The local port mapped for this tunnel
• Timestamp: When the event occurred (formatted and relative)

Event Types Explained¶

Connected¶

Indicates a tunnel was successfully established and is now active. This event includes:

• Tunnel name and type
• SSH mode used (NIOSSH or CLI)
• Remote host and local port
• Connection timestamp

Disconnected¶

Indicates a tunnel connection was terminated (either manually or automatically). This event shows:

• Duration of the connection session
• Tunnel information
• Disconnection timestamp

If a tunnel is currently connected, you won't see a disconnection event until it's stopped.

Error¶

Indicates a connection failure. Error events display:

• Error Message: Detailed description of what went wrong
• SSH Mode: Which implementation was being used
• Reconnection Attempts: If automatic retry was attempted

Common errors include:

• Authentication failures
• Connection timeouts
• Host unreachable
• Port binding conflicts
• Permission denied

Stage Changed¶

Tracks progression through connection stages when enabled in settings. Stages include:

• Preflight: Initial validation and preparation
• Authenticating: SSH key exchange and authentication
• Connected: Connection established and forwarding active
• Complete: Tunnel ready for use

Stage events are disabled by default for performance. Enable them in Advanced Settings if you need detailed connection diagnostics.

Mode Changed¶

Records when a tunnel switches between SSH implementations:

• NIOSSH: Native Swift SSH implementation (default)
• CLI: System SSH CLI fallback

This helps identify which SSH mode works best for your use case.

Connection Sessions¶

Each connected tunnel creates a session that tracks:

• Start Time: When the connection was initiated
• End Time: When it was disconnected (if applicable)
• Duration: Total time connected
• Success Status: Whether the session completed successfully
• SSH Mode: Which implementation was used
• Metadata: Additional context like SSH key ID, retry attempts

Sessions are useful for analyzing connection patterns and calculating statistics.

Timestamp Information¶

History events display timestamps in multiple formats:

• Relative Time: "2 hours ago", "30 minutes ago" (for quick scanning)
• Formatted Time: "Dec 29, 2025 at 2:45 PM" (for specific reference)
• Hover Details: Hover over any entry for additional timestamp information

The relative timestamp updates dynamically, showing how long ago each event occurred.

Duration Calculations¶

Connection duration is calculated from the time between connected and disconnected events:

• Active Connections: Duration is calculated from connection start to current time
• Completed Sessions: Shows total time connected
• Failed Sessions: Duration is 0 (connection never established)

Durations are formatted for readability:

• Seconds: 45s (less than 1 minute)
• Minutes: 15m (1-59 minutes)
• Hours: 2h 30m (1-24 hours)
• Days: 3d 5h (longer than 24 hours)

Duration is calculated from actual connect/disconnect timestamps, not estimated. If the application crashes while a tunnel is active, an orphaned connection event will be created with the duration at the time of the crash.

Search & Filtering¶

Filter connection history to quickly find specific events, troubleshoot issues, or analyze patterns.

Search Functionality¶

The search bar filters history by matching text in:

• Tunnel Name: Partial matches against tunnel names
• Remote Host: Domain names, IP addresses, hostnames
• Error Messages: Text from error events only

Search is not case-sensitive. "Production", "production", and "PRODUCTION" all match the same results.

Search Examples:

Search: "prod"           → Matches tunnels with "prod" in name
Search: "example.com"    → Matches connections to example.com hosts
Search: "timeout"        → Matches error messages containing "timeout"
Search: "192.168"        → Matches connections to local network IPs

Event Type Filter¶

Filter by connection event type to focus on specific activities:

Usage Example:

1. Select "Error" from the Event Type dropdown
2. Review all failed connection attempts
3. Identify common error patterns or problematic hosts

Tunnel Filter¶

Filter history to show events for a specific tunnel only:

1. Click the Tunnel dropdown
2. Select a tunnel from the list (e.g., "Production Server")
3. View all events for that tunnel only

You can also view history for individual tunnels from the tunnel detail view in the main window.

Date Range Selection¶

Control how far back in history to view with the time range selector:

Free users may see fewer events than the selected time range due to the 5-event limit.

Use Cases:

• Last 24 Hours: Debug recent connection issues
• Last 7 Days: Review weekly usage patterns
• Last 30 Days: Analyze monthly trends and reliability
• All Time: View complete historical data

Combining Filters¶

Filters work together to narrow down results. For example:

Example 1: Find all failed connections to a specific server

1. Search: "prod.example.com"
2. Event Type: Error
3. Time Range: Last 7 Days

Example 2: Review successful connections this week

1. Event Type: Connected
2. Time Range: Last 7 Days

Example 3: Find timeout errors on a specific tunnel

1. Search: "timeout"
2. Tunnel: "Development Server"
3. Event Type: Error

Click "Clear Filters" to reset all filters and show all history again.

Clearing Filters¶

When filters are applied and no results match, you'll see an empty state with a "Clear Filters" button.

To clear all filters:

1. Click the "Clear Filters" button
2. Or manually reset each filter:
   • Clear the search text
   • Select "All Events" for event type
   • Select "All Tunnels" for tunnel filter
   • Select "All Time" for time range

Connection Statistics Dashboard¶

The statistics dashboard (Premium only) provides analytics and visualizations of your tunnel usage patterns.

Accessing Statistics¶

The statistics dashboard appears at the top of the Connection History window for Premium users. Free users see an upgrade prompt in this section.

Statistics Cards¶

Four key metrics are displayed at the top of the dashboard:

Interpreting Success Rate:

• > 90% (green): Excellent reliability
• 70-90% (yellow): Good reliability, some intermittent issues
• < 70% (red): Frequent problems requiring investigation

Success Rate = (Successful Sessions / Total Sessions) × 100%

Connection Timeline Chart¶

A visual timeline showing connection events over time (requires macOS 13+).

Chart Details:

• X-Axis: Time (based on selected time range)
• Y-Axis: Connection duration (in seconds)
• Points: Each point represents a connection
  • ● Green: Successful connection
  • ● Red: Failed connection

Using the Timeline:

1. Identify patterns in connection frequency
2. Spot outliers in connection duration
3. Correlate failures with time periods
4. View temporal clustering of connection issues

The Connection Timeline chart requires macOS 13.0 (Ventura) or later for Swift Charts framework support.

SSH Mode Usage Breakdown¶

Shows how often each SSH implementation is used:

Analysis Use Cases:

• Compare stability between NIOSSH and CLI modes
• Identify which mode works better for specific tunnels
• Track mode switching patterns over time

NIOSSH is the default and is generally faster. CLI is used as a fallback for compatibility or specific server configurations.

Tunnel Type Usage Breakdown¶

Displays usage statistics by tunnel type:

Use Cases:

• Track the adoption of different tunnel technologies
• Identify primary tunnel types in your workflow
• Monitor AWS vs. SSH tunnel usage patterns

Time Range Filtering for Stats¶

Statistics automatically update based on the selected time range filter:

• Last 24 Hours: Recent performance and reliability
• Last 7 Days: Weekly trends and patterns
• Last 30 Days: Monthly analysis and long-term trends
• All Time: Complete historical statistics

Switch between time ranges to identify changes in reliability or usage patterns over time.

Interpreting the Data¶

Success Rate Analysis:

• High Success Rate (> 90%): Tunnels and network are reliable
• Declining Success Rate: Recent changes or issues introduced
• Specific Tunnel Issues: Filter by tunnel to isolate problem connections

Timeline Analysis:

• Consistent Points: Regular usage patterns (e.g., daily backups)
• Clusters: High usage periods or connection storms
• Gaps: Periods of inactivity or downtime

Mode/Type Analysis:

• Dominant Mode: Primary SSH implementation preference
• Mode Switching: Frequent switches indicate compatibility testing or fallback usage

Managing History¶

Control what's stored in connection history and manage data retention.

Clearing All History¶

Remove all connection history from the application:

1. Click the "Clear All" button in the History window header
2. Confirm the action in the confirmation dialog
3. All history events are permanently deleted

Clearing history cannot be undone. All connection data will be permanently removed from the application.

Clearing History for Specific Tunnels¶

Remove history only for a specific tunnel from its detail view:

1. Open the tunnel detail view
2. Click the "Connection History" tab
3. Click the "Clear" button
4. Confirm the deletion

Privacy Settings¶

Protect sensitive information in your connection history.

Host Anonymization¶

Enable hostname anonymization to hide remote host information in history:

1. Open Settings → Advanced
2. Find the "Connection History" section
3. Enable "Anonymize hostnames"
4. Hostnames are replaced with secure hashes

Example:

Disabled: prod-db.internal.example.com
Enabled:  3A7F9C2D

Anonymization uses consistent SHA-256 hashing, so the same host always produces the same hash. This preserves analysis capabilities while protecting privacy.

Excluding Sensitive Tunnels¶

Prevent specific tunnels from being tracked in history:

1. Open Settings → Advanced
2. Configure connection history settings
3. Add tunnels to the exclusion list

Use Cases:

• Production tunnels with strict compliance requirements
• Tunnels connecting to sensitive infrastructure
• Temporary or test tunnels you don't want recorded

Storage Considerations¶

Connection history is stored in:

• Location: Application UserDefaults (encrypted on macOS)
• Format: JSON with ISO 8601 timestamps
• Backup: Automatic backup of previous history data
• Size: Typically less than 1MB for normal usage

History is automatically pruned based on retention settings (default: 30 days, max 50 events per tunnel).

History Retention¶

Control how long connection history is kept:

Default Retention Settings:

To Adjust Retention:

1. Open Settings → Advanced
2. Locate the Connection History section
3. Adjust retention settings
4. Settings take effect immediately

Higher event counts and longer retention periods may increase memory usage and UI rendering time. Use the default settings for best performance.

License Features¶

Connection History is a premium feature with tiered access.

Free Plan: Last 5 Events¶

Free tier users have limited access:

• Visibility: Last 5 connection events only
• Search & Filter: Available
• Statistics Dashboard: Not accessible (upgrade prompt shown)
• Time Range: Limited to available events (typically Last 24 Hours)
• Retention: Events are still recorded, but only 5 are visible

Free Tier Experience:

• See basic connection history (last 5 events)
• Use search and filters to find specific events
• View individual event details
• Clear history

Premium Plan: Unlimited History¶

Premium users get full access:

• Visibility: Unlimited connection history
• Search & Filter: Full capabilities
• Statistics Dashboard: Complete analytics with charts
• Time Range: All options available
• Retention: Up to 90 days with 200 events per tunnel

Premium Features:

• Complete connection timeline
• Success rate analysis
• Connection timeline visualization
• SSH mode usage breakdown
• Tunnel type usage breakdown
• Advanced filtering and search

What Happens When Upgrading¶

When you upgrade from Free to Premium:

1. Immediate Access: All history features unlock instantly
2. Historical Data: All previously recorded history becomes visible
3. Statistics: Dashboard populates with all historical data
4. No Data Loss: No history is lost during the upgrade

Your connection history continues from Free to Premium without interruption. All previously recorded events become visible immediately after the upgrade.

What Happens When Downgrading¶

If your Premium license expires:

1. Dashboard Hides: Statistics dashboard shows upgrade prompt
2. History Limited: Only last 5 events visible
3. Data Preserved: All history is retained locally
4. Restore on Renewal: Full access returns with license renewal

Your connection history is never deleted when downgrading. All events are preserved and will be visible again when you renew or upgrade.

Common Questions¶

Why Don't I See Older Connections?¶

Possible Causes:

1. Free Tier Limitation: Free users only see the last 5 events
2. Retention Period: Events older than the retention setting (default: 30 days) are automatically pruned
3. History Cleared: Someone may have cleared the history
4. New Application: This is a fresh installation with no accumulated history

Solutions:

• Upgrade to Premium for unlimited history
• Check retention settings in Advanced preferences
• Verify no one cleared the history
• Allow time for new connections to be recorded

How Long Is History Kept?¶

Connection history retention depends on your settings:

• Default: 30 days
• Configurable: 7 to 90 days
• Per-Tunnel Limit: Default 50 events per tunnel (20-200 range)
• Automatic Pruning: Old events are automatically removed

To Check Your Retention Settings:

1. Open Settings → Advanced
2. Find the Connection History section
3. Review retention days and max events settings

Can I Export History?¶

Current Status: Export functionality is not available in the current version.

Alternatives:

• Use screenshots for documentation purposes
• Copy event details manually as needed
• Check future releases for export features

Export functionality is planned for a future update. If you need this feature, consider providing feedback to the development team.

Does History Affect Performance?¶

Minimal Impact:

• Default Settings: Negligible performance impact (< 1MB storage)
• Search & Filtering: Optimized with cached queries
• UI Rendering: Fast scrolling with lazy loading

Potential Impact (Extreme Settings):

• High Event Count (> 100 per tunnel): Brief UI delays during connection
• Long Retention (> 60 days): Increased storage usage
• Stage Events Enabled: More data recorded per connection

Recommendation: Use the default settings for optimal performance.

Privacy and Security of History Data¶

Data Security:

• Local Storage: History stored in application data (not transmitted)
• Encryption: macOS encrypts application data at rest
• No Cloud Sync: History is never uploaded to external servers
• Access Control: Only your user account can access history

Privacy Features:

• Host Anonymization: Replace hostnames with hashes
• Tunnel Exclusion: Prevent tracking of sensitive tunnels
• Clear History: Permanently remove all data

On shared or managed computers, other users with administrative access may be able to view the connection history. Enable host anonymization for additional privacy.

Troubleshooting¶

History Window Shows No Data¶

Symptoms: History window opens but displays no events.

Possible Causes:

1. No Connections: You haven't connected any tunnels yet
2. Filtering Applied: Active filters are hiding all events
3. Fresh Installation: New app with no accumulated history
4. History Cleared: All events were recently cleared

Solutions:

1. Connect to Tunnels: Establish at least one connection to populate history
2. Clear Filters: Reset all filters to show all events
3. Check Settings: Verify connection history tracking is enabled in Advanced settings
4. Wait for Data: Allow time for connections to accumulate

Can't Find Specific Connection¶

Symptoms: You remember a connection but can't find it in history.

Possible Causes:

1. Outside Time Range: Connection is outside the selected time range
2. Filtering Applied: Current filters exclude the connection
3. Retained by Exclusion: Tunnel was excluded from tracking
4. Expired: Connection is older than the retention period
5. Free Tier Limit: Only last 5 events are visible

Solutions:

1. Expand Time Range: Select "All Time" or a longer range
2. Clear Filters: Reset all filters and try searching
3. Check Exclusion: Verify the tunnel wasn't excluded in Advanced settings
4. Upgrade to Premium: Unlock full history access
5. Search Partial Terms: Try searching for partial tunnel names or host parts

Missing Recent Connections¶

Symptoms: Recent connections don't appear in history.

Possible Causes:

1. Not Yet Recorded: Connection is still active (no disconnect event yet)
2. Settings Changed: History tracking was recently disabled
3. Tunnel Excluded: Tunnel is in the exclusion list
4. App Restart: Recent events not yet persisted
5. Free Tier Limit: Only showing last 5 events

Solutions:

1. Wait for Disconnect: Active connections appear after disconnection
2. Check Settings: Verify history tracking is enabled in Advanced preferences
3. Review Exclusions: Ensure the tunnel isn't in the exclusion list
4. Refresh Window: Close and reopen the history window
5. Upgrade to Premium: View all recent connections

Statistics Don't Match Expectations¶

Symptoms: Success rate or session counts seem incorrect.

Possible Causes:

1. Time Range Filtered: Statistics reflect the selected time range only
2. Filter Applied: Active filters change which sessions are counted
3. Active Sessions: Currently active tunnels may not be counted as "completed"
4. Cached Data: Statistics need time to update after recent changes

Solutions:

1. Check Time Range: Verify the correct time range is selected
2. Clear Filters: Reset filters to see global statistics
3. Refresh View: Close and reopen the history window
4. Verify Active Tunnels: Check which tunnels are currently connected
5. Wait for Update: Allow a moment for statistics to recalculate

History Cleared Unexpectedly¶

Symptoms: History events disappeared without user action.

Possible Causes:

1. Automatic Pruning: Old events exceeded retention settings
2. Settings Changed: Retention settings were reduced
3. App Update: Migration or update cleared history
4. User Action: Someone with access to your Mac cleared it
5. Data Corruption: History file became corrupted and was reset

Solutions:

1. Check Retention Settings: Review retention period in Advanced settings
2. Review Recent Changes: Check if settings were recently modified
3. Check for Updates: See if an app update occurred
4. Enable Backup: Future versions may include history backup features
5. Rebuild History: Connect to tunnels to rebuild history from scratch

Performance Issues with Large History¶

Symptoms: History window is slow or unresponsive.

Possible Causes:

1. High Event Count: More than 100 events per tunnel stored
2. Long Retention: Retention period set very high (>60 days)
3. Stage Events Enabled: Extra data per connection slows rendering
4. Low Memory: Limited system resources affect performance
5. Search Complexity: Complex searches with many filters

Solutions:

1. Adjust Retention: Reduce retention period to 30 days or less
2. Lower Event Limit: Set max events per tunnel to 50 or lower
3. Disable Stage Events: Turn off stage event tracking in Advanced settings
4. Clear History: Remove old history and start fresh
5. Restart App: Close and reopen to clear memory

Use the default settings (50 events, 30 days retention) for best performance.

Tips & Best Practices¶

Using History for Debugging¶

Systematic Approach:

1. Filter by Error: Show only error events
2. Group by Tunnel: See which tunnels have issues
3. Review Time Patterns: Identify when errors occur
4. Correlate with Logs: Check error messages against system logs
5. Test Solutions: Fix issues and monitor for improvements

Example Workflow:

1. Search: "timeout" → Identify timeout errors
2. Filter by Tunnel: "Production DB" → Focus on problematic tunnel
3. Time Range: Last 7 Days → See recent pattern
4. Analyze: Errors occur between 2-4 AM daily
5. Solution: Adjust network settings or schedule maintenance window

Identifying Connection Patterns¶

Pattern Analysis Techniques:

• Frequency Analysis: Count connections per tunnel to identify usage patterns
• Time-of-Day Analysis: Identify peak usage hours
• Success Rate Trending: Track improvements or degradations over time
• Mode Comparison: Compare NIOSSH vs. CLI reliability
• Duration Analysis: Find abnormally long or short connections

Use Cases:

• Capacity Planning: Identify peak usage for resource allocation
• Reliability Tracking: Monitor success rate trends
• Troubleshooting: Correlate errors with time periods
• Optimization: Identify opportunities to improve connection efficiency

Finding Intermittent Issues¶

Strategies for Elusive Problems:

1. Extended Monitoring: Enable stage events for detailed diagnostics
2. Narrow Filters: Filter to a specific tunnel and error type
3. Time Range Comparison: Compare error rates across different periods
4. Mode Testing: Compare NIOSSH vs. CLI error rates
5. Error Grouping: Look for recurring error messages

Debugging Template:

Problem: Intermittent connection failures to Tunnel X
Steps:
1. Filter: Tunnel = X, Event Type = Error, Time Range = Last 7 Days
2. Note: Error occurs 3 times in 7 days (43% error rate)
3. Pattern: All errors between 9-10 AM
4. Hypothesis: Network congestion during morning hours
5. Solution: Schedule critical connections for off-peak hours

Monitoring Tunnel Reliability¶

Reliability Metrics to Track:

• Success Rate: Should be > 90% for reliable tunnels
• Error Rate: Track frequency of errors over time
• Connection Duration: Identify short-lived connections (may indicate issues)
• Mode Stability: Monitor if mode switching affects reliability
• Time-of-Day Patterns: Identify when connections fail most often

Alert Thresholds:

Recommended Monitoring:

1. Weekly Review: Check success rate and error frequency
2. Monthly Analysis: Review trends and identify patterns
3. After Changes: Monitor history after network or server changes
4. Proactive Alerts: Respond to declining success rates immediately

Use history data to identify problem tunnels, then adjust SSH mode, network settings, or tunnel configuration to improve reliability.