Backend Setup: JavaScript/TypeScript

This guide walks you through instrumenting a Node.js application (JavaScript or TypeScript) with the SF Veritas SDK.

Installation

Install the SF Veritas package:

npm install @sailfish-ai/sf-veritas

Or with yarn:

yarn add @sailfish-ai/sf-veritas

Basic Setup

Add the following to your application's entry point (e.g., index.ts, app.ts, or server.ts). The key is to wrap the initialization in a NODE_ENV check so it only runs during local development:

// Initialize SF Veritas ONLY in development mode
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/sf-veritas').then(({ setupInterceptors }) => {
    setupInterceptors({
      apiKey: 'sf-vscode-extension',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'my-backend-service',
      serviceVersion: '1.0.0',
    });
  });
}

// Your application code continues below...
import express from 'express';

const app = express();
// ... rest of your application

Configuration Options

Option	Type	Required	Description
apiKey	string	Yes	Use "sf-vscode-extension" for local development
apiGraphqlEndpoint	string	Yes	URL of the local collector (default port 6776)
serviceIdentifier	string	Yes	Unique name for your service
serviceVersion	string	No	Version of your service

Configuration File

For more control over what gets captured, create a .sailfish file in your project root:

{
  "capture": {
    "console": true,
    "exceptions": true,
    "functions": true,
    "network": true
  },
  "sampling": {
    "rate": 1.0,
    "maxEntriesPerSecond": 1000
  },
  "filters": {
    "excludePaths": [
      "node_modules",
      "dist"
    ],
    "excludeFunctions": [
      "internalHelper"
    ]
  }
}

Configuration Options

capture

Option	Default	Description
console	true	Capture console.log/info/warn/error
exceptions	true	Capture unhandled exceptions
functions	true	Capture function execution traces
network	true	Capture outgoing HTTP requests

sampling

Option	Default	Description
rate	1.0	Sampling rate (0.0 to 1.0, where 1.0 = 100%)
maxEntriesPerSecond	1000	Rate limit for telemetry entries

filters

Option	Default	Description
excludePaths	[]	File paths to exclude from tracing
excludeFunctions	[]	Function names to exclude from tracing

Framework Examples

Express.js

// server.ts
import express from 'express';

// Initialize SF Veritas only in development
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/sf-veritas').then(({ setupInterceptors }) => {
    setupInterceptors({
      apiKey: 'sf-vscode-extension',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'express-api',
      serviceVersion: '1.0.0',
    });
  });
}

const app = express();

app.get('/api/users', (req, res) => {
  console.log('Fetching users'); // This will appear in SF Veritas Console
  // ...
});

app.listen(3000, () => {
  console.log('Server started on port 3000');
});

NestJS

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  // Initialize SF Veritas only in development
  if (process.env.NODE_ENV === 'development') {
    const { setupInterceptors } = await import('@sailfish-ai/sf-veritas');
    setupInterceptors({
      apiKey: 'sf-vscode-extension',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'nestjs-api',
      serviceVersion: '1.0.0',
    });
  }

  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

Fastify

// app.ts
import Fastify from 'fastify';

// Initialize SF Veritas only in development
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/sf-veritas').then(({ setupInterceptors }) => {
    setupInterceptors({
      apiKey: 'sf-vscode-extension',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'fastify-api',
      serviceVersion: '1.0.0',
    });
  });
}

const fastify = Fastify({ logger: true });

fastify.get('/', async (request, reply) => {
  console.log('Handling request');
  return { hello: 'world' };
});

fastify.listen({ port: 3000 });

Verifying the Setup

1. Start your application
2. In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Run SF Veritas: Show Console Logs
4. Trigger some activity in your application
5. You should see logs appearing in the Console panel

Troubleshooting

No logs appearing

1. Check the local server: Run SF Veritas: Start Local Server if not running
2. Verify the endpoint: Ensure apiGraphqlEndpoint matches your server port
3. Check console output: Look for SF Veritas initialization messages in your terminal

Connection refused errors

1. Verify the SF Veritas extension is installed and active
2. Check that the local server is running (look for server status in VS Code status bar)
3. Ensure port 6776 is not blocked by a firewall

High memory usage

1. Reduce the sampling rate in .sailfish config
2. Add paths to excludePaths to reduce trace volume
3. Lower maxEntriesPerSecond to rate limit telemetry

Multi-Service Setup

When running multiple services locally, give each a unique serviceIdentifier:

// user-service/server.ts
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/sf-veritas').then(({ setupInterceptors }) => {
    setupInterceptors({
      apiKey: 'sf-vscode-extension',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'user-service',
      serviceVersion: '1.0.0',
    });
  });
}

// order-service/server.ts
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/sf-veritas').then(({ setupInterceptors }) => {
    setupInterceptors({
      apiKey: 'sf-vscode-extension',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'order-service',
      serviceVersion: '1.0.0',
    });
  });
}

Use the service filter in the Console to switch between services.

How It Works

The NODE_ENV environment variable controls when SF Veritas is active:

Command	NODE_ENV	SF Veritas
npm run dev	development	✅ Active
npm run start (production)	production	❌ Not loaded
npm run build	production	❌ Not included

Most Node.js frameworks automatically set NODE_ENV=development when you run npm run dev:

• Express: Set via cross-env or your dev script
• NestJS: Set automatically by nest start --watch
• Fastify: Set via cross-env or your dev script

If your framework doesn't set it automatically, add it to your package.json:

{
  "scripts": {
    "dev": "NODE_ENV=development ts-node src/server.ts",
    "start": "NODE_ENV=production node dist/server.js"
  }
}

Next Steps

• Set up your frontend application (optional)
• Learn how to use the Console
• Learn how to use the Flamechart