ExESDBDashboard

Advanced Dashboard Package for EventStore Cluster Monitoring

ExESDBDashboard provides composable, real-time dashboard components for monitoring and managing EventStore clusters in Phoenix applications. Features both basic cluster monitoring and an advanced admin dashboard with comprehensive analytics.

Features

🏢 Advanced Admin Dashboard

📊 Basic Cluster Dashboard

🎨 Styling & UI

Installation

From Local Path (Development)

Add ex_esdb_dashboard to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_esdb_dashboard, path: "../beam-campus/ex-esdb-dashboard/package"},
    {:phoenix_live_view, "~> 0.18.0"},  # Required
    {:ex_esdb_gater, "~> 0.1.0"}        # For cluster integration
  ]
end

From Hex (When Published)

def deps do
  [
    {:ex_esdb_dashboard, "~> 0.1.0"}
  ]
end

Quick Start

1. Add Routes to Your Phoenix Router

# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  import ExESDBDashboard  # Import dashboard routing macro
  
  # ... your other routes
  
  scope "/admin" do
    pipe_through :browser
    dashboard_routes()  # Adds /cluster, /admin routes
  end
end

This adds the following routes:

2. Include Dashboard CSS

Option A: Import in your app.scss

// assets/css/app.scss
@import "../deps/ex_esdb_dashboard/priv/static/css/dashboard.css";

Option B: Copy CSS file to your assets

cp deps/ex_esdb_dashboard/priv/static/css/dashboard.css assets/css/

Then include it in your CSS build process.

3. Configure PubSub (Optional)

For real-time updates, ensure Phoenix.PubSub is configured in your application:

# lib/my_app/application.ex
children = [
  {Phoenix.PubSub, name: MyApp.PubSub},
  # ... other children
]

Usage Examples

Individual Components

You can mount individual dashboard components instead of using the routing macro:

# In your router
live "/cluster-status", ExESDBDashboard.ClusterLive
live "/admin-dashboard", ExESDBDashboard.AdminLive

Embedding Components

Embed dashboard components in your existing LiveViews:

defmodule MyAppWeb.AdminLive do
  use MyAppWeb, :live_view
  
  def render(assigns) do
    ~H"""
    <div class="admin-page">
      <h1>System Administration</h1>
      
<!-- Embed cluster status widget -->

      <.live_component 
        module={ExESDBDashboard.ClusterStatus} 
        id="cluster-status"
      />
      
<!-- Your other admin content -->

    </div>
    """
  end
end

Custom Styling

Override CSS custom properties to match your app's theme:

/* In your app.css */
:root {
  --dashboard-primary: #your-brand-color;
  --dashboard-success: #your-success-color;
  --dashboard-warning: #your-warning-color;
  --dashboard-danger: #your-error-color;
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --dashboard-bg: #1a1a1a;
    --dashboard-white: #2d2d2d;
    /* ... other dark mode colors */
  }
}

API Reference

Main Module Functions

# Get cluster data programmatically
ExESDBDashboard.get_cluster_data()
# => %{nodes: [...], stores: [...], total_streams: 42, cluster_health: :healthy}

# Individual data functions
ExESDBDashboard.cluster_health()    # => :healthy | :degraded | :unhealthy
ExESDBDashboard.cluster_nodes()     # => [%{name: :node1, status: :connected, ...}]
ExESDBDashboard.cluster_stores()    # => [%{id: "store1", stream_count: 10, ...}]
ExESDBDashboard.total_streams()     # => 42

Component References

# Get LiveView component modules
ExESDBDashboard.cluster_live_component()     # => ExESDBDashboard.ClusterLive
ExESDBDashboard.admin_live_component()       # => ExESDBDashboard.AdminLive
ExESDBDashboard.cluster_status_component()   # => ExESDBDashboard.ClusterStatus

Advanced Features

Real-time Updates

The dashboard subscribes to PubSub topics for real-time updates:

Publish to these topics from your application:

# Broadcast health updates
Phoenix.PubSub.broadcast(
  MyApp.PubSub, 
  "cluster_health_updates", 
  {:cluster_health_update, :healthy}
)

# Broadcast system events
Phoenix.PubSub.broadcast(
  MyApp.PubSub,
  "system_events",
  {:system_event, %{type: "backup_completed", message: "Database backup finished"}}
)

Performance Monitoring

The admin dashboard includes performance metrics tracking:

Log Monitoring

System logs with filtering capabilities:

Configuration

Environment Variables

# config/config.exs
config :ex_esdb_dashboard,
  # Update interval for auto-refresh (milliseconds)
  update_interval: 5_000,
  # Maximum number of log entries to keep
  max_log_entries: 100,
  # Maximum number of activity entries
  max_activity_entries: 20,
  # PubSub module to use
  pubsub: MyApp.PubSub

Theme Customization

The dashboard uses CSS custom properties for easy theming:

:root {
  /* Primary colors */
  --dashboard-primary: #2563eb;
  --dashboard-success: #059669;
  --dashboard-warning: #d97706;
  --dashboard-danger: #dc2626;
  
  /* Background colors */
  --dashboard-bg: #f9fafb;
  --dashboard-white: #ffffff;
  --dashboard-border: #e5e7eb;
  
  /* Text colors */
  --dashboard-gray-dark: #374151;
  --dashboard-gray: #6b7280;
  
  /* Layout */
  --dashboard-radius: 0.5rem;
  --dashboard-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
}

Requirements

Host Application Requirements

Your Phoenix application must have:

  1. Phoenix LiveView configured and running
  2. Phoenix.PubSub configured (for real-time updates)
  3. ExESDBGater.System started in supervision tree (for cluster data)

Development

Setup

git clone https://github.com/beam-campus/ex-esdb-dashboard.git
cd ex-esdb-dashboard/package
mix deps.get
mix test

Running Tests

mix test
mix test --cover

Building Documentation

mix docs
open doc/index.html

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v0.2.0 (2025-08-16)

v0.1.0 (Initial Release)

Support

For questions, issues, or contributions: