Getting Started

Minimal Setup

Install Dependencies:

composer require agenticmorf/fluxui-loki livewire/flux-pro
php artisan flux:publish date-picker time-picker chart

Configure Loki URL in .env:

LOKI_URL=http://loki:3100  # Default for Sail/Docker

Publish Config (optional):

php artisan vendor:publish --tag=fluxui-loki-config

Add Sidebar Link: Include a nav item in your Flux sidebar (e.g., resources/views/components/layouts/app/sidebar.blade.php):
```
<x-flux.nav-item href="{{ route('logs') }}" icon="document-text">
    Logs
</x-flux.nav-item>
```
Access Dashboard: Visit /logs (or your configured route) to query logs.

Implementation Patterns

Core Workflow

Query Logs: The dashboard auto-populates a service dropdown using the service_label config (default: compose_service). Select a service, then use Flux Pro’s date/time pickers to filter logs.
```
// Example: Customize the service dropdown in a published view
// resources/views/vendor/fluxui-loki/logs.blade.php
<x-flux.select name="service" :options="$services" label="Service" />
```
Log Display: Logs render in a Flux Pro chart (line/bar) or raw table (customizable via published views). Use the chart component for visualizations:
```
<x-flux.chart :data="$logs" type="line" />
```
Real-Time Updates: Leverage Livewire’s reactivity. Modify the LogsController to refresh logs on demand:
```
public function updatedService($service)
{
    $this->fetchLogs($service);
}
```
Integration with Sail/Docker: For Laravel Sail, ensure your docker-compose.yml includes Loki:
```
services:
  loki:
    image: grafana/loki:latest
    ports:
      - "3100:3100"
```

Advanced Patterns

Custom Labels: Override service_label in config if using non-standard Loki labels (e.g., job or container_name).

Middleware: Restrict access via middleware in config:

'middleware' => ['web', 'auth', 'verified'], // Example: Add 'verified'

Multi-Tenant: Dynamically set LOKI_URL per tenant by extending the LogsController:

protected function getLokiUrl()
{
    return Tenant::current()->lokiUrl ?? config('fluxui-loki.url');
}

Gotchas and Tips

Common Pitfalls

Flux Pro Dependencies:
- Forgetting to publish Flux Pro components (date-picker, time-picker, chart) will break the UI. Run:
```
php artisan flux:publish date-picker time-picker chart
```
- Fix: Ensure livewire/flux-pro is installed and published.
Loki URL Mismatch:
- If logs don’t load, verify LOKI_URL matches your Loki instance (e.g., http://localhost:3100 for local dev).
- Debug: Check the network tab for CORS errors or 404s on /loki/api/v1/query.
Label Mismatch:
- The service dropdown fails if service_label doesn’t match Loki’s labels. Defaults to compose_service (common in Sail).
- Fix: Update config/fluxui-loki.php or adjust your Loki label query.
Livewire Caching:
- Log queries may cache unexpectedly. Clear Livewire cache if data appears stale:
```
php artisan cache:clear
php artisan view:clear
```

Debugging Tips

Log Queries: Enable debug mode in config/fluxui-loki.php to log raw Loki queries:
```
'debug' => env('APP_DEBUG', false),
```
Custom Views: Publish and override views for granular control:
```
php artisan vendor:publish --tag=fluxui-loki-views
```
Modify resources/views/vendor/fluxui-loki/logs.blade.php to add/remove fields.
Performance:
- Loki queries can be slow. Limit time ranges or use limit in queries:
```
$query->limit(1000); // Reduce log volume
```
- Tip: Use Flux Pro’s time-picker to constrain queries to recent data.

Extension Points

Custom Controllers: Extend the default LogsController to add features (e.g., log search):

namespace App\Http\Controllers;

use AgenticMorf\FluxUILoki\Http\Controllers\LogsController as BaseController;

class LogsController extends BaseController
{
    public function search($query)
    {
        $this->logs = $this->queryLogs()->where('line', 'like', "%{$query}%")->get();
    }
}

Dynamic Labels: Fetch labels dynamically from Loki’s API:

public function getServices()
{
    $response = Http::get(config('fluxui-loki.url').'/api/v1/series', [
        'limit' => 100,
        'match' => ['job' => '.*'],
    ]);
    return collect($response->json()['data'])->pluck('values.0')->unique()->toArray();
}

Alerting: Integrate with Laravel Notifications to alert on critical logs:

if (str_contains($log, 'ERROR')) {
    Notification::route('mail', $user)->notify(new LogAlert($log));
}

Theming: Customize Flux Pro components via Tailwind CSS. Override styles in your app.css:
```
/* Target Flux Pro components */
.flux-chart { --chart-bg: #1a202c; }
```

Configuration Quirks

Sail-Specific: If using Sail, ensure your docker-compose.yml exposes Loki’s port (3100) and networks match:
```
services:
  loki:
    networks:
      - sail
```
HTTPS: For production, use HTTPS in LOKI_URL (e.g., https://loki.yourdomain.com).
Rate Limiting: Loki may throttle requests. Adjust timeout in config/fluxui-loki.php:
```
'timeout' => 30, // Seconds
```

Pro Tips

Log Retention: Configure Loki’s retention policies in loki-config.yml to manage storage costs.
Log Sampling: Use Loki’s limit and offset to paginate logs efficiently.
CI/CD: Test Loki queries in GitHub Actions by spinning up a temporary Loki instance:
```
services:
  loki:
    image: grafana/loki:latest
    ports:
      - "3100:3100"
```

Fluxui Loki Laravel Package