19889: Add an id to the container log method documentation

[arvados.git] / doc / api / methods / containers.html.textile.liquid

diff --git a/doc/api/methods/containers.html.textile.liquid b/doc/api/methods/containers.html.textile.liquid
index 6117823d4a67813a16c29d74097a6b4e0a38133b..c2e9d27eba0b20e6e4c136743f5ff42cf2c3d673 100644 (file)
--- a/doc/api/methods/containers.html.textile.liquid
+++ b/doc/api/methods/containers.html.textile.liquid
@@ -28,7 +28,7 @@ table(table table-bordered table-condensed).
 |state|string|The allowed states are "Queued", "Locked", "Running", "Cancelled" and "Complete".|See "Container states":#container_states for more details.|
 |started_at|datetime|When this container started running.|Null if container has not yet started.|
 |finished_at|datetime|When this container finished.|Null if container has not yet finished.|
-|log|string|UUID or portable data hash of a collection containing the log messages produced when executing the container.|PDH after the container is finished, otherwise UUID or null.|
+|log|string|Portable data hash of a collection containing the log messages produced when executing the container.|Null if container has not yet started. The Crunch system will periodically update this field for a running container.|
 |environment|hash|Environment variables and values that should be set in the container environment (@docker run --env@). This augments and (when conflicts exist) overrides environment variables given in the image's Dockerfile.|Must be equal to a ContainerRequest's environment in order to satisfy the ContainerRequest.|
 |cwd|string|Initial working directory.|Must be equal to a ContainerRequest's cwd in order to satisfy the ContainerRequest|
 |command|array of strings|Command to execute.| Must be equal to a ContainerRequest's command in order to satisfy the ContainerRequest.|
@@ -93,6 +93,7 @@ table(table table-bordered table-condensed).
 |activity|string|A message for the end user about what state the container is currently in.|Optional.|
 |errorDetail|string|Additional structured error details.|Optional.|
 |warningDetail|string|Additional structured warning details.|Optional.|
+|preemptionNotice|string|Details about any cloud provider scheduled interruption to the instance running this container.|Existence of this key indicates the container likely was (or will soon be) @Cancelled@ due to an instance interruption.|
 
 h2(#scheduling_parameters). {% include 'container_scheduling_parameters' %}
 
@@ -104,10 +105,12 @@ Required arguments are displayed in %{background:#ccffcc}green%.
 
 Supports federated @get@ and @list@.
 
-h2(#create). create
+h3(#create). create
 
 Create a new Container.
 
+This API requires admin privileges. In normal operation, it should not be used at all.
+
 Arguments:
 
 table(table table-bordered table-condensed).
@@ -160,3 +163,26 @@ Get the api_client_authorization record indicated by this container's auth_uuid,
 table(table table-bordered table-condensed).
 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 {background:#ccffcc}.|uuid|string||path||
+
+h3(#log). log
+
+Get container log data using WebDAV methods.
+
+This API retrieves data from the container's log collection. It can be used at any time in the container lifecycle.
+* While the container is @Queued@ or @Locked@ it returns an empty directory.
+* While the container is @Running@ it returns real-time logging data.
+* While the container is @Complete@ or @Cancelled@ it returns the final log collection.
+
+This API also supports the @Range@ request header, so it can be used to poll for and retrieve logs while the container is running.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+|method|string|Read-only WebDAV method|HTTP method|@GET@, @OPTIONS@, @PROPFIND@|
+{background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
+|path|string|Path to a file in the log collection.|path|@/stderr.txt@|
+
+Examples:
+* @GET /arvados/v1/containers/zzzzz-dz642-0123456789abcde/log/stderr.txt@
+* @PROPFIND /arvados/v1/containers/zzzzz-dz642-0123456789abcde/log/@