Merge pull request #186 from containers/sboeuf/readme-update

virtc: Improve logging and documentation

hack/virtc/README.md

@@ -51,6 +51,27 @@ $ sudo su
 
 `virtcontainers-setup.sh` setup your environment performing different tasks. Particularly, it creates a __busybox__ bundle, and it creates CNI configuration files needed to run `virtc` with CNI plugins.
 
+### Get cc-proxy (optional)
+
+If you plan to start `virtc` with the hyperstart agent, you will have to use [cc-proxy](https://github.com/clearcontainers/proxy) as a proxy, meaning you have to perform extra steps to setup your environment.
+
+```
+$ go get github.com/clearcontainers/proxy
+$ make
+$ sudo make install
+```
+If you want to see the traces from the proxy when `virtc` will run, you can manually start it with appropriate debug level:
+
+```
+$ sudo /usr/libexec/clearcontainers/cc-proxy -v 3
+```
+This will generate output similar to the following:
+```
+I0410 08:58:49.058881    5384 proxy.go:521] listening on /var/run/clearcontainers/proxy.sock
+I0410 08:58:49.059044    5384 proxy.go:566] proxy started
+```
+The proxy socket specified in the example log output has to be used as `virtc`'s `--proxy-url` option.
+
 ### Run virtc
 
 All following commands __MUST__ be run as root. By default, and unless you decide to modify it and rebuild it, `virtc` starts empty pods (no container started).
@@ -63,26 +84,34 @@ All following commands __MUST__ be run as root. By default, and unless you decid
 ```
 # ./virtc pod run -agent="hyperstart" -network="CNI" -proxy="ccProxy" -proxy-url="unix:///var/run/clearcontainers/proxy.sock" -pause-path="/tmp/bundles/pause_bundle/rootfs/bin/pause"
 ```
-This should generate that kind of output
+This will generate output similar to the following:
 ```
-Created pod 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
+Pod 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 created
 ```
 
 #### Start an existing pod
 ```
 # ./virtc pod start -id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
+This will generate output similar to the following:
+```
+Pod 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 started
+```
 
 #### Stop an existing pod
 ```
 # ./virtc pod stop -id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
+This will generate output similar to the following:
+```
+Pod 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 stopped
+```
 
 #### Get the status of an existing pod and its containers
 ```
 # ./virtc pod status -id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
-This should generate the following output (assuming the pod has been started):
+This will generate output similar to the following (assuming the pod has been started):
 ```
 POD ID                                  STATE   HYPERVISOR      AGENT
 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8    running qemu            hyperstart
@@ -94,6 +123,10 @@ CONTAINER ID    STATE
 ```
 # ./virtc pod delete -id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
+This will generate output similar to the following:
+```
+Pod 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 deleted
+```
 
 #### List all existing pods
 ```
@@ -112,16 +145,16 @@ POD ID                                  STATE   HYPERVISOR      AGENT
 ```
 # ./virtc container create -id=1 -pod-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 -rootfs="/tmp/bundles/busybox/rootfs" -cmd="/bin/ifconfig"
 ```
-This should generate the following output:
+This will generate output similar to the following:
 ```
-Created container 1
+Container 1 created
 ```
 
 #### Start an existing container
 ```
 # ./virtc container start -id=1 -pod-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
-This should generate the following output:
+This will generate output similar to the following:
 ```
 Container 1 started
 ```
@@ -130,7 +163,7 @@ Container 1 started
 ```
 # ./virtc container enter -id=1 -pod-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 -cmd="/bin/ps"
 ```
-This should generate the following output:
+This will generate output similar to the following:
 ```
 Container 1 entered
 ```
@@ -139,7 +172,7 @@ Container 1 entered
 ```
 # ./virtc container stop -id=1 -pod-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
-This should generate the following output:
+This will generate output similar to the following:
 ```
 Container 1 stopped
 ```
@@ -148,7 +181,7 @@ Container 1 stopped
 ```
 # ./virtc container delete -id=1 -pod-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
-This should generate the following output:
+This will generate output similar to the following:
 ```
 Container 1 deleted
 ```
@@ -157,7 +190,7 @@ Container 1 deleted
 ```
 # ./virtc container status -id=1 -pod-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
 ```
-This should generate the following output (assuming the container has been started):
+This will generate output similar to the following (assuming the container has been started):
 ```
 CONTAINER ID    STATE
 1               running

hack/virtc/main.go

@@ -23,12 +23,14 @@ import (
 	"strings"
 	"text/tabwriter"
 
-	log "github.com/Sirupsen/logrus"
+	"github.com/Sirupsen/logrus"
 	"github.com/urfave/cli"
 
 	vc "github.com/containers/virtcontainers"
 )
 
+var virtcLog = logrus.New()
+
 var listFormat = "%s\t%s\t%s\t%s\n"
 var statusFormat = "%s\t%s\n"
 
@@ -330,7 +332,7 @@ func createPod(context *cli.Context) error {
 		return fmt.Errorf("Could not create pod: %s", err)
 	}
 
-	fmt.Printf("Created pod %s\n", p.ID())
+	fmt.Printf("Pod %s created\n", p.ID())
 
 	return nil
 }
@@ -352,29 +354,35 @@ func checkContainerArgs(context *cli.Context, f func(context *cli.Context) error
 }
 
 func deletePod(context *cli.Context) error {
-	_, err := vc.DeletePod(context.String("id"))
+	p, err := vc.DeletePod(context.String("id"))
 	if err != nil {
 		return fmt.Errorf("Could not delete pod: %s", err)
 	}
 
+	fmt.Printf("Pod %s deleted\n", p.ID())
+
 	return nil
 }
 
 func startPod(context *cli.Context) error {
-	_, err := vc.StartPod(context.String("id"))
+	p, err := vc.StartPod(context.String("id"))
 	if err != nil {
 		return fmt.Errorf("Could not start pod: %s", err)
 	}
 
+	fmt.Printf("Pod %s started\n", p.ID())
+
 	return nil
 }
 
 func stopPod(context *cli.Context) error {
-	_, err := vc.StopPod(context.String("id"))
+	p, err := vc.StopPod(context.String("id"))
 	if err != nil {
 		return fmt.Errorf("Could not stop pod: %s", err)
 	}
 
+	fmt.Printf("Pod %s stopped\n", p.ID())
+
 	return nil
 }
 
@@ -540,7 +548,7 @@ func createContainer(context *cli.Context) error {
 		return fmt.Errorf("Could not create container: %s", err)
 	}
 
-	fmt.Printf("Created container %s\n", c.ID())
+	fmt.Printf("Container %s created\n", c.ID())
 
 	return nil
 }
@@ -767,6 +775,23 @@ func main() {
 	virtc.Name = "VirtContainers CLI"
 	virtc.Version = "0.0.1"
 
+	virtc.Flags = []cli.Flag{
+		cli.BoolFlag{
+			Name:  "debug",
+			Usage: "enable debug output for logging",
+		},
+		cli.StringFlag{
+			Name:  "log",
+			Value: "",
+			Usage: "set the log file path where internal debug information is written",
+		},
+		cli.StringFlag{
+			Name:  "log-format",
+			Value: "text",
+			Usage: "set the format used by logs ('text' (default), or 'json')",
+		},
+	}
+
 	virtc.Commands = []cli.Command{
 		{
 			Name:  "pod",
@@ -795,8 +820,38 @@ func main() {
 		},
 	}
 
+	virtc.Before = func(context *cli.Context) error {
+		if context.GlobalBool("debug") {
+			virtcLog.Level = logrus.DebugLevel
+		}
+
+		if path := context.GlobalString("log"); path != "" {
+			f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND|os.O_SYNC, 0640)
+			if err != nil {
+				return err
+			}
+			virtcLog.Out = f
+		}
+
+		switch context.GlobalString("log-format") {
+		case "text":
+			// retain logrus's default.
+		case "json":
+			virtcLog.Formatter = new(logrus.JSONFormatter)
+		default:
+			return fmt.Errorf("unknown log-format %q", context.GlobalString("log-format"))
+		}
+
+		// Set virtcontainers logger.
+		vc.SetLog(virtcLog)
+
+		return nil
+	}
+
 	err := virtc.Run(os.Args)
 	if err != nil {
-		log.Fatal(err)
+		virtcLog.Fatal(err)
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
 	}
 }