svn commit: r1633372 - /incubator/slider/site/trunk/content/docs/manpage.md

[st...@apache.org]

Author: stevel
Date: Tue Oct 21 13:22:44 2014
New Revision: 1633372

URL: http://svn.apache.org/r1633372
Log:
SLIDER-548 Slider exists command to add --state probe

Modified:
    incubator/slider/site/trunk/content/docs/manpage.md

Modified: incubator/slider/site/trunk/content/docs/manpage.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/docs/manpage.md?rev=1633372&r1=1633371&r2=1633372&view=diff
==============================================================================
--- incubator/slider/site/trunk/content/docs/manpage.md (original)
+++ incubator/slider/site/trunk/content/docs/manpage.md Tue Oct 21 13:22:44 2014
@@ -61,7 +61,7 @@ and existing but not running "stopped" a
 
 1. The supported component types depends upon the slider application.
 
-1. the count of each component must initially be specified when a application instance is created.
+1. the count of each component must initially be specified when an application instance is created.
 
 1. Users can flex an application instance: adding or removing components dynamically.
 If the application instance is live, the changes will have immediate effect. If not, the changes will be picked up when the instance is next thawed.
@@ -135,7 +135,7 @@ This define the slider application packa
 
 ##### `--option <name> <value>`  
 
-Set a application instance option. 
+Set an application instance option. 
 
 Example:
 
@@ -277,44 +277,78 @@ Example
 
     slider destroy instance1
 
-### `exists <name> [--live]`
+### `exists <name> [--live] [--status status]`
 
 Probe the existence of the named Slider application instance. If the `--live` flag is set, the instance
 must actually be running
 
 If not, an error code is returned.
 
-When the --live` flag is unset, the command looks for the application instance to be
+When the `--live` flag is unset, the command looks for the application instance to be
 defined in the filesystem -its operation state is not checked.
 
-Return codes
-
-     0 : application instance is defined in the filesystem
-    70 : application instance is unknown
+it will "succeed" if the definition files of the named application instance 
+are found.
 
 Example:
 
     slider exists instance4
 
+Return codes
+
+     0 : application instance is running
+    -1 : application instance exists but is not running
+    69 : application instance is unknown
+
+
 #### Live Tests
 
-When the `--live` flag is set, the application instance must be running for the command
-to succeed
+When the `--live` flag is set, the application instance must be running
+or about to run for the probe to succeed. 
+That is, either application is running (`RUNNING`) or in any of the states
+from which an application can start running. That means the service can be
+in any of the states `NEW`, `NEW_SAVING`, `SUBMITTED`, `ACCEPTED` or `RUNNING`
+
+An application instance that is `FINISHED` or `FAILED` or `KILLED` is not considered to be live.
 
-1. The probe does not check the status of any Slider-deployed services, merely that a application instance has been deployed
-1. A application instance that is finished or failed is not considered to be live.
+
+Note that probe does not check the *liveness* of the actually deployed application,
+merely that the application instance has been deployed
 
 Return codes
 
      0 : application instance is running
     -1 : application instance exists but is not running
-    70 : application instance is unknown
-
+    69 : application instance is unknown
 
 Example:
 
     slider exists instance4 --live
 
+When the `--state` flag is set, a specific YARN application state is checked for.
+
+The allowed YARN states are:
+
+      NEW: Application which was just created.
+      NEW_SAVING: Application which is being saved.
+      SUBMITTED: Application which has been submitted. 
+      ACCEPTED: Application has been accepted by the scheduler
+      RUNNING: Application which is currently running. 
+      FINISHED:  Application which finished successfully. 
+      FAILED: Application which failed.
+      KILLED: Application which was terminated by a user or admin.
+
+Example:
+
+    slider exists instance4 --state ACCEPTED
+
+Return codes
+
+     0 : application instance is running
+    -1 : application instance exists but is not in the desired state
+    69 : application instance is unknown
+
+
 ### `flex <name> [--component component count]* `
 
 Flex the number of workers in an application instance to the new value. 
@@ -381,7 +415,7 @@ Example
     slider list instance1
     slider list --live --history
 
-### `registry (--list | --listconf | --getconf <conf> | --resolve <path>) [--name <name>] [--servicetype <servicetype>] [--out <filename>] [--verbose]`
+### `registry (--list | --listconf | --getconf <conf> ) [--name <name>] [--servicetype <servicetype>] [--out <filename>] [--verbose]`
 
 List registered application instances visible to the user. This is slightly
 different from the `slider list` command in that it does not make use of the
@@ -475,11 +509,17 @@ and save it to a file
 If the specified path is not in the registry, or the path exists but there
 is no service record there, the return code is `EXIT_NOT_FOUND`, 77.
 
-### List all services under a path: `slider resolve --path <path> --list`
+### List all entries and services under a path: `slider resolve --path <path> --list`
 
 `slider resolve --path <path> --list` command will list all service records
-directly under a path. The listing can be displayed in the console, or saved
-to a directory, one JSON file per entry. The `--destdir` option enables
+directly under a path.
+ 
+The all entries will be listed to the console,
+followed by the individual service records of those entries that contain
+a service record declaration.
+
+The service records can be saved to a directory, one JSON file per entry.
+ The `--destdir` option enables
 this saving of the entries —and identifies the destination directory for them.
 Each entry will be saved with the entry name suffixed by `.json`.