> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Userscript Metrics

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

To improve observability and debugging in the field, <InternalLink path="molt-replicator">MOLT Replicator</InternalLink> 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 <InternalLink path="replicator-metrics">Replicator Prometheus metrics</InternalLink> set and can be visualized immediately using the provided [`replicator.json` Grafana dashboard file](https://replicator.cockroachdb.com/replicator_grafana_dashboard.json). They are also included in <InternalLink path="replicator-metrics#metrics-snapshots">Replicator metrics snapshots</InternalLink>.

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

<a id="script-invocations-total" />

* `script_invocations_total` (counter)
  * Description: Number of times <InternalLink path="userscript-overview">userscript</InternalLink> handler functions (such as `onRowUpsert`, `onRowDelete`, and `onWrite`) are invoked.
  * Interpretation: Use to confirm that userscripts are actively being called, and detect misconfigurations where scripts filter out all data or never run.

<a id="script-rows-filtered-total" />

* `script_rows_filtered_total` (counter)
  * Description: Number of rows filtered out by the <InternalLink path="userscript-overview">userscript</InternalLink> (for example, handlers that returned `null` or produced no output).
  * Interpretation: Use to identify scripts that unintentionally drop incoming data, and confirm that logic for filtering out data rows is working as intended.

<a id="script-rows-processed-total" />

* `script_rows_processed_total` (counter)
  * Description: Number of rows successfully processed and passed through the <InternalLink path="userscript-overview">userscript</InternalLink>.
  * Interpretation: Use to measure how many rows are being transformed or routed successfully. Compare with [`script_rows_filtered_total`](#script-rows-filtered-total) to understand filtering ratios and validate script logic.

<a id="script-exec-time-seconds" />

* `script_exec_time_seconds` (histogram)
  * Description: Measures the execution time of each <InternalLink path="userscript-overview">userscript</InternalLink> function call.
  * Interpretation: Use to detect slow or inefficient userscripts that could introduce replication lag, and identify performance bottlenecks caused by complex transformations or external lookups.

<a id="script-entry-wait-seconds" />

* `script_entry_wait_seconds` (histogram)
  * Description: Measures the latency between a row entering the Replicator <InternalLink path="userscript-overview">userscript</InternalLink> queue and the start of its execution inside the JavaScript runtime.
  * Interpretation: Use to detect whether userscripts are queuing up before execution (higher values indicate longer wait times), and monitor how busy the userscript runtime pool is under load.

<a id="script-errors-total" />

* `script_errors_total` (counter)
  * Description: Number of errors that occurred during <InternalLink path="userscript-overview">userscript</InternalLink> execution (for example, JavaScript exceptions or runtime errors).
  * Interpretation: Use to surface failing scripts or invalid assumptions about incoming data, and 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. A wildcard value of "\*" means it is a shared or global metric applying to all tables.
* `function`: The handler function being observed.

## See also

* <InternalLink path="userscript-overview">Userscript Overview</InternalLink>
* <InternalLink path="userscript-quickstart">Userscript Quickstart</InternalLink>
* <InternalLink path="userscript-api">Userscript API</InternalLink>
* <InternalLink path="molt-replicator">MOLT Replicator</InternalLink>
* <InternalLink path="replicator-metrics">Replicator Metrics</InternalLink>