Userscript Metrics

To improve observability and debugging in the field, MOLT Replicator exposes Prometheus metrics that provide insight into userscript activity, performance, and stability. These metrics help identify issues such as slow script execution, overly aggressive filtering, handlers not being called when expected, and unhandled errors in user-defined logic.

All userscript metrics include a script_ prefix and are automatically labeled with the relevant schema or table for each configured handler (for example, schema="target.public"). If a userscript defines both schema-level and table-level handlers, separate label values will be created for each.

These metrics are part of the default Replicator Prometheus metrics set and can be visualized immediately using the provided replicator.json Grafana dashboard file.

Consider using these metrics to:

• Correlate script performance and errors with replication throughput.
• Identify high-latency or error-prone scripts impacting replication health.
• Debug unexpected filtering or transformation logic in field environments.

Metrics

• script_invocations_total (counter)

  • Counts how many times userscript handler functions (such as onRowUpsert, onRowDelete, and onWrite) are invoked.
  • Use it to:
    • Confirm that userscripts are actively being called.
    • Detect misconfigurations where scripts filter out all data or never run.

• script_rows_filtered_total (counter)

  • Counts how many rows were filtered out by the userscript (for example, handlers that returned null or produced no output).
  • Use it to:
    • Identify scripts that unintentionally drop incoming data.
    • Confirm that logic for filtering out data rows is working as intended.

• script_rows_processed_total (counter)

  • Counts how many rows were successfully processed and passed through the userscript.
  • Use it to:
    • Measure how many rows are being transformed or routed successfully.
    • Compare with script_rows_filtered_total to understand filtering ratios and validate script logic.

• script_exec_time_seconds (histogram)

  • Measures the execution time of each userscript function call.
  • Use it to:
    • Detect slow or inefficient userscripts that could introduce replication lag.
    • Identify performance bottlenecks caused by complex transformations or external lookups.

• script_entry_wait_seconds (histogram)

  • Measures the latency between a row entering the Replicator userscript queue and the start of its execution inside the JavaScript runtime.
  • Use it to:
    • Detect whether userscripts are queuing up before execution (higher values indicate longer wait times).
    • Monitor how busy the userscript runtime pool is under load.

• script_errors_total (counter)

  • Counts the total number of errors that occurred during userscript execution (for example, JavaScript exceptions or runtime errors).
  • Use it to:
    • Surface failing scripts or invalid assumptions about incoming data.
    • Monitor script stability over time and catch regressions early.

Example Metric Labels

Each metric may include the following standard labels:

• schema: The schema name associated with the userscript handler.
• table: The table name associated with the userscript handler.
• function: The handler function being observed.

See also

• MOLT Replicator
• Userscript Guide
• Userscript API
• Replicator Metrics