You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Metadata draft
* Fixes to the examples
* Placeholders for version compatiblity
* Add service version
* import statement note
* Apply suggestions from code review
* JS SDK versions
* Add kotlin version
* Add dart version
* placeholder for .net
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.
72
72
73
-
***Service logs**: Reflect sync processes from the PowerSync Service to clients.
73
+
***Service/API logs**: Reflect sync processes from the PowerSync Service to clients.
74
74
75
75
***Replicator logs**: Reflect replication activity from your source database to the PowerSync Service.
76
76
@@ -100,12 +100,151 @@ You can manage logs with the following options:
100
100
101
101
***Sorting**: Sort logs by newest or oldest first.
102
102
103
-
***Service Logs Metadata**: Include metadata like `user_id` and `user_agent` in the logs if available.
103
+
***Metadata**: Display metadata like `user_id` and `user_agent` in the logs if available.
104
104
105
105
***View Mode**: Tail logs in real-time or view them statically.
106
106
107
107
***Stack Traces**: Option to show or hide stack traces for errors.
108
108
109
+
## Custom Metadata in Sync Logs
110
+
111
+
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.
112
+
113
+
### How to Use Custom Metadata
114
+
115
+
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+.
121
+
</Note>
122
+
123
+
```javascript
124
+
import { PowerSyncDatabase } from'@powersync/web'; // Update this to the appropriate SDK package
125
+
126
+
constpowerSync=newPowerSyncDatabase({
127
+
schema: AppSchema,
128
+
database: {
129
+
dbFilename:'powersync.db'
130
+
}
131
+
});
132
+
133
+
// Set custom metadata when connecting
134
+
powerSync.connect(connector, {
135
+
appMetadata: {
136
+
app_version:'1.2.3',
137
+
feature_flag:'new_sync_flow'
138
+
}
139
+
});
140
+
```
141
+
</Tab>
142
+
143
+
<Tabtitle="Dart/Flutter">
144
+
<Note>
145
+
**Version compatibility**: This feature requires Dart/Flutter SDK v1.17.0+ and PowerSync Service v1.17.0+.
146
+
</Note>
147
+
148
+
```dart
149
+
import 'package:powersync/powersync.dart';
150
+
151
+
final powerSync = PowerSyncDatabase(
152
+
schema: AppSchema,
153
+
path: 'powersync.db'
154
+
);
155
+
await powerSync.initialize();
156
+
157
+
// Set custom metadata when connecting
158
+
const options = SyncOptions(
159
+
appMetadata: {
160
+
'app_version': '1.2.3',
161
+
'feature_flag': 'new_sync_flow'
162
+
}
163
+
);
164
+
powerSync.connect(
165
+
connector: MyConnector(),
166
+
options: options
167
+
);
168
+
```
169
+
</Tab>
170
+
171
+
<Tabtitle="Kotlin">
172
+
<Note>
173
+
**Version compatibility**: This feature requires Kotlin SDK v1.10.0+ and PowerSync Service v1.17.0+.
174
+
</Note>
175
+
176
+
```kotlin
177
+
importcom.powersync.DatabaseDriverFactory
178
+
importcom.powersync.PowerSyncDatabase
179
+
180
+
// Android
181
+
val driverFactory =DatabaseDriverFactory(this)
182
+
// iOS & Desktop
183
+
// val driverFactory = DatabaseDriverFactory()
184
+
185
+
val powerSync =PowerSyncDatabase({
186
+
factory: driverFactory,
187
+
schema:AppSchema,
188
+
dbFilename:"powersync.db"
189
+
})
190
+
191
+
// Set custom metadata when connecting
192
+
powerSync.connect(
193
+
connector =MyConnector(),
194
+
appMetadata =mapOf(
195
+
"app_version" to "1.2.3",
196
+
"feature_flag" to "new_sync_flow"
197
+
)
198
+
)
199
+
```
200
+
</Tab>
201
+
202
+
<Tabtitle="Swift">
203
+
Support for custom metadata is not yet available in Swift, but is planned for a future release.
204
+
</Tab>
205
+
206
+
<Tabtitle=".NET">
207
+
Support for custom metadata is not yet available in .NET, but is planned for a future release.
208
+
209
+
{/* ```csharp
210
+
using PowerSync.Common.Client;
211
+
212
+
var powerSync = new PowerSyncDatabase(new PowerSyncDatabaseOptions
213
+
{
214
+
Database = new SQLOpenOptions { DbFilename = "powersync.db" },
215
+
Schema = AppSchema.PowerSyncSchema,
216
+
});
217
+
await powerSync.Init();
218
+
219
+
// Set custom metadata when connecting
220
+
await powerSync.Connect(
221
+
connector: new MyConnector(),
222
+
appMetadata: new Dictionary<string, string>
223
+
{
224
+
{ "app_version", "1.2.3" },
225
+
{ "feature_flag", "new_sync_flow" }
226
+
}
227
+
);
228
+
``` */}
229
+
</Tab>
230
+
</Tabs>
231
+
232
+
### View Custom Metadata in Logs
233
+
234
+
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.
235
+
236
+
<Note>
237
+
Make sure the **Metadata** checkbox is enabled in the logs view to see custom metadata in log entries.
238
+
</Note>
239
+
240
+
Note the following when using custom metadata:
241
+
242
+
* Keep metadata values concise. `app_metadata` is limited to 20 keys, with each string value capped at 100 characters.
243
+
244
+
* Avoid including sensitive information in metadata as it will appear in logs.
245
+
246
+
* Metadata is set per connection. Reconnect with new metadata when user context or app state changes (e.g., feature flags).
247
+
109
248
## Issue Alerts
110
249
111
250
Issue alerts capture potential problems with your instance, such as connection or replication issues.
0 commit comments