Laravel Telemetry Ui Laravel Package

Getting Started

First Steps

1. Installation Run:

   composer require cboxdk/laravel-telemetry-ui
   php artisan vendor:publish --provider="Cboxdk\TelemetryUI\TelemetryUIServiceProvider" --tag="config"
   php artisan migrate
   

   Publish the config (config/telemetry-ui.php) and run migrations to set up the database tables for saved queries/dashboards.

2. Prerequisites Ensure your Laravel app has:

   • cboxdk/laravel-telemetry installed (this package’s dependency).
   • A working Tempo, Loki, and Prometheus/Mimir stack (or compatible alternatives).
   • Livewire installed (laravel/livewire).

3. First Use Case: Quick Dashboard Add the UI to your layout:

   @telemetryUI
   

   This renders the default dashboard with pre-configured cards for:

   • Latency (Tempo traces)
   • Logs (Loki queries)
   • Metrics (Prometheus/Mimir)

   Customize via the telemetry-ui.php config (e.g., adjust time ranges, default queries).

Implementation Patterns

1. Extending with Custom Cards

Create a Livewire component for a custom card:

php artisan make:livewire CustomMetricsCard

Register it in config/telemetry-ui.php:

'cards' => [
    'custom' => [
        'component' => 'custom-metrics-card',
        'label' => 'Custom Metrics',
        'default_query' => 'sum(rate(http_requests_total[5m])) by (service)',
    ],
],

2. Querying Data Programmatically

Use the TelemetryUI facade to fetch raw data (e.g., for APIs or background jobs):

use Cboxdk\TelemetryUI\Facades\TelemetryUI;

// Fetch logs from Loki
$logs = TelemetryUI::logs()
    ->query('{job="api"} | json')
    ->timeRange('1h')
    ->fetch();

// Fetch traces from Tempo
$traces = TelemetryUI::traces()
    ->query('service="user-service"')
    ->limit(10)
    ->fetch();

3. Integrating with Existing Workflows

• Auth Integration: Use middleware to restrict dashboard access:

  Route::middleware(['auth:sanctum'])->group(function () {
      Route::telemetryUI();
  });
  

• Dynamic Time Ranges: Pass time ranges via URL or session:

  TelemetryUI::setTimeRange(request('range', '1h'));
  

• Theming: Override Blade styles in resources/css/telemetry-ui.css:

  .telemetry-card { border: 2px solid #3b82f6; }
  

4. Saving User Queries

Leverage the built-in query storage:

// Save a query for a user
TelemetryUI::saveQuery(
    userId: auth()->id(),
    type: 'logs',
    query: '{job="api"} | json',
    label: 'API Logs'
);

// Retrieve saved queries
$userQueries = TelemetryUI::getSavedQueries(auth()->id());

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • Ensure cboxdk/laravel-telemetry is installed before this package. The UI relies on its underlying clients (e.g., grafana/tempo-client-php).
   • Fix: Run composer require cboxdk/laravel-telemetry if missing.

2. CORS Issues

   • If querying remote Tempo/Loki/Prometheus, ensure your Laravel app’s CORS settings allow requests to the observability stack.
   • Fix: Add to config/cors.php:

     'paths' => ['telemetry-ui/*', 'api/telemetry/*'],
     'allowed_methods' => ['GET', 'POST', 'OPTIONS'],
     'allowed_origins' => ['*'], // Or restrict to your app's domain
     

3. Livewire Component Conflicts

   • If using other Livewire components, namespace your custom cards to avoid class collisions:

     namespace App\Livewire\Telemetry;
     class CustomCard extends Component { ... }
     

4. Rate Limiting

   • Heavy queries (e.g., large trace exports) may hit rate limits in Tempo/Loki.
   • Fix: Use ->limit() and ->timeRange() to constrain queries:

     TelemetryUI::traces()->query('...')->limit(50)->timeRange('5m');
     

Debugging Tips

• Check Config Values: Validate config/telemetry-ui.php for correct endpoints (e.g., tempo.url, loki.url).
• Log Queries: Enable debug mode in the config:

  'debug' => env('TELEMETRY_UI_DEBUG', false),
  

  This logs queries to storage/logs/telemetry-ui.log.
• Test Queries Manually: Use the Tempo/Loki/Prometheus UI to verify queries work before integrating.

Extension Points

1. Custom Data Sources Extend the Cboxdk\TelemetryUI\Contracts\QueryBuilder interface to support non-Grafana stacks (e.g., Datadog, New Relic):

   class CustomQueryBuilder implements QueryBuilder {
       public function query(string $q): self { ... }
       public function fetch(): array { ... }
   }
   

   Register via the service provider.

2. Plugin System Use Laravel’s package discovery to auto-load card components:

   // In TelemetryUIServiceProvider
   $this->loadViewsFrom(__DIR__.'/../resources/views', 'telemetry-ui');
   

3. Webhook Alerts Combine with laravel-telemetry’s alerting to trigger UI notifications:

   TelemetryUI::alert()
       ->type('metric')
       ->condition('error_rate > 0.1')
       ->notifyVia('database'); // Stores alerts in DB for UI display
   

4. Dark Mode Support Override the default Tailwind classes in your app’s CSS:

   @media (prefers-color-scheme: dark) {
       .telemetry-card { background: #1a1a1a; }
   }