PHP Monolog logs (#14781)

closes [#1893](getsentry/sentry-php#1893)
closes PHP-22

---------

Co-authored-by: Martin Linzmayer <[email protected]>

Author: cleptric

docs/platforms/php/common/integrations/monolog.mdx

@@ -1,11 +1,65 @@
 ---
 title: Monolog
-description: "Learn how to enable Sentry's PHP SDK to capture Monolog events."
+description: "Learn how to enable Sentry's PHP SDK to capture Monolog events and logs."
 ---
 
-When using [Monolog](https://github.com/Seldaek/monolog) you can configure a [breadcrumb](../../enriching-events/breadcrumbs/) handler to capture Monolog messages as breadcrumbs and a handler that captures messages as events in Sentry.
+<Alert level="info" title="Sentry Logs">
+
+  Enable the Sentry Logs feature with `\Sentry\init(['enable_logs' => true])` to unlock Sentry's full logging power. With Sentry Logs, you can search, filter, and analyze logs from across your entire application in one place.
+
+</Alert>
+
+When using [Monolog](https://github.com/Seldaek/monolog) you can configure handlers to capture Monolog messages in several ways:
+
+- **Logs Handler** - Send structured logs to Sentry
+- **Event Handler** - Capture messages as error events in Sentry
+- **Breadcrumb Handler** - Record messages as breadcrumbs attached to future events
+
 The breadcrumb handler will not send anything to Sentry directly, it only records breadcrumbs that will be attached to any event or exception sent to Sentry.
 
+## Logs
+
+<Alert level="info">
+Available in SDK version 4.12.0 and above.
+</Alert>
+
+To send structured logs to Sentry, use the `\Sentry\Monolog\LogsHandler`.
+
+```php
+<?php
+
+use Monolog\Logger;
+use Sentry\Logs\LogLevel;
+
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'enable_logs' => true, // Enable Sentry logging
+]);
+
+// Create a Monolog channel with a logs handler
+$logger = new Logger('sentry_logs');
+$logger->pushHandler(new \Sentry\Monolog\LogsHandler(
+    LogLevel::info(), // Minimum level to send logs
+));
+
+// Send logs to Sentry
+$logger->info('User logged in', [
+    'user_id' => 12345,
+    'email' => '[email protected]',
+    'login_method' => 'password',
+]);
+
+$logger->warning('API rate limit approaching', [
+    'endpoint' => '/api/users',
+    'requests_remaining' => 10,
+    'window_seconds' => 60,
+]);
+```
+
+The context array passed to Monolog methods becomes searchable attributes in the Sentry logs interface.
+
+## Events & Breadcrumbs
+
 ```php
 <?php
 

docs/platforms/php/common/logs/index.mdx

@@ -19,6 +19,10 @@ With Sentry Structured Logs, you can send text-based log information from your a
 
 <PlatformContent includePath="logs/usage" />
 
+## Integrations
+
+<PlatformContent includePath="logs/integrations" />
+
 ## Options
 
 <PlatformContent includePath="logs/options" />

platform-includes/logs/integrations/php.mdx

@@ -0,0 +1,4 @@
+Available integrations:
+- [Monolog](/platforms/php/integrations/monolog/#logs)
+
+If there's an integration you would like to see, open a [new issue on GitHub](https://github.com/getsentry/sentry-php/issues/new/choose).

platform-includes/logs/setup/php.mdx

@@ -10,3 +10,31 @@ To enable logging, you need to initialize the SDK with the `enable_logs` option
 // Somewhere at the end of your execution, you should flush the logger to send pending logs to Sentry.
 \Sentry\logger()->flush();
 ```
+
+## Using with Monolog
+
+If you're already using [Monolog](https://github.com/Seldaek/monolog), you can use the `\Sentry\Monolog\LogsHandler` to send logs directly through your existing logging setup:
+
+```php
+use Monolog\Level;
+use Monolog\Logger;
+
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'enable_logs' => true,
+]);
+
+$log = new Logger('app');
+$log->pushHandler(new \Sentry\Monolog\LogsHandler(
+    hub: \Sentry\SentrySdk::getCurrentHub(),
+    level: Level::Info,
+));
+
+// Your existing Monolog usage will now send logs to Sentry
+$log->info('Application started');
+
+// Don't forget to flush
+\Sentry\logger()->flush();
+```
+
+For more details, see the [Monolog integration documentation](/platforms/php/integrations/monolog/#logs).