Skip to main content
Observability is how you answer “what happened?” after code execution completes. isol8 provides layered visibility:
  • debug logs for engine internals
  • execution audit records
  • resource usage metrics
  • optional network request logs

​
Debug logging

​
CLI

isol8 run script.py --debug
isol8 serve \
  --debug \
  --key my-key

​
Library

new DockerIsol8({ debug: true });
Debug logs are useful for:
  • pool acquisition/release behavior
  • container lifecycle operations
  • persist/cleanup decisions
  • request-level execution timing signals
Use --debug first when triaging behavior differences. It is the fastest way to inspect mode selection, pool behavior, and runtime lifecycle decisions.

​
Audit logging

Enable in config: 
{
  "audit": {
    "enabled": true,
    "destination": "filesystem",
    "logDir": "./.isol8_audit",
    "trackResources": true,
    "retentionDays": 30
  }
}
audit.destination currently supports filesystem and stdout. The default log file path is ./.isol8_audit/executions.log unless audit.logDir (or ISOL8_AUDIT_DIR) is set.

​
What gets recorded

Audit records can include:
  • execution identifiers and timestamps
  • runtime, exit code, duration
  • code hash
  • metadata (when provided)
  • security/network events
  • resource usage metrics
Depending on includeCode and includeOutput, source and output may also be persisted.
includeCode and includeOutput are privacy-sensitive. Keep both disabled unless you explicitly need forensic capture and have strict retention/access controls.

​
Resource usage telemetry

When resource tracking is enabled, ExecutionResult may include:
  • resourceUsage.cpuPercent
  • resourceUsage.memoryMB
  • resourceUsage.networkBytesIn
  • resourceUsage.networkBytesOut
Use this for:
  • anomaly detection (sudden memory spikes)
  • capacity planning (baseline CPU/memory per workload)
  • policy tuning (timeouts and limits)

​
Network logs

When both conditions are true:
  • network = "filtered"
  • logNetwork = true
ExecutionResult.networkLogs can include per-request allow/block entries. This is especially useful when debugging allowlist/denylist policy behavior.
networkLogs are only returned when both network: "filtered" and logNetwork: true are set.

​
Retention and privacy guidance

  • Keep includeCode and includeOutput disabled by default.
  • Configure retention (retentionDays) for compliance requirements.
  • Restrict filesystem permissions on audit directories.
  • Use metadata carefully (avoid PII unless required).

​
Quick verification

isol8 config --json
isol8 run script.py --debug

​
Example incident workflow

  1. Re-run failing task with --debug.
  2. Inspect exitCode, stderr, durationMs, and truncated.
  3. Review resourceUsage for saturation.
  4. If filtered mode is used, inspect networkLogs for blocked hosts.
  5. Correlate with audit entries by executionId.

​
FAQ

resourceUsage is only populated when audit logging with trackResources is enabled.
You need both network: "filtered" and logNetwork: true. If either is missing, network logs are omitted.
By default, logs are written under ./.isol8_audit in the current working directory, unless overridden by audit.logDir or ISOL8_AUDIT_DIR.

​
Troubleshooting quick checks

  • No audit records written: verify audit.enabled: true and a supported audit.destination.
  • Expected code/output not in audit: check audit.includeCode / audit.includeOutput.
  • Old logs not deleted: ensure audit.retentionDays > 0 and log directory permissions allow cleanup.
  • Missing network diagnostics: ensure both network: "filtered" and logNetwork: true.

Configuration reference

Full audit config fields, defaults, and precedence.

Security and network

Understand filtered networking, allow/deny rules, and security tradeoffs.

Execution guide

Execution result fields, streaming behavior, and output semantics.

Troubleshooting

Diagnose runtime, logging, and server failures.