Custom metadata in sync logs

usage/tools/monitoring-and-alerting.mdx

@@ -51,7 +51,7 @@
 Access usage metrics in the [PowerSync Dashboard](https://dashboard.powersync.com/). Select your project and instance and go to the **Metrics** view:
 
 <Frame>
-  <img src="/images/usage-metrics.png" />
+  <img src="/images/resources/view-usage-metrics.png" />
 </Frame>
 
 You have following options:
@@ -70,7 +70,7 @@
 
 You can review logs for your PowerSync instance(s) to troubleshoot replication or sync service issues. Logs capture activity from the PowerSync Service and Replicator processes.
 
-* **Service logs**: Reflect sync processes from the PowerSync Service to clients.
+* **Service/API logs**: Reflect sync processes from the PowerSync Service to clients.
 
 * **Replicator logs**: Reflect replication activity from your source database to the PowerSync Service.
 
@@ -100,12 +100,151 @@
 
 * **Sorting**: Sort logs by newest or oldest first.
 
-* **Service Logs Metadata**: Include metadata like `user_id` and `user_agent` in the logs if available.
+* **Metadata**: Display metadata like `user_id` and `user_agent` in the logs if available.
 
 * **View Mode**: Tail logs in real-time or view them statically.
 
 * **Stack Traces**: Option to show or hide stack traces for errors.
 
+## Custom Metadata in Sync Logs
+
+Custom metadata in sync logs allows clients to attach additional context to their PowerSync connection for improved observability and analytics. This metadata appears in the Service/API logs, making it easier to track, debug, and analyze sync behavior across your app. For example, you can tag connections with app version, feature flags, or business context.
+
+### How to Use Custom Metadata
+
+You can specify application metadata when calling `PowerSyncDatabase.connect()`. To update the metadata, reconnect with new metadata values.
+
+<Tabs>
+  <Tab title="JavaScript/React Native/Node.js/Capacitor">
+    <Note>
+      **Version compatibility**: This feature requires JavaScript/Web SDK v1.30.0+, React Native SDK v1.28.0+, Node.js SDK v0.15.0+, or Capacitor SDK v0.2.0+, and PowerSync Service v1.17.0+.
+    </Note>
+
+    ```javascript
+    import { PowerSyncDatabase } from '@powersync/web'; // Update this to the appropriate SDK package
+
+    const powerSync = new PowerSyncDatabase({
+      schema: AppSchema,
+      database: {
+        dbFilename: 'powersync.db'
+      }
+    });
+
+    // Set custom metadata when connecting
+    powerSync.connect(connector, {
+      appMetadata: {
+        app_version: '1.2.3',
+        feature_flag: 'new_sync_flow'
+      }
+    });
+    ```
+  </Tab>
+
+  <Tab title="Dart/Flutter">
+    <Note>
+      **Version compatibility**: This feature requires Dart/Flutter SDK v1.17.0+ and PowerSync Service v1.17.0+.
+    </Note>
+
+    ```dart
+    import 'package:powersync/powersync.dart';
+
+    final powerSync = PowerSyncDatabase(
+      schema: AppSchema,
+      path: 'powersync.db'
+    );
+    await powerSync.initialize();
+
+    // Set custom metadata when connecting
+    const options = SyncOptions(
+      appMetadata: {
+        'app_version': '1.2.3',
+        'feature_flag': 'new_sync_flow'
+      }
+    );
+    powerSync.connect(
+      connector: MyConnector(),
+      options: options
+    );
+    ```
+  </Tab>
+
+  <Tab title="Kotlin">
+    <Note>
+      **Version compatibility**: This feature requires Kotlin SDK v1.10.0+ and PowerSync Service v1.17.0+.
+    </Note>
+
+    ```kotlin
+    import com.powersync.DatabaseDriverFactory
+    import com.powersync.PowerSyncDatabase
+
+    // Android
+    val driverFactory = DatabaseDriverFactory(this)
+    // iOS & Desktop
+    // val driverFactory = DatabaseDriverFactory()
+
+    val powerSync = PowerSyncDatabase({
+      factory: driverFactory,
+      schema: AppSchema,
+      dbFilename: "powersync.db"
+    })
+
+    // Set custom metadata when connecting
+    powerSync.connect(
+      connector = MyConnector(),
+      appMetadata = mapOf(
+        "app_version" to "1.2.3",
+        "feature_flag" to "new_sync_flow"
+      )
+    )
+    ```
+  </Tab>
+
+  <Tab title="Swift">
+    Support for custom metadata is not yet available in Swift, but is planned for a future release.
+  </Tab>
+
+  <Tab title=".NET">
+    Support for custom metadata is not yet available in .NET, but is planned for a future release.
+
+    {/* ```csharp
+    using PowerSync.Common.Client;
+
+    var powerSync = new PowerSyncDatabase(new PowerSyncDatabaseOptions
+    {
+      Database = new SQLOpenOptions { DbFilename = "powersync.db" },
+      Schema = AppSchema.PowerSyncSchema,
+    });
+    await powerSync.Init();
+
+    // Set custom metadata when connecting
+    await powerSync.Connect(
+      connector: new MyConnector(),
+      appMetadata: new Dictionary<string, string>
+      {
+        { "app_version", "1.2.3" },
+        { "feature_flag", "new_sync_flow" }
+      }
+    );
+    ``` */}
+  </Tab>
+</Tabs>
+
+### View Custom Metadata in Logs
+
+Custom metadata appears in the **Service/API logs** section of the [PowerSync Dashboard](https://dashboard.powersync.com/). Navigate to your project and instance, then go to the **Logs** view. The metadata is included in **Sync Stream Started** and **Sync Stream Completed** log entries.
+
+<Note>
+  Make sure the **Metadata** checkbox is enabled in the logs view to see custom metadata in log entries.
+</Note>
+
+Note the following when using custom metadata:
+
+* Keep metadata values concise. `app_metadata` is limited to 20 keys, with each string value capped at 100 characters.
+
+* Avoid including sensitive information in metadata as it will appear in logs.
+
+* Metadata is set per connection. Reconnect with new metadata when user context or app state changes (e.g., feature flags).
+
 ## Issue Alerts
 
 Issue alerts capture potential problems with your instance, such as connection or replication issues.
@@ -223,7 +362,7 @@
 * **Event Triggers**: Select one or more of the following events to trigger the email notification:
   * **Usage alert state change**: Fired when a usage alert changes between 'monitoring' and 'alerting' (a threshold has been crossed)
   * **Issue alert state change**: Fired when an issue alert changes between 'monitoring' and 'alerting' (the instance has active issues)
   * **Deploy state change**: Fired when an instance deploy starts, completes or fails. This includes deprovisioning an instance
 
 * **Enabled**: Toggle to control whether the email rule is active
 
@@ -243,7 +382,7 @@
 * **Event Triggers**: Select one or more of the following events to trigger the webhook:
   * **Usage alert state change**: Fired when a usage alert changes between 'monitoring' and 'alerting' (a threshold has been crossed)
   * **Issue alert state change**: Fired when an issue alert changes between 'monitoring' and 'alerting' (the instance has active issues)
   * **Deploy state change**: Fired when an instance deploy starts, completes or fails. This includes deprovisioning an instance
 
 * **Enabled**: Toggle to control whether the webhook rule is active