Skip to main content

Telescope Debugging and Monitoring

This document describes how Farfalla uses Laravel Telescope for debugging and monitoring across all environments, including cross-subdomain request tracking.

Overview​

Telescope is a key debugging tool used across all environments:

  • Local: Always enabled with TELESCOPE_ENABLED=true
  • Production/Staging: On-demand via IP-based authorization (also requires TELESCOPE_ENABLED=true)
  • Dashboard: /telescope (accessible to super admins only)
  • Cross-domain support: IP-based authorization works across ALL domains automatically
  • Auto-pruning: Old entries automatically deleted (48 hours retention)

Activating Telescope​

In Production and Staging​

Telescope requires both environment configuration and IP authorization:

  1. Environment Configuration: TELESCOPE_ENABLED=true must be set via Laravel Vapor's environment variables editor (not in encrypted .env files)
  2. IP Authorization: Super admins activate data collection via Nova:
    • Log into Nova on any subdomain
    • Open the Dev Mode menu in the sidebar (super admins only)
    • Click Telescope to load the dashboard
    • Use "Add my IP" to authorize yourself (60-minute expiration shown inline)

While your IP is active, you can:

  • Click "Extend TTL" on any active IP to reset its expiration back to 60 minutes
  • Use "Remove my IP (Xm)" to immediately disable Telescope for your IP

The dashboard lists every authorized IP with remaining time. Removing your IP immediately disables Telescope for you.

In Local​

As long as TELESCOPE_ENABLED=true is set in .env, Telescope is always active. No IP authorization needed.

Cross-Domain IP Authorization​

Telescope uses IP-based authorization stored in cache (60-minute TTL) to enable seamless cross-domain request tracking without cookies or CORS complexity.

Universal Domain Support ✅​

IP-based authorization works automatically across ALL domains because it's a server-side check:

  • Main app: app.publica.la ✅
  • Tenant subdomains: {tenant}.publica.la (e.g., loadtestingstore.publica.la) ✅
  • Volpe reader: volpe.publica.la ✅
  • Custom domains: kiosco.latercera.com ✅
  • Staging app: staging-farfalla.publica.la ✅
  • Staging tenants: {tenant}.publicala.me ✅

When Telescope is toggled from any domain, ALL requests from your IP are captured across:

  • All platform subdomains
  • All tenant custom domains
  • All AJAX/API requests (Volpe → App, etc.)
  • All cross-domain interactions

No browser restrictions, no CORS configuration, no third-party cookie blocking.

Considerations​

  • Multiple admins behind same NAT: All will get Telescope access (acceptable tradeoff)
  • Dynamic IPs: If your IP changes, simply re-toggle Telescope
  • Shared cache requirement: Cache must be accessible across all Farfalla instances (Redis/Valkey recommended)
  • 60-minute auto-expiry: Balances security with debugging convenience (extendable via "Extend TTL" button)

Accessing Telescope​

Telescope data collection is centralized and not tenant-scoped (but tenant-labeled). While the dashboard is accessible via any domain where you're authenticated:

  • https://app.publica.la/telescope
  • https://staging-farfalla.publica.la/telescope
  • https://kiosco.latercera.com/telescope

All tenant data can be accessed from any of these URLs. The recommended approach is to use https://app.publica.la/telescope or https://staging-farfalla.publica.la/telescope for simplicity.

Only super admins can access Telescope.

Data Retention and Pruning​

Telescope automatically prunes old data to prevent database bloat:

  • Retention period: 48 hours
  • Pruning mechanism: Lottery-based (runs automatically on random requests)

Manual Pruning​

# From host
cd farfalla

# Run pruning command
zar telescope:prune

# Prune specific hours
zar telescope:prune --hours=24

Resources​

X

Graph View