Backend Setup: Ruby

Enterprise Configuration

This guide covers Ruby instrumentation for Sailfish Enterprise. Key differences from local development:

• API key: Use your Enterprise API key (shown as "<ApiKey />" below -- auto-replaced when you're logged in)
• GraphQL endpoint: Do not set it -- the SDK defaults to the Sailfish cloud endpoint automatically
• Service identifier: Use the <org>/<repo>/<path-to-this-file> format (e.g., acme-corp/web-api/config/initializers/sf_veritas.rb)
• No environment gating: Enterprise telemetry runs in all environments (staging, production)

If you connected GitHub and received Auto-Installation PRs, the API key, service identifier, and graphql endpoint are already configured for you.

This guide walks you through instrumenting a Ruby application with the SF Veritas SDK. Ruby instrumentation captures logs, print statements, exceptions, HTTP request/response telemetry, and function execution spans.

Getting Your API Key

1. Open the Sailfish dashboard
2. Log in with your enterprise email
3. Navigate to Settings > Configuration
4. Copy your company's API key

Installation

Add the Gem Source

First, add the Sailfish gem repository:

gem sources -a https://ruby-gemrepo.sailfishqa.com/

Bundler (Recommended)

Add sf-veritas to your Gemfile:

# Gemfile
gem 'sf-veritas'

Then install:

bundle install

Direct Install

gem install sf-veritas

Basic Setup

Add the following to your application's entry point:

require 'sf_veritas'

SfVeritas.setup_interceptors(
  api_key: '<see-api-key-from-your-account-settings-page>',
  service_identifier: 'acme-corp/ruby-api/config/initializers/sf_veritas.rb', # Format: <org>/<repo>/<path-to-this-file>
  service_version: '1.0.0'
)

# Your application code continues below...

Configuration Options

Option	Type	Required	Description
api_key	String	Yes	Your Sailfish Enterprise API key
service_identifier	String	Yes	Unique identifier in <org>/<repo>/<path> format
service_version	String	No	Version of your service
service_display_name	String	No	Display name in the UI
git_sha	String	No	Git commit SHA (auto-detected)
git_org	String	No	Git organization (auto-detected)
git_repo	String	No	Git repository name (auto-detected)
git_provider	String	No	Git provider (auto-detected)
sf_debug	Boolean	No	Enable debug logging to stderr
domains_to_not_propagate_headers_to	Array	No	Domains to skip header propagation
routes_to_skip_network_hops	Array	No	Routes to skip inbound tracing

What Gets Captured Automatically

Once setup_interceptors is called, these are captured with zero additional code:

• Structured logs -- All Ruby Logger output
• Print statements -- All $stdout / puts output
• Exceptions -- Unhandled exceptions with full stack traces
• Outbound HTTP requests -- Via Net::HTTP (automatic monkey-patch)
• Inbound HTTP requests -- Via Rack middleware (auto-installed in Rails, manual in Sinatra)

Framework Examples

Ruby on Rails

Rails integration is automatic via a Railtie. When the sf-veritas gem is loaded, the Rack middleware is auto-installed -- no extra configuration needed.

Add to config/initializers/sf_veritas.rb:

# config/initializers/sf_veritas.rb
require 'sf_veritas'

SfVeritas.setup_interceptors(
  api_key: '<see-api-key-from-your-account-settings-page>',
  service_identifier: 'acme-corp/rails-api/config/initializers/sf_veritas.rb', # Format: <org>/<repo>/<path-to-this-file>
  service_version: '1.0.0'
)

note

The Rack middleware for inbound request tracking is automatically inserted via a Rails Railtie. You don't need to add config.middleware.use manually.

Sinatra

For Sinatra, require the gem and add the middleware manually:

# app.rb
require 'sinatra'
require 'sf_veritas'

SfVeritas.setup_interceptors(
  api_key: '<see-api-key-from-your-account-settings-page>',
  service_identifier: 'acme-corp/sinatra-api/app.rb', # Format: <org>/<repo>/<path-to-this-file>
  service_version: '1.0.0'
)

use SfVeritas::Middleware

get '/api/users' do
  puts 'Fetching users'  # This will appear in Sailfish
  { users: [] }.to_json
end

Generic Rack

For any Rack-compatible application:

# config.ru
require 'sf_veritas'

SfVeritas.setup_interceptors(
  api_key: '<see-api-key-from-your-account-settings-page>',
  service_identifier: 'acme-corp/rack-app/config.ru' # Format: <org>/<repo>/<path-to-this-file>
)

use SfVeritas::Middleware

run MyApp

Function Tracing

Manual Spans

Use SfVeritas.start_span for manual control over which functions appear in the Flamechart:

def process_order(order_id)
  span = SfVeritas.start_span('OrderService#process_order',
    arguments: { order_id: order_id }.to_json
  )
  begin
    result = do_work(order_id)
    span.finish(result)
    result
  rescue => e
    span.finish(nil, error: e)
    raise
  end
end

Block Tracing

Use SfVeritas.trace for a cleaner block-based syntax:

def process_order(order_id)
  SfVeritas.trace('OrderService#process_order',
    arguments: { order_id: order_id }.to_json
  ) do
    do_work(order_id)
  end
end

Automatic Function Capture (TracePoint)

For full automatic function tracing, set the SF_FUNCSPAN_AUTO_CAPTURE environment variable:

SF_FUNCSPAN_AUTO_CAPTURE=true rails server

Auto-capture only instruments your application code -- it automatically skips gems, stdlib, and SF Veritas internals.

User Identification

SfVeritas.identify('user-123', { email: 'user@example.com', name: 'Jane Doe', plan: 'enterprise' })

Exception Reporting

Exceptions are captured automatically, but you can also report them manually:

begin
  risky_operation
rescue => e
  SfVeritas::ExceptionHandler.report(e)
  # Handle or re-raise
end

GIT_SHA

The SDK auto-detects GIT_SHA from common CI/CD platforms:

CI Platform	Environment Variable
GitHub Actions	GITHUB_SHA
GitLab CI	CI_COMMIT_SHA
CircleCI	CIRCLE_SHA1
Jenkins	GIT_COMMIT
Bitbucket Pipelines	BITBUCKET_COMMIT
Travis CI	TRAVIS_COMMIT
Azure DevOps	BUILD_SOURCEVERSION
AWS CodeBuild	CODEBUILD_RESOLVED_SOURCE_VERSION
Vercel	VERCEL_GIT_COMMIT_SHA

For custom CI systems, set it manually:

docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .

Environment Variables

Variable	Default	Description
SF_DEBUG	false	Enable debug logging to stderr
SF_LOG_IGNORE_REGEX	--	Regex to suppress matching log messages
SF_FUNCSPAN_AUTO_CAPTURE	false	Enable automatic function span capture via TracePoint
SF_FUNCSPAN_CAPTURE_ARGUMENTS	false	Capture function arguments
SF_FUNCSPAN_CAPTURE_RETURN_VALUE	false	Capture return values
SF_FUNCSPAN_ARG_LIMIT_MB	1	Max argument capture size in MB
SF_FUNCSPAN_RETURN_LIMIT_MB	1	Max return value capture size in MB
SF_FUNCSPAN_ENABLE_SAMPLING	false	Enable span sampling
SF_FUNCSPAN_SAMPLE_RATE	1.0	Function span sampling rate (0.0 to 1.0)
SF_FUNCSPAN_AUTOCAPTURE_ALL_CHILD_FUNCTIONS	true	Auto-capture all child function calls
SF_NETWORKHOP_CAPTURE_REQUEST_HEADERS	false	Capture HTTP request headers
SF_NETWORKHOP_CAPTURE_REQUEST_BODY	false	Capture HTTP request bodies
SF_NETWORKHOP_CAPTURE_RESPONSE_HEADERS	false	Capture HTTP response headers
SF_NETWORKHOP_CAPTURE_RESPONSE_BODY	false	Capture HTTP response bodies
SF_DISABLE_PRINT_CAPTURE	false	Disable stdout capture

Configuration File

Create a .sailfish file in your project root for per-file and per-function span configuration. Supports JSON, TOML, and YAML formats.

{
  "funcspan": {
    "default": {
      "capture_arguments": true,
      "capture_return_value": true,
      "sample_rate": 1.0
    },
    "files": {
      "app/models/*.rb": {
        "capture_arguments": false
      }
    },
    "functions": {
      "User#save": {
        "capture_arguments": true,
        "capture_return_value": true,
        "arg_limit_mb": 2
      },
      "HealthCheck#ping": {
        "sample_rate": 0.0
      }
    }
  }
}

Verifying the Setup

1. Deploy your application with the Sailfish SDK configured
2. Trigger some HTTP requests
3. Open the Sailfish dashboard -- you should see telemetry appearing

Troubleshooting

No logs appearing

1. Check the API key: Ensure api_key is set to your Enterprise API key
2. Check the service identifier: Ensure service_identifier uses the <org>/<repo>/<path> format
3. Check terminal output: Look for [sf-veritas] initialization messages

Connection errors

1. Ensure your deployment can reach https://api-service.sailfish.ai
2. Check that outbound HTTPS (port 443) is not blocked by a firewall or network policy

Gem not found

1. Ensure the Sailfish gem source is added: gem sources -l should include https://ruby-gemrepo.sailfishqa.com/
2. Re-add if missing: gem sources -a https://ruby-gemrepo.sailfishqa.com/
3. Run bundle install again if using Bundler
4. Verify Ruby 2.6+ is installed: ruby --version

Multi-Service Setup

When running multiple Ruby services, give each a unique service_identifier:

# user-service/config/initializers/sf_veritas.rb
require 'sf_veritas'
SfVeritas.setup_interceptors(
  api_key: '<see-api-key-from-your-account-settings-page>',
  service_identifier: 'acme-corp/user-service/config/initializers/sf_veritas.rb', # Format: <org>/<repo>/<path-to-this-file>
  service_version: '1.0.0'
)

# order-service/config/initializers/sf_veritas.rb
require 'sf_veritas'
SfVeritas.setup_interceptors(
  api_key: '<ApiKey />',
  service_identifier: 'acme-corp/order-service/config/initializers/sf_veritas.rb', # Format: <org>/<repo>/<path-to-this-file>
  service_version: '1.0.0'
)

Next Steps

• Set up your frontend application (optional)
• Check the Sailfish dashboard to verify telemetry is flowing

---

Local Development

Looking to set up SF Veritas for local development with the Desktop App? See the Desktop App Ruby guide.