Update to use Laravel 12, FrankenPHP and OpenTelemetry.

Author: mintopia

README.md

@@ -20,7 +20,18 @@ These are using Laravel Socialite, so any provider supported by Socialite can be
 
 These are custom integrations but more can be added and used if people develop them. The Internal provider allows you to manually issue tickets to users.
 
-## Setup
+
+## Technology
+
+This project is written in PHP 8.4 using the Laravel 12 framework. It was migrated from Laravel 10 and 11 so has some
+legacy project structure - but this is the intended upgrade path.
+
+Horizon and Telescope are installed and enabled, with access limited to the admin role. The application itself is
+served using Laravel Octane and FrankenPHP.
+
+Websocket communications are handled using Laravel Reverb.
+
+## Development Setup
 
 You will need to create a Discord application and have the Client ID and Client Secret available.
 
@@ -43,108 +54,52 @@ You should now be able to login. The first user will be given the admin role.
 
 ## Production Deployment
 
-I use the following docker-compose for running this in production:
-
-```yaml
-version: '3'
-services:
-  nginx:
-    image: ghcr.io/mintopia/control-nginx:develop
-    env_file: .env.nginx
-    restart: unless-stopped
-    depends_on:
-      - php-fpm
-    networks:
-      - frontend
-      - default
-    volumes:
-      - ./public:/var/www/storage/public
-
-  php-fpm:
-    image: ghcr.io/mintopia/control-php-fpm:develop
-    env_file: .env
-    restart: unless-stopped
-    depends_on:
-      - redis
-      - database
-    volumes:
-      - ./logs:/var/www/storage/logs
-      - ./public:/var/www/storage/public
-
-  redis:
-    image: redis:6.2.6
-    restart: unless-stopped
-
-  database:
-    image: mariadb:10.5-focal
-    env_file: .env.mariadb
-    restart: unless-stopped
-    volumes:
-      - ./database:/var/lib/mysql
-
-  worker:
-    image: ghcr.io/mintopia/control-php-fpm:develop
-    restart: unless-stopped
-    deploy:
-      replicas: 2
-    env_file: .env
-    depends_on:
-      - database
-      - redis
-    volumes:
-      - ./logs:/var/www/storage/logs
-      - ./public:/var/www/storage/public
-    entrypoint: ['php']
-    command: 'artisan queue:work'
-
-
-  scheduler:
-    image: ghcr.io/mintopia/control-php-fpm:develop
-    restart: unless-stopped
-    env_file: .env
-    depends_on:
-      - database
-      - redis
-    volumes:
-      - ./logs:/var/www/storage/logs
-      - ./public:/var/www/storage/public
-    entrypoint: ['php']
-    command: 'artisan schedule:work'
-
-  artisan:
-    image: ghcr.io/mintopia/control-php-fpm:develop
-    profiles:
-      - artisan
-    env_file: .env
-    depends_on:
-      - database
-      - redis
-    volumes:
-      - ./logs:/var/www/storage/logs
-      - ./public:/var/www/storage/public
-    entrypoint: ['php', 'artisan']
-
-networks:
-  frontend:
-    external: true
-```
+In the `example` directory there is a docker compose file and some .env example files. These are for the setup I use.
+Just rename the .env files and edit them accordingly. You can get a [random Laravel application key here](https://generate-random.org/laravel-key-generator).
+
+You need to expose the `control` container to the public. This is configured to listen on port 80
+in the docker compose, so you probably want something like Traefik or Caddy in-front as a reverse proxy.
+
+I'm running this with an external docker network called `frontend` with Caddy running as HTTP/HTTPS ingress. You will
+need to add a network section for the `control` service to add it to the `frontend` network if you
+want to do this.
 
-I'm running with an external docker network called `frontend` with Caddy running as HTTP/HTTPS ingress. To bring up the site, run the following:
+You will need to make a logs directory and chmod it 777 as I still need to sort permissions out.
 
+To bring up the site, run the following:
 
 ```bash
-# Create your docker compose file
-# Create your .env file from the project's .env.example and edit as required.
 docker compose up -d redis database
-docker compose run --rm artisan key:generate
 docker compose run --rm artisan migrate
 docker compose run --rm artisan db:seed
-docker compose run --rm artisan control:setup-discord
+docker compose run --rm artisan setup:discord
 docker compose up -d
 ```
 
 You should now be able to visit the site and login. From here you can use the admin menu to configure the site.
 
+## Observability
+
+Control supports basic observability functionality in using an OpenTelemetry collector. It can support traces, logs
+and metrics. If enabled, it will create traces for all HTTP requests. To enable it, add the following to your `.env`:
+
+```dotenv
+OPENTELEMETRY_ENABLED=true
+```
+
+For logging output, a logger is defined and can be used. I suggest you use this with your usual logger, eg. `daily`.
+You can specify this logging with the following environment variables:
+
+```dotenv
+LOG_CHANNEL=stack
+LOG_STACK=opentelemetry,daily
+```
+
+By default it is configured to send to an OpenTelemetry container running with the name `collector`. An example config
+is supplied with placeholders for sending data to [Honeycomb](https://www.honeycomb.io/).
+
+The plan will be to add further spans within individual requests and have spans for the jobs and queued actions.
+
 ## Contributing
 
 It's an open source project and I'm happy to accept pull requests. I am terrible at UI and UX, which is why this is entirely using server-side rendering. If someone wants to use Vue/Laravel Livewire - please go ahead!

app/Http/Kernel.php

@@ -4,6 +4,7 @@
 
 use App\Http\Middleware\Authenticate;
 use App\Http\Middleware\EncryptCookies;
+use App\Http\Middleware\MeasureRequest;
 use App\Http\Middleware\MetricsCollector;
 use App\Http\Middleware\PreventRequestsDuringMaintenance;
 use App\Http\Middleware\RedirectIfAuthenticated;
@@ -41,6 +42,7 @@ class Kernel extends HttpKernel
      * @var array<int, class-string|string>
      */
     protected $middleware = [
+        MeasureRequest::class,
         MetricsCollector::class,
         // \App\Http\Middleware\TrustHosts::class,
         TrustProxies::class,

app/Http/Middleware/MeasureRequest.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use App\Services\OpenTelemetry;
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Route;
+use OpenTelemetry\SemConv\TraceAttributes;
+use Symfony\Component\HttpFoundation\Response;
+
+class MeasureRequest
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (!config('open-telemetry.enabled')) {
+            return $next($request);
+        }
+
+        $name = Route::currentRouteName();
+        if ($name === null) {
+            $name = $request->getRequestUri();
+        }
+        $trace = $request->header('traceparent');
+        $state = $request->header('tracestate');
+        $span = OpenTelemetry::startSpan(name: "{$request->getMethod()} {$name}", parentTrace: $trace, parentState: $state);
+        $span->span->setAttributes([
+            TraceAttributes::HTTP_REQUEST_METHOD => $request->getMethod(),
+            TraceAttributes::HTTP_URL => $request->getRequestUri(),
+        ]);
+        if (Route::getCurrentRoute() !== null) {
+            $span->span->setAttribute(TraceAttributes::HTTP_ROUTE, Route::getCurrentRoute()->uri());
+        }
+
+        $request->attributes->set('traceId', $span->span->getContext()->getTraceId());
+
+        $response = $next($request);
+        $response->headers->set('X-TraceId', $span->span->getContext()->getTraceId());
+        $span->span->setAttribute(TraceAttributes::HTTP_RESPONSE_STATUS_CODE, $response->getStatusCode());
+        $span->end();
+        return $response;
+    }
+}

app/Providers/OpenTelemetryProvider.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
+use OpenTelemetry\Contrib\Otlp\ContentTypes;
+use OpenTelemetry\Contrib\Otlp\LogsExporter;
+use OpenTelemetry\Contrib\Otlp\MetricExporter;
+use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
+use OpenTelemetry\Contrib\Otlp\SpanExporter;
+use OpenTelemetry\SDK\Common\Attribute\Attributes;
+use OpenTelemetry\SDK\Logs\LoggerProvider;
+use OpenTelemetry\SDK\Logs\Processor\SimpleLogRecordProcessor;
+use OpenTelemetry\SDK\Metrics\MeterProvider;
+use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
+use OpenTelemetry\SDK\Resource\ResourceInfo;
+use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
+use OpenTelemetry\SDK\Sdk;
+use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
+use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
+use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
+use OpenTelemetry\SDK\Trace\TracerProvider;
+use OpenTelemetry\SemConv\ResourceAttributes;
+
+class OpenTelemetryProvider extends ServiceProvider
+{
+    /**
+     * Register services.
+     */
+    public function register(): void
+    {
+    }
+
+    /**
+     * Bootstrap services.
+     */
+    public function boot(): void
+    {
+        $this->initOpenTelemetry();
+    }
+
+    protected function initOpenTelemetry(): void
+    {
+        $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
+            ResourceAttributes::SERVICE_NAMESPACE => config('open-telemetry.service.namespace'),
+            ResourceAttributes::SERVICE_NAME => config('open-telemetry.service.name'),
+            ResourceAttributes::SERVICE_VERSION => config('open-telemetry.service.version'),
+            ResourceAttributes::DEPLOYMENT_ENVIRONMENT_NAME => config('open-telemetry.environment'),
+            ResourceAttributes::HOST_NAME => getenv('HOSTNAME'),
+        ])));
+        $tracesEndpoint = config('open-telemetry.endpoints.traces');
+        $spanExporter = new SpanExporter(
+            (new OtlpHttpTransportFactory())->create($tracesEndpoint, ContentTypes::JSON)
+        );
+
+        $logsEndpoint = config('open-telemetry.endpoints.logs');
+        $logExporter = new LogsExporter(
+            (new OtlpHttpTransportFactory())->create($logsEndpoint, ContentTypes::JSON)
+        );
+
+        $metricsEndpoint = config('open-telemetry.endpoints.metrics');
+        $reader = new ExportingReader(
+            new MetricExporter(
+                (new OtlpHttpTransportFactory())->create($metricsEndpoint, ContentTypes::JSON)
+            )
+        );
+
+        $meterProvider = MeterProvider::builder()
+            ->setResource($resource)
+            ->addReader($reader)
+            ->build();
+
+        $tracerProvider = TracerProvider::builder()
+            ->addSpanProcessor(
+                new SimpleSpanProcessor($spanExporter)
+            )
+            ->setResource($resource)
+            ->setSampler(new ParentBased(new AlwaysOnSampler()))
+            ->build();
+
+        $loggerProvider = LoggerProvider::builder()
+            ->setResource($resource)
+            ->addLogRecordProcessor(
+                new SimpleLogRecordProcessor($logExporter)
+            )
+            ->build();
+
+        Sdk::builder()
+            ->setTracerProvider($tracerProvider)
+            ->setMeterProvider($meterProvider)
+            ->setLoggerProvider($loggerProvider)
+            ->setPropagator(TraceContextPropagator::getInstance())
+            ->setAutoShutdown(true)
+            ->buildAndRegisterGlobal();
+    }
+}