Backend Setup: Python

This guide walks you through instrumenting a Python application with the SF Veritas SDK

Installation

Install the SF Veritas package:

pip install sf-veritas

Or with poetry:

poetry add sf-veritas

Basic Setup

Add the following to your application's entry point. The key is to wrap the initialization in a development check so it only runs during local development:

import os

# Initialize SF Veritas ONLY in development mode
if os.environ.get('DEBUG') == 'true':
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-vscode-extension',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='my-python-service',
        service_version='1.0.0',
    )

# Your application code continues below...

Configuration Options

Option	Type	Required	Description
api_key	str	Yes	Use "sf-vscode-extension" for local development
graphql_endpoint	str	Yes	URL of the local collector (default port 6776)
service_identifier	str	Yes	Unique name for your service
service_version	str	No	Version of your service

Framework Examples

Django

# settings.py (at the bottom of the file)
# Or in wsgi.py / manage.py before Django setup

if DEBUG:
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-vscode-extension',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='django-api',
        service_version='1.0.0',
    )

Alternatively, in manage.py:

#!/usr/bin/env python
import os
import sys

def main():
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

    # Initialize SF Veritas only in development
    if os.environ.get('DEBUG') == 'true':
        from sf_veritas import setup_interceptors
        setup_interceptors(
            api_key='sf-vscode-extension',
            graphql_endpoint='http://localhost:6776/graphql/',
            service_identifier='django-api',
            service_version='1.0.0',
        )

    from django.core.management import execute_from_command_line
    execute_from_command_line(sys.argv)

if __name__ == '__main__':
    main()

FastAPI

# main.py
import os

# Initialize SF Veritas only in development
if os.environ.get('DEBUG') == 'true':
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-vscode-extension',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='fastapi-api',
        service_version='1.0.0',
    )

from fastapi import FastAPI

app = FastAPI()

@app.get('/api/users')
async def get_users():
    print('Fetching users')  # This will appear in SF Veritas Console
    return {'users': []}

# Run with: DEBUG=true uvicorn main:app --reload

Flask

# app.py
import os

# Initialize SF Veritas only in development
if os.environ.get('FLASK_ENV') == 'development':
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-vscode-extension',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='flask-api',
        service_version='1.0.0',
    )

from flask import Flask

app = Flask(__name__)

@app.route('/api/users')
def get_users():
    print('Fetching users')  # This will appear in SF Veritas Console
    return {'users': []}

# Run with: FLASK_ENV=development flask run

Function Tracing

Use decorators to control which functions appear in the Flamechart:

from sf_veritas import capture_function_spans, skip_function_tracing

@capture_function_spans()
def important_business_logic():
    """This function will be traced in the Flamechart."""
    process_data()
    return result

@skip_function_tracing
def internal_helper():
    """This function won't be traced."""
    pass

Decorator Options

@capture_function_spans(
    include_arguments=True,      # Capture function arguments
    include_return_value=True,   # Capture return values
    sample_rate=1.0,             # Sampling rate (0.0 to 1.0)
)
def traced_function():
    pass

Verifying the Setup

1. Start your application with the development flag:
   • Django: DEBUG=true python manage.py runserver
   • FastAPI: DEBUG=true uvicorn main:app --reload
   • Flask: FLASK_ENV=development flask run
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 graphql_endpoint 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

Import errors

1. Ensure sf-veritas is installed: pip show sf-veritas
2. Check you're using Python 3.8+
3. Verify you're in the correct virtual environment

Multi-Service Setup

When running multiple Python services locally, give each a unique service_identifier:

# user-service/main.py
if os.environ.get('DEBUG') == 'true':
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-vscode-extension',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='user-service',
        service_version='1.0.0',
    )

# order-service/main.py
if os.environ.get('DEBUG') == 'true':
    from sf_veritas import setup_interceptors
    setup_interceptors(
        api_key='sf-vscode-extension',
        graphql_endpoint='http://localhost:6776/graphql/',
        service_identifier='order-service',
        service_version='1.0.0',
    )

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

How It Works

The environment variable controls when SF Veritas is active:

Framework	Dev Check	Dev Command	SF Veritas
Django	DEBUG=true or settings.DEBUG	DEBUG=true python manage.py runserver	✅ Active
FastAPI	DEBUG=true	DEBUG=true uvicorn main:app --reload	✅ Active
Flask	FLASK_ENV=development	FLASK_ENV=development flask run	✅ Active
Any	Any	Production deploy	❌ Not loaded

Most Python frameworks have their own way to detect development mode:

• Django: Uses DEBUG setting in settings.py
• FastAPI: Typically uses environment variable
• Flask: Uses FLASK_ENV environment variable

Next Steps

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