Integrate with Your Code

To use the SF Veritas Desktop App, you need to instrument your applications with the Sailfish SDK. This enables your code to send telemetry data to the local collector, which is then displayed in the Console and Flamechart views.

Overview

The setup involves installing Sailfish packages in your application and adding a few lines of initialization code. The process differs slightly between backend and frontend applications.

Backend vs Frontend

Backend Applications

Backend instrumentation captures:

• Console logs (debug, info, warn, error)
• Exceptions and stack traces
• Function execution traces (for Flamechart)
• Print statements

Supported Languages:

• JavaScript/TypeScript (Node.js)
• Python (Django, FastAPI, Flask)
• Go (net/http, Gin, Echo, Fiber)
• Java (Spring Boot, Quarkus, Micronaut, Vert.x)

Set up Backend Application →

Frontend Applications

Frontend instrumentation captures:

• Browser console logs
• User interactions
• Network requests
• Frontend errors

Supported Frameworks:

• React
• Any JavaScript/TypeScript frontend

Set up Frontend Application →

Quick Start

Minimal Backend Setup (Node.js)

// At the entry point of your application (e.g., index.ts)

// Only load in development - zero overhead in production
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/sf-veritas').then(({ setupInterceptors }) => {
    setupInterceptors({
      apiKey: 'sf-veritas-local',
      apiGraphqlEndpoint: 'http://localhost:6776/graphql/',
      serviceIdentifier: 'my-backend-service',
      serviceVersion: '1.0.0',
    });
  });
}

// Your application code continues below...

Minimal Backend Setup (Python)

# At the entry point of your application (e.g., main.py)
import os

# Only load in development - zero overhead in production
if os.environ.get('DEBUG') == 'true':
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-veritas-local',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='my-python-service',
        service_version='1.0.0',
    )

# Your application code continues below...

Minimal Frontend Setup

// At the entry point of your frontend (e.g., index.tsx)

// Only load in development - zero overhead in production
if (process.env.NODE_ENV === 'development') {
  import('@sailfish-ai/recorder').then(({ initRecorder }) => {
    initRecorder({
      apiEndpoint: 'http://localhost:6776/graphql/',
      captureConsole: true,
      captureErrors: true,
      captureNetwork: true,
    });
  });
}

Vite Projects

For Vite-based projects, use import.meta.env.DEV instead of process.env.NODE_ENV === 'development'.

Configuration File

For more control, create a .sailfish configuration file in your project root:

{
  "capture": {
    "console": true,
    "exceptions": true,
    "functions": true
  },
  "sampling": {
    "rate": 1.0
  }
}

Architecture

How It Works

Environment variables control when SF Veritas is loaded:

Node.js:

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

Python:

Command	Environment	SF Veritas
DEBUG=true python manage.py runserver	development	✅ Active
DEBUG=true uvicorn main:app --reload	development	✅ Active
Production deploy	production	❌ Not loaded

Why conditional imports? Using environment checks with imports ensures:

• Zero overhead in production builds
• No network requests to localhost in production
• The package won't be loaded or bundled in production

Enterprise Setup

Enterprise Only

This section applies to users with a Sailfish Enterprise account. If you're using the Desktop App for local development only, you can skip this section.

Enterprise users run SF Veritas in two modes simultaneously:

1. Local development — Sends telemetry to the Desktop App's local collector (http://localhost:6776/graphql/). No API key required.
2. Staging / Production — Sends telemetry to the Sailfish cloud platform (https://api-service.sailfishqa.com/graphql/). Requires your company's API key.

Getting Your API Key

1. Open the SF Veritas Desktop App
2. Click Sign In during the setup wizard (or from the sidebar)
3. Sign in with your company account (Google SSO)
4. Your API key and company name will be displayed after sign-in
5. The setup wizard can auto-configure both modes via the AI-assisted install

Dual-Mode Configuration

The key idea: your application should detect which environment it's running in and use the appropriate configuration.

Local development:

• Endpoint: http://localhost:6776/graphql/
• API key: sf-veritas-local (or omitted)
• Activated by a dev-mode check (NODE_ENV, DEBUG=true, SF_DEV, etc.)

Staging / Production (Enterprise):

• Endpoint: default (do not override — the SDK uses the cloud endpoint automatically)
• API key: your company's Enterprise API key
• Always active (no environment check — you want telemetry in staging/production)

See the language-specific guides for detailed dual-mode examples:

• JavaScript/TypeScript
• Python
• Go
• Java

GIT_SHA Environment Variable

Enterprise deployments should set the GIT_SHA environment variable during the build process. This allows Sailfish to correlate telemetry with specific commits.

# Example: set during Docker build
docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .

# Example: set in CI/CD pipeline
export GIT_SHA=$(git rev-parse HEAD)

Most veritas libraries read GIT_SHA from the environment automatically. See each language guide for details.

URL Override

For local development, override the endpoint using either:

1. Environment variable: SAILFISH_GRAPHQL_ENDPOINT=http://localhost:6776/graphql/
2. Constructor argument: Pass the endpoint directly in your SDK initialization code

For staging and production, do not set SAILFISH_GRAPHQL_ENDPOINT — the SDK defaults to the cloud endpoint automatically.

Next Steps

1. Set up your backend application:
   • JavaScript/TypeScript (Node.js)
   • Python (Django, FastAPI, Flask)
   • Go (net/http, Gin, Echo, Fiber)
   • Java (Spring Boot, Quarkus, Micronaut)
2. Set up your frontend application (optional)
3. Learn how to use the Console and Flamechart