Inspector

Zero includes a rich inspector API that can help you understand performance or behavior issues you are seeing in your apps.

Accessing the Inspector

You access the inspector right from the standard developer console in your browser:

Why hello there, inspector!

For convenience, Zero automatically injects itself as __zero on the global scope of every Zero app.

Clients and Groups

Once you have an inspector, you can inspect the current client and client group. For example to see active queries for the current client:

Copylet qs = await inspector.client.queries()
console.table(qs)

To see active queries for the entire group:

Copylet qs = await inspector.client.queries()
console.table(qs)

Queries

The inspector exposes a bunch of useful information about queries. For example, to see the first query for the current client:

Copylet qs = await inspector.client.queries()
console.log(qs[0])

This outputs something like:

Information about a query

Here are some of the more useful fields:

Analyzing Queries

Use the analyze method to get information about how a query hydrates:

Copyawait qs[0].analyze()

Analyzing a query

Here are some of the most useful fields in the output:

Interpreting Query Analysis

A Zero query is composed of one or more single-table queries connected by joins (related, whereExists).

Zero delegates the single-table queries to SQLite, which has a sophisticated query planner that chooses the best indexes to use. SQLite will scan tables or indexes to find rows to satisfy the single-table query.

Zero then implements its own incremental joins and limits on top of these single-table outputs. It reads rows out of the single-table outputs to satisfy the joins and limits.

Generally, you want the number of rows scanned by SQLite and read into JavaScript by Zero to be small multiples of the number of rows synced to the client. Most Zero query performance problems come from either too many active queries (visible from inspector.client.queries()), or queries that scan or read too many rows (visible by looking at the SQLite or Zero respectively).

Viewing SQLite Plans

To view the plans selected by SQLite, see the sqlitePlans field returned by analyze() or analyzeQuery(). This contains the output of SQLite's EXPLAIN QUERY PLAN command for each SQLite query used:

SQLite EXPLAIN QUERY PLAN output

If SQLite is scanning too many rows, it probably means that SQLite lacks a good index to use. Add the index to Postgres – Zero copies indexes from Postgres to the SQLite replica.

Another common problem visible in SQLite plans is TEMP B-TREE entries: SQLite had to build a temporary index to satisfy the ORDER BY clause. This is not always a performance problem, but if you see it you can try adding an index with the correct columns (note that Zero adds all primary key columns to the ORDER BY clause, so the index must include all primary key columns).

Viewing Zero Plans

To view the join plan selected by Zero, call analyze() or analyzeQuery() with the joinPlans option set to true and see the joinPlans field in the output:

Zero join planner output

This output is mostly useful to the Zero team for debugging query performance problems.

Analyzing Arbitrary ZQL

You can also analyze arbitrary ZQL, not just queries that are currently active:

Copyawait __zero.inspector.analyzeQuery(
  __builder.issues.whereExists('labels', q =>
    q.id.equals('sync')
  )
)

This is useful for exploring alternative query constructions to optimize performance.

To use this, you will first have to expose your builder as a property of the global object, so that you can access it from the console. For example:

Copy// schema.ts
// ...
const g = globalThis as any
g.__builder = builder

Table Data

In addition to information about queries, you can get direct access to the contents of the client side database.

Copyconst client = __zero.inspector.client
 
// All raw k/v data currently synced to client
console.log('client map:')
console.log(await client.map())
 
// kv table extracted into tables
// This is same info that is in z.query[tableName].run()
for (const tableName of Object.keys(__zero.schema.tables)) {
  console.log(`table ${tableName}:`)
  console.table(await client.rows(tableName))
}

Server Version

Ask the server to confirm what version it is:

Copyconsole.log(
  'server version: ',
  await inspector.serverVersion()
)