[api-ref] Add sections for instance logs.

Change-Id: I3b0eb2103c89610ec494ac33407e8a7969af1164
Signed-off-by: Zhao Chao <zhaochao1984@gmail.com>

14 files changed, 542 insertions, 0 deletions

diff --git a/api-ref/source/database-instance-logs.inc b/api-ref/source/database-instance-logs.inc
new file mode 100644
index 00000000..c40d92ba
--- /dev/null
+++ b/api-ref/source/database-instance-logs.inc
@@ -0,0 +1,349 @@
+.. -*- rst -*-
+
+======================
+Database instance logs
+======================
+
+List, show details, enable, disable, publish, and discard logs for instances.
+
+
+List instance logs
+~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: GET /v1.0/{accountId}/instances/{instanceId}/log
+
+Listing all logs for an instance.
+
+Different datastore backend has its own ``guest_log_exposed_logs``
+configuration to determine which type of logs will be listed by default. For
+admin context, all logs will be listed.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), badMethod(405), overLimit(413), badMediaType(415),
+unprocessableEntity(422), instanceFault(500), notImplemented(501),
+serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - logs: instance_logs
+    - name: log_name
+    - type: log_type
+    - status: log_status
+    - published: log_published_size
+    - pending: log_pending_size
+    - container: log_container
+    - prefix: log_prefix
+    - metafile: log_metafile
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-list-logs-response.json
+   :language: javascript
+
+
+
+
+Show instance log details
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: POST /v1.0/{accountId}/instances/{instanceId}/log
+
+Show details for a instance log.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), badMethod(405), overLimit(413), badMediaType(415),
+unprocessableEntity(422), instanceFault(500), notImplemented(501),
+serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+   - name: log_name
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-show-log-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - log: instance_log
+    - name: log_name
+    - type: log_type
+    - status: log_status
+    - published: log_published_size
+    - pending: log_pending_size
+    - container: log_container
+    - prefix: log_prefix
+    - metafile: log_metafile
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-show-log-response.json
+   :language: javascript
+
+
+
+
+Enable instance log
+~~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: POST /v1.0/{accountId}/instances/{instanceId}/log
+
+Enable a log type for a instance.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), badMethod(405), overLimit(413), badMediaType(415),
+unprocessableEntity(422), instanceFault(500), notImplemented(501),
+serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+   - name: log_name
+   - enable: log_enable_action
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-enable-log-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - log: instance_log
+    - name: log_name
+    - type: log_type
+    - status: log_status
+    - published: log_published_size
+    - pending: log_pending_size
+    - container: log_container
+    - prefix: log_prefix
+    - metafile: log_metafile
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-enable-log-response.json
+   :language: javascript
+
+
+
+
+Disable instance log
+~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: POST /v1.0/{accountId}/instances/{instanceId}/log
+
+Disable a log type for a instance.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), badMethod(405), overLimit(413), badMediaType(415),
+unprocessableEntity(422), instanceFault(500), notImplemented(501),
+serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+   - name: log_name
+   - disable: log_disable_action
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-disable-log-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - log: instance_log
+    - name: log_name
+    - type: log_type
+    - status: log_status
+    - published: log_published_size
+    - pending: log_pending_size
+    - container: log_container
+    - prefix: log_prefix
+    - metafile: log_metafile
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-disable-log-response.json
+   :language: javascript
+
+
+
+
+Publish instance log
+~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: POST /v1.0/{accountId}/instances/{instanceId}/log
+
+Publish a log type for a instance.
+
+*Note:* ``publish`` will automatically ``enable`` a log.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), badMethod(405), overLimit(413), badMediaType(415),
+unprocessableEntity(422), instanceFault(500), notImplemented(501),
+serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+   - name: log_name
+   - publish: log_publish_action
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-publish-log-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - log: instance_log
+    - name: log_name
+    - type: log_type
+    - status: log_status
+    - published: log_published_size
+    - pending: log_pending_size
+    - container: log_container
+    - prefix: log_prefix
+    - metafile: log_metafile
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-publish-log-response.json
+   :language: javascript
+
+
+
+
+Discard instance log
+~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: POST /v1.0/{accountId}/instances/{instanceId}/log
+
+Discard all previously published logs for a instance.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), badMethod(405), overLimit(413), badMediaType(415),
+unprocessableEntity(422), instanceFault(500), notImplemented(501),
+serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+   - name: log_name
+   - discard: log_discard_action
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-discard-log-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - log: instance_log
+    - name: log_name
+    - type: log_type
+    - status: log_status
+    - published: log_published_size
+    - pending: log_pending_size
+    - container: log_container
+    - prefix: log_prefix
+    - metafile: log_metafile
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-discard-log-response.json
+   :language: javascript
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 9c382fa3..d5cf2f4f 100755
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -9,6 +9,7 @@
 .. include:: api-versions.inc
 .. include:: database-instances.inc
 .. include:: database-instance-actions.inc
+.. include:: database-instance-logs.inc
 .. include:: databases.inc
 .. include:: user-management.inc
 .. include:: flavors.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 2c637e03..ff607d1d 100755
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -153,12 +153,101 @@ instance:
   in: body
   required: true
   type: object
+instance_log:
+  description: |
+    A ``log`` objects.
+  in: body
+  required: true
+  type: array
+instance_logs:
+  description: |
+    A list of ``log`` objects.
+  in: body
+  required: true
+  type: array
 instanceName:
   description: |
     Name of the instance.
   in: body
   required: false
   type: string
+log_container:
+  description: |
+    The object store container where the published
+    log data will be stored. Defaults to ``None``
+    before the log has been published.
+  in: body
+  required: true
+  type: string
+log_disable_action:
+  description: |
+    To disable a log type, this should always set to 1.
+  in: body
+  required: false
+  type: integer
+log_discard_action:
+  description: |
+    To discard a log type which has been published previously,
+    this should always set to 1.
+  in: body
+  required: false
+  type: integer
+log_enable_action:
+  description: |
+    To enable a log type, this should always set to 1.
+  in: body
+  required: false
+  type: integer
+log_metafile:
+  description: |
+    The log metafile location.
+  in: body
+  required: true
+  type: string
+log_name:
+  description: |
+    The name of the log.
+  in: body
+  required: true
+  type: string
+log_pending_size:
+  description: |
+    Log file size pending to be published.
+  in: body
+  required: true
+  type: string
+log_prefix:
+  description: |
+    If the log has been published, thi is the prefix location
+    of where the log data are stored. Otherwize the prefix is
+    ``None``.
+  in: body
+  required: true
+  type: string
+log_publish_action:
+  description: |
+    To publish a log type, this should always set to 1.
+  in: body
+  required: false
+  type: integer
+log_published_size:
+  description: |
+    Published size of the log.
+  in: body
+  required: true
+  type: string
+log_status:
+  description: |
+    The log status.
+  in: body
+  required: true
+  type: string
+log_type:
+  description: |
+    The type of the log.
+  in: body
+  required: true
+  type: string
 name:
   description: |
     Name of the configuration group you are creating.
diff --git a/api-ref/source/samples/db-instance-disable-log-request.json b/api-ref/source/samples/db-instance-disable-log-request.json
new file mode 100644
index 00000000..5f199474
--- /dev/null
+++ b/api-ref/source/samples/db-instance-disable-log-request.json
@@ -0,0 +1,4 @@
+{
+    "name": "general",
+    "disable": 1
+}
diff --git a/api-ref/source/samples/db-instance-disable-log-response.json b/api-ref/source/samples/db-instance-disable-log-response.json
new file mode 100644
index 00000000..b17d61de
--- /dev/null
+++ b/api-ref/source/samples/db-instance-disable-log-response.json
@@ -0,0 +1,12 @@
+{
+    "log": {
+            "name": "general",
+            "type": "USER",
+            "status": "Disabled",
+            "published": "4096",
+            "pending": "0",
+            "container": "data_logs",
+            "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
+        }
+}
diff --git a/api-ref/source/samples/db-instance-discard-log-request.json b/api-ref/source/samples/db-instance-discard-log-request.json
new file mode 100644
index 00000000..c2fd2fe2
--- /dev/null
+++ b/api-ref/source/samples/db-instance-discard-log-request.json
@@ -0,0 +1,4 @@
+{
+    "name": "general",
+    "discard": 1
+}
diff --git a/api-ref/source/samples/db-instance-discard-log-response.json b/api-ref/source/samples/db-instance-discard-log-response.json
new file mode 100644
index 00000000..965d7c13
--- /dev/null
+++ b/api-ref/source/samples/db-instance-discard-log-response.json
@@ -0,0 +1,12 @@
+{
+    "log": {
+            "name": "general",
+            "type": "USER",
+            "status": "Ready",
+            "published": "0",
+            "pending": "128",
+            "container": "None",
+            "prefix": "None",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
+        }
+}
diff --git a/api-ref/source/samples/db-instance-enable-log-request.json b/api-ref/source/samples/db-instance-enable-log-request.json
new file mode 100644
index 00000000..bbeafc0a
--- /dev/null
+++ b/api-ref/source/samples/db-instance-enable-log-request.json
@@ -0,0 +1,4 @@
+{
+    "name": "general",
+    "enable": 1
+}
diff --git a/api-ref/source/samples/db-instance-enable-log-response.json b/api-ref/source/samples/db-instance-enable-log-response.json
new file mode 100644
index 00000000..db73af9c
--- /dev/null
+++ b/api-ref/source/samples/db-instance-enable-log-response.json
@@ -0,0 +1,12 @@
+{
+    "log": {
+            "name": "general",
+            "type": "USER",
+            "status": "Eanbled",
+            "published": "0",
+            "pending": "0",
+            "container": "None",
+            "prefix": "None",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
+        }
+}
diff --git a/api-ref/source/samples/db-instance-list-logs-response.json b/api-ref/source/samples/db-instance-list-logs-response.json
new file mode 100644
index 00000000..103d6d05
--- /dev/null
+++ b/api-ref/source/samples/db-instance-list-logs-response.json
@@ -0,0 +1,24 @@
+{
+    "logs": [
+        {
+            "name": "general",
+            "type": "USER",
+            "status": "Partial",
+            "published": "128",
+            "pending": "4096",
+            "container": "data_logs",
+            "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
+        },
+        {
+            "name": "slow_query",
+            "type": "USER",
+            "status": "Ready",
+            "published": "0",
+            "pending": "128",
+            "container": "None",
+            "prefix": "None",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-slow_query_metafile"
+        }
+    ]
+}
diff --git a/api-ref/source/samples/db-instance-publish-log-request.json b/api-ref/source/samples/db-instance-publish-log-request.json
new file mode 100644
index 00000000..f56de2d0
--- /dev/null
+++ b/api-ref/source/samples/db-instance-publish-log-request.json
@@ -0,0 +1,4 @@
+{
+    "name": "general",
+    "publish": 1
+}
diff --git a/api-ref/source/samples/db-instance-publish-log-response.json b/api-ref/source/samples/db-instance-publish-log-response.json
new file mode 100644
index 00000000..b9cfdfb0
--- /dev/null
+++ b/api-ref/source/samples/db-instance-publish-log-response.json
@@ -0,0 +1,12 @@
+{
+    "log": {
+            "name": "general",
+            "type": "USER",
+            "status": "Published",
+            "published": "128",
+            "pending": "0",
+            "container": "data_logs",
+            "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
+        }
+}
diff --git a/api-ref/source/samples/db-instance-show-log-request.json b/api-ref/source/samples/db-instance-show-log-request.json
new file mode 100644
index 00000000..79a2020e
--- /dev/null
+++ b/api-ref/source/samples/db-instance-show-log-request.json
@@ -0,0 +1,3 @@
+{
+    "name": "general"
+}
diff --git a/api-ref/source/samples/db-instance-show-log-response.json b/api-ref/source/samples/db-instance-show-log-response.json
new file mode 100644
index 00000000..23ac0128
--- /dev/null
+++ b/api-ref/source/samples/db-instance-show-log-response.json
@@ -0,0 +1,12 @@
+{
+    "log": {
+            "name": "general",
+            "type": "USER",
+            "status": "Partial",
+            "published": "128",
+            "pending": "4096",
+            "container": "data_logs",
+            "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
+            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
+        }
+}