SDK Integration
Ruby SDK Setup Guide
Install, initialize, and optimize the InSitu Ruby and JRuby SDK inside in-process Ruby applications.
The InSitu Ruby SDK runs as an in-process agent for standard Ruby (CRuby) and JRuby. It captures variable snapshots, stack frames, metrics, and logs without adding logging statements to your application. Capture overhead depends on your probes and workload.
Technical Prerequisites
Standard Ruby (CRuby):
Ruby 3.0 and later.
JRuby (Ruby on JVM):
JRuby 9.3 and later on Java 11 or later (Java 17, 21, and 25 supported). Requires the JIT-preserving tracing profile in
JRUBY_OPTS
.
Metadata:
Access to the active git commit SHA (mandatory for matching local source coordinates to production builds).
Installation
Add the SDK as a dependency using your package manager:
Gemfile
bundle add
gem
gem
'InSitu-agent'
bundle
add
InSitu-agent
gem
install
InSitu-agent
If you added
gem 'InSitu-agent'
directly to your
Gemfile
, run:
bundle
install
Initialization Walkthrough
Follow these steps to initialize the InSitu agent inside your application:
1
Create your initialization file
Create a dedicated file named
InSitu.rb
in your project root:
InSitu.rb
require
'InSitu'
InSitu
.
start
(
service_id:
'<service-uuid-from-dashboard>'
,
environment:
ENV
[
'InSitu_ENVIRONMENT'
]
||
ENV
[
'RAILS_ENV'
]
||
ENV
[
'RACK_ENV'
]
||
'production'
,
broker_url:
'https://logger.app.useinsitu.com'
,
commit_sha:
ENV
[
'GIT_COMMIT'
]
||
ENV
[
'InSitu_COMMIT_SHA'
]
)
2
Import it in your entrypoint
In your main application entrypoint (such as
config/environment.rb
for Rails, or
app.rb
/
server.rb
for Sinatra / Rack), require
InSitu
as early as possible
before starting your application:
Rails (config/environment.rb)
Sinatra          Web Server (app.rb)
require_relative
'../InSitu'
# Require as early as possible
require_relative
'application'
Rails
.
application
.
initialize!
require_relative
'InSitu'
# Require as early as possible
require
'sinatra'
get
'/'
do
'Hello World'
end
Environment Variables Loading Order:
If
InSitu.rb
reads variables loaded by a library such as
dotenv
, load those variables before requiring
InSitu.rb
.
3
Configure multi-worker servers (Puma / Unicorn)
If you run a multi-process web server like Puma or Unicorn in clustered mode (with forked workers) on standard Ruby (CRuby), add
defer_start: true
to your initializer and call
InSitu.after_fork
in your worker boot configuration:
config/puma.rb
on_worker_boot
do
InSitu
.
after_fork
end
JRuby on JVM:
On JRuby, Puma runs in multi-threaded mode on the JVM without process forking, so
InSitu.after_fork
and
defer_start
are not required.
4
Configure your Dockerfile
To enable Docker-based deployments, define a
GIT_COMMIT
build argument inside your
Dockerfile
with a default value of
unknown
.
If you are running JRuby, also set the
JRUBY_OPTS
environment variable to preserve variable scopes with JIT enabled:
Standard Ruby (CRuby)
JRuby (Ruby on JVM)
Dockerfile
# Define build argument with 'unknown' fallback to protect non-CI builds
ARG
GIT_COMMIT=unknown
ENV
GIT_COMMIT=${GIT_COMMIT}
Dockerfile
# Set required JRuby flags to preserve line boundaries and variables with JIT enabled
ENV
JRUBY_OPTS=
"--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass"
# Define build argument with 'unknown' fallback to protect non-CI builds
ARG
GIT_COMMIT=unknown
ENV
GIT_COMMIT=${GIT_COMMIT}
5
Run local Docker builds
For building and testing Docker containers locally, inject your active git commit:
docker
build
--build-arg
GIT_COMMIT=
$(
git
rev-parse
HEAD
)
-t
api:latest
.
6
Inject correct SHA in CI/CD (The PR Merge Trap)
To protect source alignment, InSitu refuses to start if
commit_sha
resolves to
unknown
. Pass the real commit SHA to
GIT_COMMIT
during deployment.
Always use your CI/CD platform’s native commit SHA variable:
Platform / Engine
Configuration Option
Build Argument Syntax
GitHub Actions
PR-Safe HEAD Check (Recommended)
--build-arg GIT_COMMIT=${{ github.event.pull_request.head.sha || github.sha }}
GitHub Actions (Push)
Standard Branch Push
--build-arg GIT_COMMIT=${{ github.sha }}
GitLab CI/CD
GitLab Variable
--build-arg GIT_COMMIT=$CI_COMMIT_SHA
CircleCI
CircleCI Variable
--build-arg GIT_COMMIT=$CIRCLE_SHA1
Beware of the PR Merge Commit Trap:
By default, GitHub Actions checks out a virtual merge commit for a
pull_request
trigger instead of the commit from your branch.
If you use
git rev-parse HEAD
or
${{ github.sha }}
in a pull request workflow, source mapping can fail. Use
${{ github.event.pull_request.head.sha || github.sha }}
for pull request builds.
☕ JRuby Support (Ruby on the JVM)
InSitu provides native, first-class support for JRuby applications running on the JVM.
Prerequisites for JRuby
JRuby Version:
JRuby
9.3 and later
(Java 8 is not supported; JRuby 10.1 requires Java 21+).
Java Runtime:
Java 11, 17, 21, or 25.
Launch Profile:
JRuby must be launched with the required JIT-preserving tracing profile:
--debug
-J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass
-J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass
Why the Launch Profile is Required on JRuby
JRuby’s JIT compiler optimizes hot methods into raw JVM bytecode, stripping out line-level checkpoints and local variable names by default. Passing this profile instructs JRuby to retain line checkpoints and local variable scopes without disabling JIT compilation, so probes trigger reliably on compiled methods.
How to Launch JRuby with InSitu
Docker / Kubernetes
CLI / Local Server
Add the environment variable inside your
Dockerfile
or Deployment manifest:
Dockerfile
ENV
JRUBY_OPTS=
"--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass"
Set the
JRUBY_OPTS
variable before starting your application:
export
JRUBY_OPTS
=
"--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass"
bundle
exec
jruby
app.rb
# Or with Puma:
bundle
exec
puma
-C
config/puma.rb
(Note: If running JRuby 9.3 on Java 17, also include
-J--add-opens=java.base/sun.nio.ch=ALL-UNNAMED -J--add-opens=java.base/java.io=ALL-UNNAMED
for JRuby’s native I/O access).
Zero C-Extensions & Zero Runtime Downloads:
On JRuby, Bundler automatically installs the Java gem artifact (
InSitu-agent-<version>-java.gem
). It bundles an internal, shaded Netty gRPC transport and patched protobuf codec. No C compiler, Maven, or runtime downloads are required on the client machine.
Configuration & Environment Variables Reference
You can configure the agent by passing properties inside your
InSitu.start()
options hash, or by using
environment variables
.
The following example includes the available programmatic options and their corresponding environment variables:
InSitu.rb
require
'InSitu'
InSitu
.
start
(
# --- CORE OPTIONS ---
service_id:
'<service-uuid-from-dashboard>'
,
# Env: InSitu_SERVICE_ID
environment:
ENV
[
'InSitu_ENVIRONMENT'
],
# Env: InSitu_ENVIRONMENT (e.g. 'production', 'staging')
broker_url:
'https://logger.app.useinsitu.com'
,
# Env: InSitu_BROKER_URL
commit_sha:
ENV
[
'GIT_COMMIT'
],
# Env: GIT_COMMIT or InSitu_COMMIT_SHA (Mandatory)
# --- BUFFERING & PERFORMANCE ---
max_queue_size:
100
,
# Env: InSitu_MAX_QUEUE_SIZE      - Cap on telemetry stored in memory
flush_interval_ms:
1000
,
# Env: InSitu_FLUSH_INTERVAL_MS   - Milliseconds before draining the queue
sync_interval_ms:
60000
,
# Env: InSitu_SYNC_INTERVAL_MS    - Sync cycle to fetch new active probes
# --- SAFETY GUARDRAILS ---
hits_per_sec:
10
,
# Env: InSitu_HITS_PER_SEC         - Global limit on triggers per second
bandwidth_kb_per_sec:
1024
,
# Env: InSitu_BANDWIDTH_KB_PER_SEC - Throughput cap in Kilobytes/sec
max_lag_ms:
50
,
# Env: InSitu_MAX_LAG_MS          - Thread-lag threshold in ms (CRuby only)
pause_budget_ms:
15
,
# Env: InSitu_PAUSE_BUDGET_MS     - Probe-handler time budget in ms/sec (CRuby only)
cooldown_sec:
10
,
# Env: InSitu_COOLDOWN_SEC        - Duration (in seconds) the agent remains dormant in cooldown
rpc_timeout_sec:
10
,
# Env: InSitu_RPC_TIMEOUT_SEC     - gRPC request timeout in seconds
# --- DATA & REDACTION CONTROLS ---
redact_keys:
[
# Env: InSitu_REDACT_KEYS (comma-separated list)
'password'
,
'secret'
,
'token'
,
'authorization'
,
'cookie'
,
'key'
,
'signature'
],
# Blacklisted keys are stripped and replaced with [REDACTED] in-process
redact_values:
[],
# Env: InSitu_REDACT_VALUES (comma-separated list of regex patterns)
max_object_depth:
3
,
# Env: InSitu_MAX_OBJECT_DEPTH     - Max nested properties serialized
max_array_length:
3
,
# Env: InSitu_MAX_ARRAY_LENGTH     - Max elements serialized per array
max_object_properties:
50
,
# Env: InSitu_MAX_OBJECT_PROPERTIES - Max key-value parameters recorded per object
max_string_length:
1024
,
# Env: InSitu_MAX_STRING_LENGTH    - Max character count before string truncation
stack_frame_depth:
3
# Env: InSitu_STACK_FRAME_DEPTH    - Number of call stack frames captured per snapshot
)
Option Precedence:
Explicit options passed to
InSitu.start()
take precedence over environment variables.
Disabling the Agent:
Set
InSitu_DISABLED=YES
in your environment to completely disable the agent at startup.
Option Naming:
Both
snake_case
(e.g.,
service_id
,
commit_sha
) and
camelCase
(e.g.,
serviceId
,
commitSha
) parameter keys are accepted.
On CRuby, snapshots include locals from the hit frame and available caller frames, including blocks, up to
stack_frame_depth
. On JRuby, only the hit frame has locals; caller frames show
{}
.
Safe evaluation
Safe evaluation is enabled by default on Ruby and JRuby. To allow custom method calls in probe expressions, opt in before starting your application:
export
InSitu_DISABLE_SAFE_EVALUATION
=
true
Alternatively, add
disable_safe_evaluation: true
to your existing
InSitu.start
options. An explicit
false
keeps safe evaluation enabled, even if the environment variable is
true
.
Disabling safe evaluation lets conditions, watches, log placeholders, metrics, and duration correlations execute Ruby code with your application’s permissions. This code can change state, block, or terminate the process. Only enable it for trusted probes. The SDK logs a warning once at startup when enabled.
Safety shields
The SDK automatically suspends probes when its safety limits are exceeded:
CRuby:
Uses repeated thread-lag readings and a probe-handler time budget (default 15 ms per second).
JRuby:
Checks JVM heap headroom every 5 seconds. Below 15% of maximum heap triggers a warning; below 5% suspends probes. Timing-budget breaches do not log warnings or suspend probes.
Auto-recovery:
Resumes probes after the cooldown period (default 10 seconds), once health returns to GREEN.
Python SDK Setup Guide
Previous
Integration using AI agent
Next
⌘
I
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Terms of Service
On this page
Back to top
Technical Prerequisites
Installation
Initialization Walkthrough
☕ JRuby Support (Ruby on the JVM)
Prerequisites for JRuby
Why the Launch Profile is Required on JRuby
How to Launch JRuby with InSitu
Configuration & Environment Variables Reference
Safe evaluation
Safety shields