feature: send logs to sentry

Author: g105b

README.md

@@ -90,41 +90,6 @@ It would be helpful if you could create your issue in the appropriate repository
 [contributing]: https://github.com/PhpGt/WebEngine/blob/master/CONTRIBUTING.md
 [issues]: https://github.com/PhpGt/WebEngine/issues
 
-## Optional Sentry error reporting
-
-Install `sentry/sentry` in your application (the `sentry/sdk` meta-package also
-provides it), then configure your project's `config.ini`:
-
-```ini
-[sentry]
-dsn=https://YOUR_KEY@app.glitchtip.com/YOUR_PROJECT
-environment=production
-```
-
-The DSN can point to Sentry or a compatible service such as GlitchTip.
-The optional `sentry.environment` is trimmed and included with reported errors.
-If missing, empty or whitespace-only, the SDK's default behavior applies:
-`SENTRY_ENVIRONMENT` if supplied by the server, otherwise `production`.
-
-WebEngine initializes an SDK client in `Application::start()` when both the SDK
-and a nonempty DSN are available. No Sentry initialization in `setup.php` is necessary. Leave the
-DSN empty in environments that should not report errors.
-
-Exceptions escaping request logic are reported before the normal error page or
-custom error script runs. Failures escaping error-page rendering are also
-reported. Expected HTTP responses below 500 are excluded. Reporting failures
-do not replace the application's error response. Exceptions caught and handled
-by application code still require explicit reporting if desired.
-
-The reporter uses an injected `Sentry\ClientInterface` and PSR-7 request, without
-the SDK's global hub or default integrations. WebEngine reports fatal errors
-through its shutdown handler once the reporter is initialized. Errors before
-initialization are not captured. Performance tracing is not enabled.
-
-Request context includes only the HTTP method and URL without credentials,
-query parameters or fragments. Headers, cookies and request bodies are omitted.
-Exception messages may still contain sensitive data; review what your application throws.
-
 # Proudly sponsored by
 
 [JetBrains Open Source sponsorship program](https://www.jetbrains.com/community/opensource/)

config.default.ini

@@ -37,8 +37,12 @@ log_not_modified=false
 log_redirects=false
 ignore_post_fields=password,pass,passwd,password_confirm,password_confirmation,current_password,new_password,old_password,secret,client_secret,token,access_token,refresh_token,id_token,api_key,apikey,authorization,auth,bearer,otp,totp,mfa_code,verification_code,recovery_code,card_number,cc_number,credit_card,cvv,cvc,pin
 debug_to_javascript=true
-stderr_level=ERROR
+stderr_level=error
+; Comma-separated destinations: stdout,sentry (requires sentry.dsn and SDK).
 type=stdout
+; Levels (case-insensitive): debug,info,notice,warning,error,critical,alert,emergency.
+; One minimum level for all destinations, or comma-separated levels matching type order.
+; Example: type=sentry,stdout and level=error,debug.
 level=debug
 path=
 timestamp_format=Y-m-d H:i:s

src/Application.php

@@ -15,6 +15,8 @@
 use GT\WebEngine\Debug\OutputBuffer;
 use GT\WebEngine\Debug\Timer;
 use GT\WebEngine\Debug\SentryReporter;
+use GT\WebEngine\Debug\SentryLogHandler;
+use GT\WebEngine\Debug\LoggerConfigurationException;
 use GT\WebEngine\Redirection\Redirect;
 use GT\WebEngine\Redirection\RedirectUri;
 use GT\WebEngine\Dispatch\Dispatcher;
@@ -59,6 +61,7 @@ class Application {
 	private static bool $loggerConfigured = false;
 	private bool $finished = false;
 	private ?SentryReporter $sentryReporter = null;
+	private ?SentryLogHandler $sentryLogHandler = null;
 
 	/**
 	 * @param null|array<string, array<string, string>> $globals
@@ -99,6 +102,9 @@ public function __construct(
 		], $globals ?? $GLOBALS);
 		$this->globalProtection = $globalProtection ?? new Protection();
 		register_shutdown_function($handleShutdown ?? $this->handleShutdown(...));
+		if($this->sentryLogHandler) {
+			register_shutdown_function($this->sentryLogHandler->flush(...));
+		}
 	}
 
 	public function start():void {
@@ -138,7 +144,7 @@ public function start():void {
 
 // Initialise SDK options before protecting globals. Request context is injected
 // into the reporter, so reporting itself does not require global access.
-		$this->sentryReporter ??= SentryReporter::create($this->config, $request);
+		$this->initializeSentry();
 		$this->protectGlobals();
 
 // The Dispatcher is a core component responsible for:
@@ -263,6 +269,7 @@ private function finish(
 
 		$this->timer->stop();
 		$this->timer->logDelta();
+		$this->sentryLogHandler?->flush();
 	}
 
 	private function protectGlobals():void {
@@ -312,22 +319,11 @@ private function loadConfig():Config {
 	}
 
 	private function configureLoggerStreams():void {
+		$destinations = $this->getLoggerDestinations();
 		if(self::$loggerConfigured) {
 			return;
 		}
 
-		$minimumLogLevel = $this->getMinimumLogLevel();
-		$minimumLogLevelIndex = array_search($minimumLogLevel, LogLevel::ALL_LEVELS, true);
-		if($minimumLogLevelIndex === false) {
-			return;
-		}
-
-		$stderrMinLevel = $this->getStderrMinimumLogLevel();
-		$stderrMinLevelIndex = array_search($stderrMinLevel, LogLevel::ALL_LEVELS, true);
-		if($stderrMinLevelIndex === false) {
-			return;
-		}
-
 		if(!class_exists(StdErrHandler::class)) {
 			return;
 		}
@@ -338,7 +334,25 @@ private function configureLoggerStreams():void {
 			return;
 		}
 
-		LogConfig::setDefaultHandlerLevel($minimumLogLevel);
+		LogConfig::setDefaultHandlerLevel($this->getMinimumLogLevel());
+		foreach($destinations as $destination => $level) {
+			if($destination === "sentry") {
+				$this->sentryLogHandler = new SentryLogHandler();
+				LogConfig::addHandler($this->sentryLogHandler, $level);
+			}
+			else {
+				$this->configureLocalLogger($level);
+			}
+		}
+		self::$loggerConfigured = true;
+	}
+
+	private function configureLocalLogger(string $minimumLogLevel):void {
+		$minimumLogLevelIndex = array_search($minimumLogLevel, LogLevel::ALL_LEVELS, true);
+		$stderrMinLevelIndex = array_search($this->getStderrMinimumLogLevel(), LogLevel::ALL_LEVELS, true);
+		if($minimumLogLevelIndex === false || $stderrMinLevelIndex === false) {
+			return;
+		}
 
 		if($stderrMinLevelIndex > $minimumLogLevelIndex) {
 			$stdoutMaxLevel = LogLevel::ALL_LEVELS[$stderrMinLevelIndex - 1];
@@ -353,7 +367,13 @@ private function configureLoggerStreams():void {
 			LogLevel::ALL_LEVELS[max($stderrMinLevelIndex, $minimumLogLevelIndex)],
 			LogLevel::EMERGENCY,
 		);
-		self::$loggerConfigured = true;
+	}
+
+	private function initializeSentry():void {
+		$this->sentryReporter ??= SentryReporter::create($this->config, $this->request);
+		if($this->sentryLogHandler) {
+			$this->sentryReporter?->connectLogHandler($this->sentryLogHandler);
+		}
 	}
 
 	private function handleShutdown():void {
@@ -456,9 +476,9 @@ private function logErrorMessage(string $message, array $context = []):void {
 	}
 
 	private function getStderrMinimumLogLevel():string {
-		$configuredLevel = strtoupper(
+		$configuredLevel = strtoupper(trim(
 			$this->config->getString("logger.stderr_level") ?: LogLevel::ERROR
-		);
+		));
 		if(in_array($configuredLevel, LogLevel::ALL_LEVELS, true)) {
 			return $configuredLevel;
 		}
@@ -467,16 +487,41 @@ private function getStderrMinimumLogLevel():string {
 	}
 
 	private function getMinimumLogLevel():string {
-		$configuredLevel = $this->config->getString("logger.level")
-			?: LogLevel::DEBUG;
-		$configuredLevel = strtoupper($configuredLevel);
-		if(in_array($configuredLevel, LogLevel::ALL_LEVELS, true)) {
-			return $configuredLevel;
+		$levels = $this->getLoggerDestinations();
+		foreach(LogLevel::ALL_LEVELS as $level) {
+			if(in_array($level, $levels, true)) {
+				return $level;
+			}
 		}
-
 		return LogLevel::DEBUG;
 	}
 
+	/** @return array<string, string> */
+	private function getLoggerDestinations():array {
+		$types = array_map("trim", explode(",", strtolower($this->config->getString("logger.type") ?: "stdout")));
+		$levels = array_map("trim", explode(",", strtoupper($this->config->getString("logger.level") ?: "debug")));
+		if(count($levels) !== 1 && count($levels) !== count($types)) {
+			throw new LoggerConfigurationException(
+				"logger.level must contain one shared level or one level per logger.type destination; "
+				. count($levels) . " levels supplied for " . count($types) . " destinations."
+			);
+		}
+		$destinations = [];
+		foreach($types as $index => $type) {
+			$level = $levels[count($levels) === 1 ? 0 : $index];
+			if(!in_array($level, LogLevel::ALL_LEVELS, true)) {
+				$level = LogLevel::DEBUG;
+			}
+			// A repeated destination needs only one handler, at its lowest threshold.
+			if(isset($destinations[$type]) && array_search($destinations[$type], LogLevel::ALL_LEVELS, true)
+				< array_search($level, LogLevel::ALL_LEVELS, true)) {
+				continue;
+			}
+			$destinations[$type] = $level;
+		}
+		return $destinations;
+	}
+
 	/**
 	 * @return array<string, mixed>
 	 * @SuppressWarnings("PHPMD.Superglobals")

src/Debug/LoggerConfigurationException.php

@@ -0,0 +1,6 @@
+<?php
+namespace GT\WebEngine\Debug;
+
+use GT\WebEngine\WebEngineException;
+
+class LoggerConfigurationException extends WebEngineException {}

src/Debug/SentryLogHandler.php

@@ -0,0 +1,85 @@
+<?php
+namespace GT\WebEngine\Debug;
+
+use GT\Logger\LogHandler\LogHandler;
+use Sentry\ClientInterface;
+use Sentry\Event;
+use Sentry\Logs\Log;
+use Sentry\Logs\LogLevel;
+use Sentry\Tracing\TraceId;
+use Throwable;
+
+/** Bounded structured logging without the SDK's global hub. */
+class SentryLogHandler extends LogHandler {
+	private const BATCH_SIZE = 100;
+	/** @var array<array{level: string, message: string, timestamp: float}> */
+	private array $pending = [];
+	private ?ClientInterface $client = null;
+	private ?string $traceId = null;
+
+	public function setClient(ClientInterface $client):void {
+		$this->client = $client;
+	}
+
+	/** @param array<string, mixed> $context */
+	public function handle(string $level, string $message, array $context = []):void {
+		// Context is deliberately excluded: arbitrary values can contain secrets.
+		$this->pending []= [
+			"level" => strtoupper($level),
+			"message" => substr($message, 0, 8192),
+			"timestamp" => microtime(true),
+		];
+		if(count($this->pending) >= self::BATCH_SIZE) {
+			$this->flush();
+		}
+	}
+
+	public function flush():void {
+		if(!$this->pending) {
+			return;
+		}
+		$pending = $this->pending;
+		$this->pending = [];
+		try {
+			if(!$this->client) {
+				$this->fallback($pending);
+				return;
+			}
+			$this->traceId ??= (string)TraceId::generate();
+			$logs = [];
+			foreach($pending as $entry) {
+				$logs []= (new Log($entry["timestamp"], $this->traceId, $this->mapLevel($entry["level"]), $entry["message"]))
+					->setAttribute("sentry.environment", $this->client->getOptions()->getEnvironment() ?? Event::DEFAULT_ENVIRONMENT)
+					->setAttribute("logger.level", $entry["level"]);
+			}
+			if($this->client->captureEvent(Event::createLogs()->setLogs($logs)) === null) {
+				$this->fallback($pending);
+			}
+		}
+		catch(Throwable) {
+			$this->fallback($pending);
+		}
+	}
+
+	private function mapLevel(string $level):LogLevel {
+		return match($level) {
+			"DEBUG" => LogLevel::debug(),
+			"WARNING" => LogLevel::warn(),
+			"ERROR" => LogLevel::error(),
+			"CRITICAL", "ALERT", "EMERGENCY" => LogLevel::fatal(),
+			default => LogLevel::info(),
+		};
+	}
+
+	/** @param array<array{level: string, message: string, timestamp: float}> $entries */
+	private function fallback(array $entries):void {
+		foreach($entries as $entry) {
+			error_log("WebEngine: Sentry log delivery unavailable: {$entry['level']} {$entry['message']}");
+		}
+	}
+
+	/** @param array<string, mixed> $context */
+	protected function unwrapContext(array $context):string {
+		return "";
+	}
+}

src/Debug/SentryReporter.php

@@ -77,4 +77,8 @@ public function report(Throwable $throwable):void {
 			error_log("WebEngine: Sentry exception reporting failed.");
 		}
 	}
+
+	public function connectLogHandler(SentryLogHandler $handler):void {
+		$handler->setClient($this->client);
+	}
 }