Merge pull request #30802 from anusha-ragunathan/debug_docs

Add plugin debug docs.

docs/extend/index.md

@@ -17,10 +17,10 @@ title: Managed plugin system
 
 * [Installing and using a plugin](index.md#installing-and-using-a-plugin)
 * [Developing a plugin](index.md#developing-a-plugin)
+* [Debugging plugins](index.md#debugging-plugins)
 
 Docker Engine's plugins system allows you to install, start, stop, and remove
-plugins using Docker Engine. This mechanism is currently only available for
-volume drivers, but more plugin driver types will be available in future releases.
+plugins using Docker Engine. 
 
 For information about the legacy plugin system available in Docker Engine 1.12
 and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md).
@@ -212,7 +212,9 @@ Consider the following `config.json` file.
 		   "types": ["docker.volumedriver/1.0"],
 		   "socket": "sshfs.sock"
 	},
-	"capabilities": ["CAP_SYS_ADMIN"]
+	"linux": {
+		"capabilities": ["CAP_SYS_ADMIN"]
+	}
 }
 ```
 
@@ -231,3 +233,59 @@ in subdirectory `rootfs`.
 After that the plugin `<plugin-name>` will show up in `docker plugin ls`.
 Plugins can be pushed to remote registries with
 `docker plugin push <plugin-name>`.
+
+
+## Debugging plugins
+
+Stdout of a plugin is redirected to dockerd logs. Such entries have a
+`plugin=<ID>` suffix. Here are a few examples of commands for pluginID
+`f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62` and their
+corresponding log entries in the docker daemon logs.
+
+```bash
+$ docker plugin install tiborvass/sample-volume-plugins
+
+INFO[0036] Starting...       Found 0 volumes on startup  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+```
+
+```bash
+$ docker volume create -d tiborvass/sample-volume-plugins samplevol
+
+INFO[0193] Create Called...  Ensuring directory /data/samplevol exists on host...  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+INFO[0193] open /var/lib/docker/plugin-data/local-persist.json: no such file or directory  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+INFO[0193]                   Created volume samplevol with mountpoint /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+INFO[0193] Path Called...    Returned path /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+```
+
+```bash
+$ docker run -v samplevol:/tmp busybox sh
+
+INFO[0421] Get Called...     Found samplevol                plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+INFO[0421] Mount Called...   Mounted samplevol              plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+INFO[0421] Path Called...    Returned path /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+INFO[0421] Unmount Called... Unmounted samplevol            plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
+```
+
+#### Using docker-runc to obtain logfiles and shell into the plugin.
+
+`docker-runc`, the default docker container runtime can be used for debugging
+plugins. This is specifically useful to collect plugin logs if they are
+redirected to a file.
+
+```bash
+$ docker-runc list
+ID                                                                 PID         STATUS      BUNDLE                                                                                       CREATED
+f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62   2679        running     /run/docker/libcontainerd/f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62	2017-02-06T21:53:03.031537592Z
+r
+```
+
+```bash
+$ docker-runc exec f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 cat /var/log/plugin.log
+```
+
+If the plugin has a built-in shell, then exec into the plugin can be done as
+follows:
+```bash
+$ docker-runc exec -t f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 sh
+```
+