gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/pkg/test/dockerutil/README.md (about)

     1  # dockerutil
     2  
     3  This package is for creating and controlling docker containers for testing
     4  runsc, gVisor's docker/kubernetes binary. A simple test may look like:
     5  
     6  ```
     7   func TestSuperCool(t *testing.T) {
     8     ctx := context.Background()
     9     c := dockerutil.MakeContainer(ctx, t)
    10     got, err := c.Run(ctx, dockerutil.RunOpts{
    11       Image: "basic/alpine"
    12     }, "echo", "super cool")
    13     if err != nil {
    14        t.Fatalf("err was not nil: %v", err)
    15     }
    16     want := "super cool"
    17     if !strings.Contains(got, want){
    18       t.Fatalf("want: %s, got: %s", want, got)
    19     }
    20   }
    21  ```
    22  
    23  For further examples, see many of our end to end tests elsewhere in the repo,
    24  such as those in //test/e2e or benchmarks at //test/benchmarks.
    25  
    26  dockerutil uses the "official" docker golang api, which is
    27  [very powerful](https://godoc.org/github.com/docker/docker/client). dockerutil
    28  is a thin wrapper around this API, allowing desired new use cases to be easily
    29  implemented.
    30  
    31  ## Profiling
    32  
    33  dockerutil is capable of generating profiles. Currently, the only option is to
    34  use pprof profiles generated by `runsc debug`. The profiler will generate Block,
    35  CPU, Heap, Goroutine, and Mutex profiles. To generate profiles:
    36  
    37  *   Install runsc with the `--profile` flag: `make configure RUNTIME=myrunsc
    38      ARGS="--profile"` Also add other flags with ARGS like `--platform=kvm`.
    39  *   Restart docker: `sudo service docker restart`
    40  
    41  To run and generate CPU profiles run:
    42  
    43  ```
    44  make sudo TARGETS=//path/to:target \
    45    ARGS="--runtime=myrunsc -test.v -test.bench=. --pprof-cpu" OPTIONS="-c opt"
    46  ```
    47  
    48  Profiles would be at: `/tmp/profile/myrunsc/CONTAINERNAME/cpu.pprof`
    49  
    50  Container name in most tests and benchmarks in gVisor is usually the test name
    51  and some random characters like so:
    52  `BenchmarkABSL-CleanCache-JF2J2ZYF3U7SL47QAA727CSJI3C4ZAW2`
    53  
    54  Profiling requires root as runsc debug inspects running containers in /var/run
    55  among other things.
    56  
    57  ### Writing for Profiling
    58  
    59  The below shows an example of using profiles with dockerutil.
    60  
    61  ```
    62  func TestSuperCool(t *testing.T){
    63    ctx := context.Background()
    64    // profiled and using runtime from dockerutil.runtime flag
    65    profiled := MakeContainer()
    66  
    67    // not profiled and using runtime runc
    68    native := MakeNativeContainer()
    69  
    70    err := profiled.Spawn(ctx, RunOpts{
    71      Image: "some/image",
    72    }, "sleep", "100000")
    73    // profiling has begun here
    74    ...
    75    expensive setup that I don't want to profile.
    76    ...
    77    profiled.RestartProfiles()
    78    // profiled activity
    79  }
    80  ```
    81  
    82  In the above example, `profiled` would be profiled and `native` would not. The
    83  call to `RestartProfiles()` restarts the clock on profiling. This is useful if
    84  the main activity being tested is done with `docker exec` or `container.Spawn()`
    85  followed by one or more `container.Exec()` calls.