VS Code extension — Nistor Docs

The VS Code extension shows what Nistor knows about the BigQuery tables named in your SQL. Hover a table in a .sql file to see:

its open and acknowledged incidents: how many, and the severity and title of one of them (snoozed incidents are left out);
when the latest of those incidents started;
how many nodes are downstream and upstream of it;
a link that opens the table in Nistor.

A table that Nistor does not know shows "Not tracked by Nistor". The Nistor view in the activity bar lists the tables of the current file in three groups: with open incidents, not tracked, and healthy.

The extension only reads. It asks the backend for the incidents of the tables in your open files (POST /api/v1/incidents/by-nodes) and for each table's node (GET /api/v1/dependencies/nodes/{id}), and keeps each answer for five minutes.

Before you start#

VS Code 1.85 or later, and Node.js with npm to build the extension.
A Nistor backend that issues extension tokens (see Sign in).
The Google Cloud integration, which creates the BigQuery table nodes the extension looks up. Their ids have the form BigqueryTable_<project>.<dataset>.<table>.

Build and install#

The extension is not published to a marketplace. Build it from the repository:

cd vscode-extension
npm ci
npm run build
npm run package

npm run build bundles the extension into dist/extension.js, and npm run package writes a .vsix file. In VS Code, run Extensions: Install from VSIX… from the command palette and pick that file.

Settings#

Setting	Default	Meaning
`nistor.backendUrl`	empty	The base URL of your Nistor instance, for example `https://nistor.example.com`. The extension adds `/api/v1` to it for the API.
`nistor.frontendUrl`	empty, meaning `nistor.backendUrl`	The origin that serves the web shell, where you sign in. Set it only when the web shell and the API have different origins.
`nistor.tableProjectPrefixes`	`[]`	The project id prefixes of the tables to recognise, for example `["acme-"]`. Nothing is recognised until you set at least one.

"Open in Nistor" opens <nistor.backendUrl>/nodes/<node id>, so set nistor.backendUrl to an origin that serves both the web shell and the API when you have one. Changing it clears the cache.

What it recognises#

In a file whose language is SQL, the extension recognises a table name that follows FROM, JOIN, INTO, UPDATE or TABLE (in any case), written as project.dataset.table or project:dataset.table, whose project starts with one of your prefixes. It does not recognise a name in backticks, nor a name split across lines.

Set nistor.backendUrl.
Run Nistor: Sign in from the command palette, or click Nistor: sign in in the status bar.
Your browser opens the web shell's /extension-token-redeem page. If you are signed in to the web shell, the page sends you back to VS Code with a one-time code.
The extension trades the code for a token at POST /api/v1/auth/extension-tokens/exchange, and keeps the token in VS Code's secret storage.

The token carries your identity, so the extension sees what you may see. It lasts EXTENSION_TOKEN_TTL_DAYS days (7 by default). The status bar shows how many days are left, or that the token has expired. When the backend answers 401, the extension forgets the token: sign in again. Nistor: Sign out removes it.

Commands#

Command	Does
Nistor: Sign in	Starts the sign-in above.
Nistor: Sign out	Removes the stored token.
Nistor: Open node in Nistor	Opens a node in your browser. The hover card's link runs it.
Nistor: Clear cache	Forgets the cached answers.

Privacy#

The extension sends requests only to nistor.backendUrl, and opens nistor.frontendUrl in your browser to sign in. Every request carries the header User-Agent: nistor-vscode/<version> (vscode/<version>).