feat(dart/flutter): improve distinction between Logging integration and Structured Logs (#14527)

The logging integration refers to the integration with the Dart Logging
package and it's pretty easy to confuse it with Structured Logs
especially because if you google for Sentry Dart/Flutter logs the
logging integration is the first page that shows up

I tried to make it a bit more clearer but I'm unsure if my approach is
good

---------

Co-authored-by: Alex Krawiec <[email protected]>

Author: buenaflor

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

@@ -21,6 +21,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" />

includes/dart-integrations/logging.mdx

@@ -1,6 +1,6 @@
 ---
 title: Logging Integration
-description: "Learn more about the Sentry Logging integration for the Dart SDK."
+description: "Integrate Sentry with the Dart Logging package to capture events, breadcrumbs, and automatically send structured logs to Sentry."
 caseStyle: canonical
 supportLevel: production
 sidebar_order: 3
@@ -9,9 +9,19 @@ platforms:
   - flutter
 ---
 
-The `sentry_logging` library provides [Logging](https://pub.dev/packages/logging) support for Sentry using the [onRecord property](https://pub.dev/documentation/logging/latest/logging/Logger/onRecord.html). It is able to collect breadcrumbs and capture events. Once this integration is configured, you can use Logging's public API exclusively or in combination to the Sentry's SDK API to capture and enrich events.
+This integration connects Sentry with the popular [Dart logging package](https://pub.dev/packages/logging), providing the following capabilities:
 
-The source can be found [on GitHub](https://github.com/getsentry/sentry-dart/tree/main/logging/).
+- If `enableLogs` is set to `true`, Sentry will send your log messages as [Sentry Structured Logs](/platforms/dart/logs/) (new in `9.5.0`)
+- Captures breadcrumbs from your log calls
+- Converts error-level logs into Sentry error events
+- Works with your existing logging code
+
+<Alert level="info">
+
+This page covers the instrumentation of the **Dart Logging package**.
+This integration also supports creating structured logs. However, if you're looking to set up Sentry structured logs in general, visit our [Structured Logs](/platforms/dart/logs/) documentation. 
+
+</Alert>
 
 ## Install
 
@@ -26,8 +36,7 @@ dependencies:
 
 ## Configure
 
-Configuration should happen as early as possible in your application's lifecycle.
-
+Add the `LoggingIntegration` to your `Sentry.init` call:
 
 ```dart
 import 'package:sentry_logging/sentry_logging.dart';
@@ -38,36 +47,64 @@ Future<void> main() async {
     (options) {
       options.dsn = '___PUBLIC_DSN___';
       options.addIntegration(LoggingIntegration());
+      // If you want to enable sending structured logs, set `enableLogs` to `true`
+      options.enableLogs = true;
     },
     appRunner: initApp, // Init your App.
   );
 }
 ```
 
+### Configuration Options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `minBreadcrumbLevel` | `Level.INFO` | Minimum level for creating breadcrumbs |
+| `minEventLevel` | `Level.SEVERE` | Minimum level for creating error events |
+| `minSentryLogLevel` | `Level.INFO` | Minimum level for sending structured logs (requires `enableLogs` to be `true`) |
+
+You can customize which log levels trigger different Sentry features:
+
+```dart
+await Sentry.init(
+  (options) {
+    options.dsn = '___PUBLIC_DSN___';
+    options.addIntegration(LoggingIntegration(
+      minBreadcrumbLevel: Level.INFO,    // Breadcrumbs for INFO and above
+      minEventLevel: Level.SEVERE,       // Error events for SEVERE and above  
+      minSentryLogLevel: Level.INFO,     // Structured logs for INFO and above
+    ));
+  },
+  appRunner: initApp,
+);
+```
+
 ## Verify
 
-This snippet captures an intentional error, so you can test that everything is working as soon as you set it up:
+Add the following snippet to your app and execute it to verify that Sentry is capturing your logs:
 
 ```dart
 import 'package:logging/logging.dart';
 
-void main() async {
+void testLogging() {
   final log = Logger('MyAwesomeLogger');
 
-  log.info('a breadcrumb!');
+  // This creates a breadcrumb AND a structured log (Level.INFO >= defaults)
+  log.info('User logged in successfully');
+  
+  // This creates a breadcrumb AND a structured log (Level.WARNING >= defaults)  
+  log.warning('Rate limit approaching');
 
   try {
-    throw StateError();
+    throw StateError('Something went wrong');
   } catch (error, stackTrace) {
-    log.severe('an error!', error, stackTrace);
+    // This creates a breadcrumb, structured log, AND error event (Level.SEVERE >= all defaults)
+    log.severe('Critical error occurred', error, stackTrace);
   }
 }
 ```
 
-<Alert>
-
-Learn more about manually capturing an error or message, in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
-
-</Alert>
-
-To view and resolve the recorded message, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.
+### What You'll See in Sentry:
+- **Breadcrumbs**: All three log calls will appear as breadcrumbs on the error event
+- **Error Event**: The `severe` log creates a full error event with stack trace
+- **Structured Logs**: (if `enableLogs` is `true`) Navigate to **Logs** in your Sentry project to see all three entries as searchable structured logs

platform-includes/logs/integrations/dart.mdx

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

platform-includes/logs/usage/dart.mdx

@@ -2,14 +2,33 @@ Once the feature is enabled on the SDK and the SDK is initialized, you can send
 
 The `logger` namespace exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warning`, `error`, and `fatal`.
 
-You can pass additional attributes directly to the logging functions. These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
+Aside from the primary logging methods, we've provided a format text function, `Sentry.logger.fmt`, that you can use to insert properties into to your log entries.
+
+These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
+
+<Alert level="info">
+  When using the `fmt` function, you must use the `%s` placeholder for each value you want to insert.
+</Alert>
 
 ```dart
-Sentry.logger.info("A simple log message");
-Sentry.logger.warn("This is a warning log with attributes.", attributes: {
-  'attribute1': SentryLogAttribute.string('string'),
-  'attribute2': SentryLogAttribute.int(1),
-  'attribute3': SentryLogAttribute.double(1.0),
-  'attribute4': SentryLogAttribute.bool(true),
+Sentry.logger.fmt.error('Uh oh, something broke, here is the error: %s', [
+  errorMsg
+], attributes: {
+  'additional_info': SentryLogAttribute.string('some info'),
 });
+Sentry.logger.fmt.info("%s added %s to cart.", [user.username, product.name]);
 ```
+
+You can also pass additional attributes directly to the logging functions, avoiding the need to use the `fmt` function.
+
+```dart
+Sentry.logger.error('Uh oh, something broke, here is the error: $errorMsg',
+    attributes: {
+      'error': SentryLogAttribute.string(errorMsg),
+      'some_info': SentryLogAttribute.string('some info'),
+    });
+Sentry.logger.info('User ${user.username} added ${product.name} to cart.', attributes: {
+  'user': SentryLogAttribute.string(user.username),
+  'product': SentryLogAttribute.string(product.name),
+});
+```