How to Monitor Phoenix Storybook with Vigilmon

Phoenix Storybook is a UI component development, documentation, and testing environment for Phoenix LiveView applications. It provides an isolated rendering sandbox for components, an interactive playground for experimenting with different prop combinations, and a visual regression testing harness for catching unintended UI changes. Teams working on design systems, shared component libraries, or complex LiveView UIs rely on Storybook as the single source of truth for what components look and behave like. When the Storybook server goes down, a component build breaks, or the visual baseline becomes stale, UI development stalls silently.

Vigilmon keeps your Storybook environment observable: HTTP monitors confirm the server is running and rendering components, heartbeats from CI pipelines verify visual regression suites are executing, and instant alerts fire when your component catalog breaks or drifts.

This tutorial covers:

• HTTP monitoring for Phoenix Storybook servers
• Heartbeat monitoring for visual regression CI pipelines
• Alerting on component build failures and catalog staleness
• Status pages for design system teams

What to Monitor in a Phoenix Storybook Deployment

| Layer | What it is | How to monitor | |---|---|---| | Storybook server | Phoenix app serving the component catalog | HTTP uptime check | | Component rendering | LiveView stories loading without errors | HTTP check with keyword match | | Visual regression CI | Automated screenshot comparison pipeline | Heartbeat on pipeline completion | | Asset pipeline | CSS/JS compilation for component styles | HTTP check on asset URL | | Story compilation | Mix task compiling story definitions | Heartbeat on build completion |

Step 1: Add HTTP monitoring for your Storybook server

Phoenix Storybook runs as a Phoenix application (often a separate endpoint from your main app). The simplest monitoring is an HTTP check on the root path — but a dedicated health route is more reliable:

Add a health endpoint to your Storybook app:

# lib/my_app_storybook/router.ex
defmodule MyAppStorybook.Router do
  use Phoenix.Router

  import Phoenix.LiveView.Router

  pipeline :browser do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_live_flash
    plug :put_root_layout, {MyAppStorybook.Layouts, :root}
    plug :protect_from_forgery
    plug :put_secure_browser_headers
  end

  scope "/", MyAppStorybook do
    pipe_through :browser

    live_storybook "/storybook", backend: MyAppStorybook.Storybook
    get "/health", HealthController, :index
  end
end

defmodule MyAppStorybook.HealthController do
  use MyAppStorybook, :controller

  def index(conn, _params) do
    story_count = MyAppStorybook.Storybook.story_count()
    component_count = MyAppStorybook.Storybook.component_count()

    status = if story_count > 0, do: 200, else: 503

    conn
    |> put_status(status)
    |> json(%{
      status: if(status == 200, do: "ok", else: "no_stories"),
      stories: story_count,
      components: component_count
    })
  end
end

In Vigilmon:

1. Click New Monitor → HTTP.
2. Enter https://storybook.your-app.example.com/health.
3. Set check interval to 2 minutes.
4. Set keyword match to "ok" so a zero-story catalog (broken build) triggers an alert.

For internal Storybook servers not accessible from the internet, run Vigilmon's uptime check from a monitoring host on your internal network or VPN.

Step 2: Monitor specific component stories

Beyond the root health check, verify that critical component stories actually render. A LiveView story that raises during mount will return 500 or produce an empty render — detectable with keyword monitoring:

# lib/my_app_storybook/components/button_story.ex
defmodule MyAppStorybook.ButtonStory do
  use PhoenixStorybook.Story, :component

  def component, do: MyAppWeb.Components.Button

  def variations do
    [
      %Variation{
        id: :primary,
        attributes: %{label: "Submit", variant: :primary}
      },
      %Variation{
        id: :secondary,
        attributes: %{label: "Cancel", variant: :secondary}
      }
    ]
  end
end

Add HTTP monitors for story-level URLs in Vigilmon:

1. Click New Monitor → HTTP.
2. Enter https://storybook.your-app.example.com/storybook/components/button.
3. Set keyword match to a string that appears only on a successfully rendered story (e.g., "Submit").
4. If the keyword is missing, the component failed to render.

Repeat for your most critical shared components — forms, modals, navigation elements.

Step 3: Heartbeat from visual regression CI pipelines

Visual regression testing runs in CI — typically after each merge to your main branch. A heartbeat from the end of the pipeline tells you the suite ran and passed; a missed heartbeat means CI broke or the suite is failing silently.

Add a heartbeat step to your GitHub Actions workflow:

# .github/workflows/visual_regression.yml
name: Visual Regression

on:
  push:
    branches: [main]

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Elixir
        uses: erlef/setup-beam@v1
        with:
          elixir-version: '1.16'
          otp-version: '26'

      - name: Install dependencies
        run: mix deps.get

      - name: Start Storybook server
        run: mix phx.server &
        env:
          PHX_SERVER: true
          MIX_ENV: test

      - name: Wait for server
        run: |
          until curl -sf http://localhost:4001/health; do sleep 2; done

      - name: Run visual regression
        run: mix storybook.visual_regression --base-url http://localhost:4001

      - name: Ping Vigilmon on success
        if: success()
        run: curl -sf "${{ secrets.VIGILMON_VISUAL_REGRESSION_URL }}"

In Vigilmon:

1. Click New Monitor → Heartbeat.
2. Name it Storybook visual regression CI.
3. Set expected interval to match your CI cadence — for multiple merges per day, use 4 hours; for daily releases use 25 hours.
4. Add the heartbeat URL to your CI secrets.

Step 4: Monitor the story compilation build step

When developers add new stories or modify component APIs, a compile step must succeed for Storybook to load updated stories. In development environments, add a compilation health check:

# mix.exs
defmodule MyApp.MixProject do
  use Mix.Project

  defp aliases do
    [
      "storybook.build": ["compile", "assets.build", &ping_vigilmon_on_success/1]
    ]
  end

  defp ping_vigilmon_on_success(_) do
    url = System.get_env("VIGILMON_BUILD_HEARTBEAT_URL")

    if url do
      System.cmd("curl", ["-sf", url])
      IO.puts("Vigilmon build heartbeat sent")
    end
  end
end

For staging environments with automated builds, add this to your deploy script so a failed compilation is reflected in Vigilmon within minutes.

Step 5: Configure alerts for design system failures

| Monitor | Condition | Action | |---|---|---| | Storybook HTTP health | Non-200 or keyword miss | Slack #design-system — server down | | Button story HTTP | Keyword miss | Slack #frontend-eng — component broken | | Visual regression heartbeat | Missed ≥ 1× | Slack #frontend-eng — CI suite skipped | | Story build heartbeat | Missed ≥ 2× | Email frontend lead |

Design system failures rarely justify PagerDuty escalation unless Storybook is used in production (e.g., as an embedded component gallery). Route alerts to Slack channels where the UI team can triage during working hours.

Step 6: Status page for design system consumers

When your component library is shared across multiple teams or products, a status page makes outages visible to all consumers:

1. Go to Status Pages → New Page.
2. Add monitors: Storybook server, visual regression CI, critical component stories.
3. Name components clearly: "Component Catalog", "Visual Regression Tests", "Button Components", "Form Components".
4. Set visibility to Team and share with frontend engineers and designers.

Key Metrics to Watch

| Metric | Threshold | Meaning | |---|---|---| | Storybook HTTP health | Must return 200 + keyword | Server running with stories loaded | | Story render check | Keyword present | Component mounting without errors | | Visual regression heartbeat | < 1 missed cycle | Screenshot comparison suite executing | | Story count | > 0 | Build not wiping catalog on error | | Response time | < 2 seconds | LiveView stories loading promptly |

Why Monitor Phoenix Storybook?

Storybook failures are easy to miss because they affect developer productivity, not end users:

• Silent story build failures — a compile error in one story file can cause the entire catalog to render blank without a visible server error
• Asset pipeline breaks — CSS compilation failures leave components unstyled; the story renders but looks wrong, and no monitor catches it unless you check visually
• Visual regression suite drift — without a heartbeat confirming the CI suite ran, the baseline can become stale and your comparisons meaningless
• LiveView upgrade regressions — Phoenix/LiveView version bumps can break story rendering in subtle ways that only appear at runtime in the Storybook sandbox

Vigilmon's HTTP keyword monitoring is particularly well suited here: check for specific text that only appears when a component renders correctly, and you catch both server-down and component-broken scenarios in a single monitor.

Conclusion

Phoenix Storybook is the component development hub for LiveView teams. Vigilmon makes it observable: HTTP checks confirm the server is alive and stories are loading, heartbeats from CI verify your visual regression suite is actually running, and keyword monitors catch silent component failures before they block the next sprint. Set it up once and your design system stays as monitored as your production API.

Get started free at vigilmon.online.