Skip to main content
The Antithesis environment is the virtual system where we run your containers — it’s the universe in some branch of the testing multiverse.
You can read more about the specifics of the system in our Antithesis environment documentation, but for our purposes, you can think of it as a Linux system that’s been customized for testing.
Inside the multiverse debugging notebook, you can use the environment object to access the following features that relate to the Antithesis environment: You can also run commands on your containers with bash fragments.

​
The environment object

Inside a multiverse debugging session, the environment object represents the system as a whole. In each moment, the Antithesis environment is in some state. There are probably containers running your software, there may be Antithesis faults in progress, and there are certainly some background services supporting the system. When you begin your session, the environment object is already defined for you: 
// `environment` here is your environment
[environment, moment] = prepare_multiverse_debugging()
As a rule of thumb, you’ll typically use the environment when you’re inspecting and configuring the system as a whole.

​
Getting system logs

Sometimes, when you’re diagnosing a problem, it’s helpful to see what’s going on with the system as a whole. System logs are available through the environment object as curated event sets.
When events are the result of readable (non-binary) program output, an event is sent each time the output contains a newline character.
Provided event sets include:
  • environment.containers.events: output from all of the containers
  • environment.containers.meta_events: changes to containers (create, start, stop, etc) as seen by the container management system
  • environment.sdk.all_events: all of the events that have been processed through the Antithesis SDK
  • environment.sdk.assertions: assertions defined with the Antithesis SDK which have been encountered
  • environment.events: the main event source, including the sources above
  • environment.fault_injector.events: high level information about the status of the fault injector
  • environment.fault_injector.faults: information about each of the discrete faults introduced by the fault injector (this does not include background chaos like thread interleavings or baseline packet drop rates)
  • environment.background_monitor.events: raw output from the Antithesis system utilization monitor (Warning: this is a new feature and its format may be unusually unstable!)
  • environment.journal.events : the main logger on the system, including for various daemons. It can be verbose, but it is the right place to notice (for instance) the system OOM-killer. (read more at man journald)

​
Listing containers

Container commands currently do not work if you are using Kubernetes. You can use kubectl to interact with the kubernetes cluster:
print(bash`kubectl get pod`.run({branch: guest_branch, container: env.host}))
{%endnotebook_example%}
You can list all of your containers as of some moment. 
[environment, moment] = prepare_multiverse_debugging()
print(environment.containers.list({moment}))
notebook output
[
    {
        name: "myworkload",
        id: "5bf984f4b13cdb1aad334c80113d72b8b480984c4ae3d98da988c70975ca4af8",
        state: "running",
        image: "us-central1-docker.pkg.dev/molten-verve-216720/my-company-repository/my_db:latest",
        image_id: "20a003596f19ddcd16bd1c3ce30e0c3dedda40f959ead53e46a6e45e3452fa18"
    }
]

​
Extracting files

Sometimes, the best tool for inspecting a file is one you have locally. In cases like that, you can extract the file and download it. 
// To extract a file, use the container name and the path in the container
link = environment.extract_file({moment, path: "/run/myservice.db", container: "myworkload"})

// You can also extract a file from an image if you need to.
link = environment.extract_file({moment, path: "/run/myservice.db", image: "my_db"})

// Print the result to get a download link
print(link)
notebook output
[Download myservice.log (808712 bytes)](https://youtu.be/dQw4w9WgXcQ)

​
Injecting files

Sometimes, you may want to inject a file in your container after it’s started. In cases like that, use inject_file(). 
    // To inject a file, use the container name, the path in the container, and the file_data you want to inject.
    stat = environment.inject_file({
                        branch, 
                        path: "/run/testing.sh",
                        container: "mycontainer", 
                        file_data: bash`echo hello`, 
                        permissions: "0755"
                    })

    // Print the result to see the stat results
    print(stat)

​
Configuring fault injection

If you’re exploring a moment from the middle of a test, Antithesis might have been disrupting the network or other containers. If you want to stop these faults, either to see whether your software recovers or to make other debugging clearer, you can use environment.fault_injector.pause, and if you want to resume, you can use environment.fault_injector.unpause.

​
Profiling CPU usage

The Environment includes a CPU profiler, which is a powerful way to investigate what’s happening during some part of a branch. Here’s what it looks like to use the profiler. 
// Start the profiler on some branch
background_profiler = environment.profiler.start({branch})

// You can optionally supply a PID if you want to look at a particular process.
// background_profiler = environment.profiler.start({branch, pid: 1})

// Advance time on the branch
// Note that instead of waiting, you could run commands here.
// This is especially helpful for investigating the performance of a series of commands
branch.wait(Time.seconds(10))

// Stop the profiler on the branch
environment.profiler.stop({branch, background_profiler})

// View the results as of the end of the branch
print(environment.profiler.report({moment: branch.end}))

​
Running commands

To run a command in one of your containers, you can use a bash fragment. Commands return a process object.
Since we know that many lightweight containers don’t include bash, Antithesis mounts a shell and assorted shell tools into every container at runtime, making it possible to run bash commands even in minimal containers.
There are two main ways to run a bash fragment: in the foreground and the background. Either way, you need to supply a container, so we know where to run a command, and a branch, so we know when in the multiverse to run it. Running a bash command will return a process object.

​
Running a command with .run()

Most of the time, when you want to run a command, you want to run it to completion. If you call .run() on a fragment, it will run until it finishes, advancing the branch until the command has exited. If the command doesn’t exit, .run() will fail after 30 virtual minutes have passed. You can supply an optional timeout to change how long it waits. 
print(
  bash`echo 'hello world!'`.run({
    container: "myworkload", 
    timeout: Time.seconds(2), 
    branch
  })
)
notebook output
78.513  info    hello world

​
Starting a command with .run_in_background()

Sometimes, you want to start a long-running command and not wait for it to complete. When that happens, you can use .run_in_background(). Unlike .run(), .run_in_background() only advances time on the branch until after the command has been delivered. It might not even be started until time has advanced on the branch! If you print the result, you’ll still see the output as it comes in (see the process object notes for more of an explanation). 
print(bash`while true ; do du -hs /* && echo "" ; sleep 2 ; done`.run_in_background({container: "myworkload", branch}))
branch.wait(Time.seconds(10))
notebook output
73.938  info    17404	/
73.938  info    
76.111  info    17408	/
76.111  info    
78.283  info    17413	/
78.283  info    
80.455  info    17413	/
80.455  info    
82.626  info    17420	/
82.627  info

​
Bash fragments

The multiverse debugging environment supports running shell commands with bash fragments. A bash fragment is a JavaScript tagged template literal containing the command that you want to run. 
bash`echo 'hello world!'`
Like regular JavaScript templates, you can interpolate, but bash fragments escape intelligently. 
s = 'This is a multicharacter string'
print(bash`echo ${s}`)

bash`echo "This is a multicharacter string"`

b = bash`ls /`
print(bash`MY_VARIABLE="foo" ${b}`) 
// equivalent to: bash`MY_VARIABLE="foo" ls /`

b = bash`ls /`
bash`MY_VARIABLE="foo" ls /`

​
Process objects

When you run a command in our environment, the result is a process object representing the execution of that process on the branch. You can print a process to view its output. 
proc = bash`ps`.run({container: "myworkload", branch})
print(proc)
notebook output
73.446  info    Every 2.0s: ps
                2024-08-19 19:57:56
73.446  info
73.447  info    PID     USER    TIME    COMMAND
73.447  info      1     root    0:00    sleep infinity
73.447  info      2     root    0:00    watch ps
73.447  info      4     root    0:00    timeout 10 watch ps
73.447  info      5     root    0:00    ps
You can also call help(proc) for more details on what you can do with a process object.

​
Highlights

  • Process-specific event sets, including proc.events, proc.stdout, proc.stderr, and proc.exits.
  • proc.pid is the PID of the process inside our virtual system.
  • proc.exited_by(moment) will return true if the process existed in the branch that ends with the supplied moment, and had exited.
  • proc.exit_code is the exit code that the process returned.

​
Background processes

Whether you use .run() or .run_in_background(), the process will have the same shape, but the behavior may be slightly different. In particular, when you get a Process object from .run_in_background(), its properties will be true as of the current state of the branch it was run on.
  • proc.exit_code will be undefined if the process hasn’t returned yet.
  • proc.pid will be undefined if the process hasn’t forked yet.
However, when you print() a process that results from .run_in_background(), you will see the events associated with the process on the branch that it was constructed from, as though the print were written below the last update to the branch in the notebook.