Capture Custom Metadata in Sync Logs for Improved Observability

You can now attach custom metadata to a PowerSync client connection and have it appear in Service/API logs. This gives you more control over how you track and debug sync behavior across your app - for example, tagging connections with app version, feature flags, or business context.

Why this matters

Until now, all sync log entries contained the same data across users and app states - including generic fields like the user_id and user-agent. This is usually enough for basic debugging, but if you needed to correlate issues with specific app versions or feature flags, you had to piece that together from other data sources. Custom metadata lets you stamp each connection with additional context you care about.

How it works

Pass an appMetadata object when calling PowerSyncDatabase.connect(). The metadata is attached to that connection and visible in the Service/API logs (enable the Metadata checkbox when viewing these in the PowerSync Dashboard). To update the metadata, reconnect with new values.

// JavaScript example:

db.connect(connector, {
  // This will be included in PowerSync service logs
  appMetadata: {
    app_version: MY_APP_VERSION
  }
});

See the docs for examples in other languages and more information.

Availability

Supported in the following SDKs:

• JavaScript/Web (v1.30.0), React Native (v1.28.0), Node.js (v0.15.0), Capacitor (v0.2.0)

• Dart/Flutter (v1.17.0+)

• Kotlin (v1.10.0+)

• Swift and .NET do not support custom metadata yet. This will be available in upcoming releases.

Requires PowerSync Service v1.17.0+. to see this metadata in the Service/API logs.

Help and Feedback

If you have questions, feedback run into edge cases, ping us on Discord - we’d love to hear how you’re using this.