diff --git a/images/resources/instance-alerts-dashboard.png b/images/resources/instance-alerts-dashboard.png
deleted file mode 100644
index 587ead8b..00000000
Binary files a/images/resources/instance-alerts-dashboard.png and /dev/null differ
diff --git a/images/resources/test-webhook-cmd.png b/images/resources/test-webhook-cmd.png
deleted file mode 100644
index fe101fa1..00000000
Binary files a/images/resources/test-webhook-cmd.png and /dev/null differ
diff --git a/images/resources/view-instance-logs.png b/images/resources/view-instance-logs.png
index 73781306..bf56b075 100644
Binary files a/images/resources/view-instance-logs.png and b/images/resources/view-instance-logs.png differ
diff --git a/images/resources/view-issue-alert-logs-cmd.png b/images/resources/view-issue-alert-logs-cmd.png
deleted file mode 100644
index 1ed84f49..00000000
Binary files a/images/resources/view-issue-alert-logs-cmd.png and /dev/null differ
diff --git a/images/resources/view-usage-alert-logs-cmd.png b/images/resources/view-usage-alert-logs-cmd.png
deleted file mode 100644
index 940ead80..00000000
Binary files a/images/resources/view-usage-alert-logs-cmd.png and /dev/null differ
diff --git a/images/resources/view-usage-metrics.png b/images/resources/view-usage-metrics.png
new file mode 100644
index 00000000..eab6dc9a
Binary files /dev/null and b/images/resources/view-usage-metrics.png differ
diff --git a/usage/tools/monitoring-and-alerting.mdx b/usage/tools/monitoring-and-alerting.mdx
index 9e76643c..e4558e2a 100644
--- a/usage/tools/monitoring-and-alerting.mdx
+++ b/usage/tools/monitoring-and-alerting.mdx
@@ -51,7 +51,7 @@ View time-series and aggregated usage data for your PowerSync instance(s), inclu
Access usage metrics in the [PowerSync Dashboard](https://dashboard.powersync.com/). Select your project and instance and go to the **Metrics** view:
- 
+ 
You have following options:
@@ -70,7 +70,7 @@ You have following options:
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 @@ You can manage logs with the following options:
* **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.
+
+
+
+
+ **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+.
+
+
+ ```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'
+ }
+ });
+ ```
+
+
+
+
+ **Version compatibility**: This feature requires Dart/Flutter SDK v1.17.0+ and PowerSync Service v1.17.0+.
+
+
+ ```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
+ );
+ ```
+
+
+
+
+ **Version compatibility**: This feature requires Kotlin SDK v1.10.0+ and PowerSync Service v1.17.0+.
+
+
+ ```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"
+ )
+ )
+ ```
+
+
+
+ Support for custom metadata is not yet available in Swift, but is planned for a future release.
+
+
+
+ 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
+ {
+ { "app_version", "1.2.3" },
+ { "feature_flag", "new_sync_flow" }
+ }
+ );
+ ``` */}
+
+
+
+### 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.
+
+
+ Make sure the **Metadata** checkbox is enabled in the logs view to see custom metadata in log entries.
+
+
+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.