SDK Integration
Python SDK Setup Guide
Install, initialize, and optimize the InSitu Python SDK inside in-process Python applications.
The InSitu Python SDK runs as an in-process agent. It captures variables, stack frames, metrics, and logs without stopping your application in a debugger. Capture runs on the application thread, so overhead depends on your probes and workload.
Technical Prerequisites
Runtime:
CPython 3.7 and later. Python 3.12 and later uses
sys.monitoring
; Python 3.7–3.11 uses bytecode instrumentation.
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:
pip
poetry
pipenv
uv
pip
install
InSitu-agent
poetry
add
InSitu-agent
pipenv
install
InSitu-agent
uv
add
InSitu-agent
Initialization Walkthrough
Follow these steps to initialize the InSitu agent inside your application:
1
Create your initialization file
Create a dedicated file named
InSitu_init.py
in your project source root:
InSitu_init.py
import
os
from
InSitu
import
InSitu
InSitu.start({
"service_id"
:
"<service-uuid-from-dashboard>"
,
"environment"
: os.getenv(
"InSitu_ENVIRONMENT"
)
or
os.getenv(
"PYTHON_ENV"
),
"broker_url"
:
"https://logger.app.useinsitu.com"
,
"commit_sha"
: os.getenv(
"InSitu_COMMIT_SHA"
)
or
os.getenv(
"GIT_COMMIT"
),
})
2
Import it in your entrypoint
In your main application file, import
InSitu_init
as early as possible
before starting your application:
main.py
import
InSitu_init
from
app
import
create_app
app
=
create_app()
Environment Variables Loading Order:
If
InSitu_init.py
reads variables loaded by a library such as
python-dotenv
, load those variables before importing
InSitu_init
.
3
Configure preloaded workers (Gunicorn)
If your server loads the application before forking workers, such as Gunicorn with
--preload
, set this variable before starting the server:
export
InSitu_FORK_MODE
=
worker
The parent defers initialization and each worker starts its own agent. Use this setting only when the application is loaded before workers fork. Inside the workers, use the
spawn
process start method instead of creating additional children with
fork
.
4
Configure your Dockerfile
To enable Docker-based deployments, define a
GIT_COMMIT
build argument inside your
Dockerfile
with a default value of
unknown
:
Dockerfile
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 the correct SHA in CI/CD
InSitu does not start if
commit_sha
is missing or
unknown
. Pass the commit SHA of the source used to build the application to
GIT_COMMIT
during deployment.
You can use your CI/CD platform’s commit SHA variable when it matches the checked-out source:
Platform / Engine
Configuration Option
Build Argument Syntax
GitHub Actions
Default checkout
--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
On a
pull_request
workflow, GitHub Actions checks out a merge commit by default. If you build that checkout, use its SHA. If you explicitly check out the PR head, use the head SHA instead.
git rev-parse HEAD
reports the checked-out commit.
Configuration & Environment Variables Reference
You can configure the agent by passing properties inside your
InSitu.start()
options object, or by using
environment variables
.
The following example includes the available programmatic options and their corresponding environment variables:
InSitu_init.py
import
os
from
InSitu
import
InSitu
InSitu.start({
# --- CORE OPTIONS ---
"service_id"
:
"<service-uuid-from-dashboard>"
,
"environment"
: os.getenv(
"InSitu_ENVIRONMENT"
)
or
os.getenv(
"PYTHON_ENV"
),
"broker_url"
:
"https://logger.app.useinsitu.com"
,
"commit_sha"
: os.getenv(
"InSitu_COMMIT_SHA"
)
or
os.getenv(
"GIT_COMMIT"
),
# --- BUFFERING & PERFORMANCE ---
"max_queue_size"
:
100
,
# Env: InSitu_MAX_QUEUE_SIZE
"flush_interval_ms"
:
1000
,
# Env: InSitu_FLUSH_INTERVAL_MS
"sync_interval_ms"
:
60000
,
# Env: InSitu_SYNC_INTERVAL_MS
# --- SAFETY GUARDRAILS ---
"hits_per_sec"
:
10
,
# Env: InSitu_HITS_PER_SEC
"bandwidth_kb_per_sec"
:
1024
,
# Env: InSitu_BANDWIDTH_KB_PER_SEC
"InSitu_max_lag_ms"
:
50
,
# Env: InSitu_MAX_LAG_MS
"InSitu_pause_budget_ms"
:
15
,
# Env: InSitu_PAUSE_BUDGET_MS
"InSitu_cooldown_sec"
:
10
,
# Env: InSitu_COOLDOWN_SEC
"InSitu_rpc_timeout_sec"
:
10
,
# Env: InSitu_RPC_TIMEOUT_SEC
# --- DATA & REDACTION CONTROLS ---
"redact_keys"
: [
# Env: InSitu_REDACT_KEYS
"password"
,
"secret"
,
"token"
,
"authorization"
,
"cookie"
,
"key"
,
"signature"
],
"redact_values"
: [],
# Env: InSitu_REDACT_VALUES
"max_object_depth"
:
3
,
# Env: InSitu_MAX_OBJECT_DEPTH
"max_array_length"
:
3
,
# Env: InSitu_MAX_ARRAY_LENGTH
"max_object_properties"
:
50
,
# Env: InSitu_MAX_OBJECT_PROPERTIES
"max_string_length"
:
1024
,
# Env: InSitu_MAX_STRING_LENGTH
"stack_frame_depth"
:
3
,
# Env: InSitu_STACK_FRAME_DEPTH
})
Option precedence:
Nonempty options in this example take precedence over their environment variables. Omit an option to configure it through the environment.
Required settings:
Provide a UUIDv4 service ID, environment, broker URL, and commit SHA. They can also be supplied through
InSitu_SERVICE_ID
,
InSitu_ENVIRONMENT
,
InSitu_BROKER_URL
, and
InSitu_COMMIT_SHA
or
GIT_COMMIT
. If initialization fails, the application continues without the agent.
Disabling the agent:
Set
InSitu_DISABLED=YES
to disable startup.
Redaction
redact_keys
and
redact_values
are lists of case-insensitive regular expressions. Their environment variables accept comma-separated patterns. A custom key list replaces the defaults, so include the defaults when adding keys.
Key redaction does not protect the result of a scalar watch expression such as
password
. Avoid watching sensitive values, and configure value-redaction patterns for secrets that may appear in captured strings.
Safe evaluation
Safe evaluation is enabled by default and restricts calls in probe expressions. It is not a security sandbox: properties and operators can still run application code. Use trusted probes.
To allow arbitrary function and method calls, set
InSitu_DISABLE_SAFE_EVALUATION=true
or pass
"disable_safe_evaluation": True
to
InSitu.start()
.
Disabling safe evaluation allows expressions to change application state or block execution. The agent cannot safely interrupt an expression that is already running.
Safety shields
The Python agent monitors scheduler lag and the time spent handling probes:
Yellow threshold:
The pause budget exceeds 50%, four of the last ten lag readings exceed 50 ms, or one of the last five readings exceeds 200 ms.
Red threshold:
The pause budget exceeds 15 ms per second, seven of the last ten lag readings exceed 50 ms, or three of the last five readings exceed 200 ms. The agent suspends instrumentation.
Auto-recovery:
Resumes probes after the cooldown period (default 10 seconds), once health returns to GREEN.
These thresholds use the defaults above. Set
DEBUG=InSitu:agent
before startup to see safety logs.
Kotlin SDK Setup Guide
Previous
Ruby 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
Installation
Initialization Walkthrough
Configuration & Environment Variables Reference
Redaction
Safe evaluation
Safety shields