SDK Integration
Java SDK Setup Guide
Configure and attach the standard Java Instrumentation agent to your running JVM applications with zero code changes.
The InSitu Java Agent is a zero-touch JVM Instrumentation agent. By attaching the JAR at startup via the standard
-javaagent
flag, it intercepts and transforms application bytecode on-the-fly—requiring
zero code changes, zero annotation wrappers, and zero compilation modifications
.
Technical Prerequisites
Runtime:
Java 17 or later (compatible with Oracle HotSpot, OpenJDK, Corretto, Temurin).
Metadata:
Active git commit SHA (mandatory for resolving bytecode offsets to local lines).
Agent Jar:
The
InSitu-agent.jar
artifact. You can view and download all releases from
Maven Central (Sonatype)
.
Downloading the Agent
Before attaching the agent, download the
InSitu-agent.jar
file. You can fetch it directly using
curl
or
wget
(be sure to replace
<LATEST_VERSION>
with the current version from
Maven Central
):
curl
curl
-L
-o
InSitu-agent.jar
"https://repo1.maven.org/maven2/co/InSitu/InSitu-agent/<LATEST_VERSION>/InSitu-agent-<LATEST_VERSION>.jar"
wget
wget
-O
InSitu-agent.jar
"https://repo1.maven.org/maven2/co/InSitu/InSitu-agent/<LATEST_VERSION>/InSitu-agent-<LATEST_VERSION>.jar"
Installation & Deployment
Attach the agent at startup using the standard
-javaagent
flag. Set the required environment variables before starting your application.
# 1. Export deployment metadata
export
GIT_COMMIT
=
$(
git
rev-parse
HEAD
)
export
InSitu_SERVICE_ID
=
"<service-uuid-from-dashboard>"
export
InSitu_ENVIRONMENT
=
production
# Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
export
InSitu_BROKER_URL
=
https
://
logger
.
app
.
InSitu
.
co
# 2. Attach JVM Agent at runtime
java
-javaagent:/opt/InSitu/InSitu-agent.jar
-jar
your-application.jar
Use environment variables for service, broker, and capture configuration. JVM system properties do not replace these settings. Custom trace ID hooks also support the system properties listed in the
configuration reference
.
Deployment Templates
Docker Multi-Stage Build
Kubernetes Manifest
It is best practice to download the agent jar during build-time and bake the Git commit into the final image:
Dockerfile
FROM
eclipse-temurin:21-jre
# Define build arguments
ARG
GIT_COMMIT
ENV
GIT_COMMIT=${GIT_COMMIT}
# Setup agent directories
RUN
mkdir -p /opt/InSitu
COPY
InSitu-agent.jar /opt/InSitu/InSitu-agent.jar
COPY
build/libs/app.jar /app/app.jar
# Inject static environment configuration
ENV
InSitu_SERVICE_ID=
"<service-uuid-from-dashboard>"
ENV
InSitu_ENVIRONMENT=production
ENV
InSitu_BROKER_URL=https://logger.app.useinsitu.com
ENTRYPOINT
[
"java"
,
"-javaagent:/opt/InSitu/InSitu-agent.jar"
,
"-jar"
,
"/app/app.jar"
]
Build the image in your pipeline by passing the active commit:
docker
build
--build-arg
GIT_COMMIT=
$(
git
rev-parse
HEAD
)
-t
app:latest
.
Expose your environment parameters inside your deployment’s spec definition:
deployment.yaml
spec
:
containers
:
-
name
:
billing-service
image
:
billing-service:latest
env
:
-
name
:
GIT_COMMIT
valueFrom
:
configMapKeyRef
:
name
:
build-metadata
key
:
commit-sha
-
name
:
InSitu_SERVICE_ID
value
:
"<service-uuid-from-dashboard>"
-
name
:
InSitu_ENVIRONMENT
value
:
"production"
-
name
:
InSitu_BROKER_URL
value
:
"https://logger.app.useinsitu.com"
command
: [
"java"
,
"-javaagent:/opt/InSitu/InSitu-agent.jar"
,
"-jar"
,
"/app/app.jar"
]
🛠️ Build-Tool & Framework Setup
Attach the JVM agent inside your development environment to test probes locally before deploying.
Gradle (Kotlin DSL)
Gradle (Groovy DSL)
Maven (pom.xml)
Add the agent args to your standard Spring Boot run tasks inside
build.gradle.kts
:
build.gradle.kts
tasks.
withType
<
org
.
springframework
.
boot
.
gradle
.
tasks
.
run
.
BootRun
> {
// 1. Add JVM Agent argument
jvmArgs
(
"-javaagent:
${
rootDir
}
/libs/InSitu-agent.jar"
)
// 2. Inject environment parameters
environment
(
"InSitu_SERVICE_ID"
,
"<service-uuid-from-dashboard>"
)
environment
(
"InSitu_ENVIRONMENT"
,
"local"
)
environment
(
"InSitu_BROKER_URL"
,
"https://logger.app.useinsitu.com"
)
environment
(
"GIT_COMMIT"
, project.
findProperty
(
"gitCommit"
) ?:
"unknown"
)
}
build.gradle
bootRun {
jvmArgs
=
[
"-javaagent:
${
rootDir
}
/libs/InSitu-agent.jar"
]
environment
"InSitu_SERVICE_ID"
,
"<service-uuid-from-dashboard>"
environment
"InSitu_ENVIRONMENT"
,
"local"
environment
"InSitu_BROKER_URL"
,
"https://logger.app.useinsitu.com"
environment
"GIT_COMMIT"
, project
.
findProperty(
"gitCommit"
)
?:
"unknown"
}
pom.xml
<
plugin
>
<
groupId
>
org.springframework.boot
</
groupId
>
<
artifactId
>
spring-boot-maven-plugin
</
artifactId
>
<
configuration
>
<
jvmArguments
>
-javaagent:${project.basedir}/libs/InSitu-agent.jar
</
jvmArguments
>
<
environmentVariables
>
<
InSitu_SERVICE_ID
>
YOUR_SERVICE_UUID
</
InSitu_SERVICE_ID
>
<
InSitu_ENVIRONMENT
>
local
</
InSitu_ENVIRONMENT
>
<
InSitu_BROKER_URL
>
https://logger.app.useinsitu.com
</
InSitu_BROKER_URL
>
<
GIT_COMMIT
>
${git.commit.id}
</
GIT_COMMIT
>
</
environmentVariables
>
</
configuration
>
</
plugin
>
Configuration and environment variables
The following example lists all supported runtime environment variables. Required values are examples; optional numeric and redaction settings show their defaults.
# --- CORE OPTIONS (required strings) ---
export
GIT_COMMIT
=
$(
git
rev-parse
HEAD
)
# Commit used to build the deployed application
export
InSitu_SERVICE_ID
=
"<service-uuid-from-dashboard>"
export
InSitu_ENVIRONMENT
=
production
# Your environment name; no default
export
InSitu_BROKER_URL
=
https
://
logger
.
app
.
InSitu
.
co
# --- BUFFERING & PERFORMANCE (integers) ---
export
InSitu_FLUSH_INTERVAL_MS
=
1000
# Telemetry export interval in milliseconds
export
InSitu_SYNC_INTERVAL_MS
=
60000
# Probe sync interval in milliseconds
# --- SAFETY GUARDRAILS (integers) ---
export
InSitu_HITS_PER_SEC
=
20
# Agent-wide probe execution limit per second
export
InSitu_BANDWIDTH_KB_PER_SEC
=
1024
# Telemetry bandwidth limit in KiB per second
export
InSitu_COOLDOWN_SEC
=
10
# Delay before attempting recovery after suspension
# --- SOURCE LOCATIONS (string) ---
export
InSitu_APP_ROOT
=
""
# Prefix to strip from probe source paths
# --- DATA & REDACTION CONTROLS ---
export
InSitu_REDACT_KEYS
=
"password,secret,token,authorization,cookie,key,signature"
export
InSitu_REDACT_VALUES
=
""
# Comma-separated regex patterns; none by default
export
InSitu_MAX_OBJECT_DEPTH
=
3
# Maximum object traversal depth
export
InSitu_MAX_ARRAY_LENGTH
=
3
# Maximum captured array or iterable elements
export
InSitu_MAX_OBJECT_PROPERTIES
=
50
# Maximum captured fields or map entries
export
InSitu_MAX_STRING_LENGTH
=
1024
# String truncation limit
export
InSitu_STACK_FRAME_DEPTH
=
3
# Maximum stack frames per snapshot
# --- OPTIONAL STARTUP & DEBUGGING (unset by default) ---
# export InSitu_DISABLED=YES                 # Disable the agent at startup
# export DEBUG="InSitu*"                    # Enable agent debug logging
# --- OPTIONAL TRACE ID HOOK (strings) ---
# export InSitu_TRACE_ID_CLASS="com.example.TraceIdHook"
# export InSitu_TRACE_ID_METHOD="getTraceId" # Default method name
Core settings
GIT_COMMIT
,
InSitu_SERVICE_ID
,
InSitu_ENVIRONMENT
, and
InSitu_BROKER_URL
must be nonblank. The agent does not start if
GIT_COMMIT
is
unknown
. Java does not read
InSitu_COMMIT_SHA
.
InSitu_BROKER_URL
accepts an HTTP(S) URL or a raw gRPC target such as
localhost:50051
. Do not include a trailing slash or query string. HTTPS enables TLS; HTTP and raw targets use plaintext gRPC.
InSitu_DISABLED
disables startup only when set to
YES
(case-insensitive).
true
and
1
do not disable the agent.
Capture and redaction
Use positive integers for numeric limits. Missing or invalid integer values fall back to defaults.
InSitu_REDACT_KEYS
and
InSitu_REDACT_VALUES
accept comma-separated, case-insensitive regular expressions. Key patterns match field names and redact their values; value patterns redact matching portions of strings. A nonempty key list replaces the default list, so include the defaults when adding custom patterns. An empty value does not clear the default key rules.
These capture and redaction settings provide startup defaults. Broker configuration can update them, and individual snapshot probes can override numeric capture limits.
Java does not expose environment variables for queue size, RPC timeout, event-loop lag, or pause budgets. Options such as
InSitu_MAX_QUEUE_SIZE
and
InSitu_MAX_LAG_MS
from other SDKs do not apply.
Logging and trace ID hooks
DEBUG
accepts comma- or space-separated namespaces, such as
InSitu*
. It enables debug output without changing normal info, warning, or error logging.
For custom trace IDs, set
InSitu_TRACE_ID_CLASS
to a class with a public static, zero-argument method.
InSitu_TRACE_ID_METHOD
defaults to
getTraceId
. Without a custom class, the agent looks for
com.InSitu.hook.TraceIdHook.getTraceId()
.
You can also use
-DInSitu.traceid.class=...
and
-DInSitu.traceid.method=...
; these JVM properties take precedence over the corresponding environment variables.
Memory Safety Shields
Because bytecode injection could theoretically impact Heap health on heavy memory spikes, the Java Agent includes an active
Memory Guardrail
:
Yellow Threshold (Free Memory < 15%):
Logs a warning and paces serialization buffers.
Red Threshold (Free Memory < 5%):
Instantly uninstalls and suspends all in-memory probes to shield your JVM from Out-Of-Memory (OOM) failures.
Auto-Recovery:
Resumes instrumentation automatically once GC recovers memory health and active cooldown cycles end.
Node.js SDK Setup Guide
Previous
Kotlin SDK Setup Guide
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
Downloading the Agent
Installation & Deployment
Deployment Templates
🛠️ Build-Tool & Framework Setup
Configuration and environment variables
Core settings
Capture and redaction
Logging and trace ID hooks
Memory Safety Shields