api-ref: Add X-Openstack-Request-Id description

Add the description for the following items
in the API reference and the API guide.

* 'X-Openstack-Request-Id' header in request
* 'X-Openstack-Request-Id' header in response
* 'X-Compute-Request-Id' in response

Change-Id: Idd9181c1530eb9576da9941416b697a97c0cfb8d
Closes-Bug: #1693555

api-guide/source/faults.rst

@@ -13,11 +13,56 @@ the action you requested has successfully completed.
 Tracking Errors by Request ID
 =============================
 
-Every request made has a unique Request ID.
+There are two types of request ID.
-This is returned in a response header.
-Here is an example response header:
 
-X-Compute-Request-Id: req-4b9e5c04-c40f-4b4f-960e-6ac0858dca6c
+.. list-table::
+  :header-rows: 1
+  :widths: 2,8
+
+  * - Type
+    - Description
+  * - Local request ID
+    - Locally generated unique request ID by each service and different between
+      all services (Nova, Cinder, Glance, Neutron, etc.) involved
+      in that operation. The format is ``req-`` + UUID (UUID4).
+  * - Global request ID
+    - User specified request ID which is utilized as common identifier
+      by all services (Nova, Cinder, Glance, Neutron, etc.) involved
+      in that operation. This request ID is same among all services involved
+      in that operation.
+      The format is ``req-`` + UUID (UUID4).
+
+It is extremely common for clouds to have an ELK (Elastic Search, Logstash,
+Kibana) infrastructure consuming their logs.
+The only way to query these flows is if there is a common identifier across
+all relevant messages. The global request ID immediately makes existing
+deployed tooling better for managing OpenStack.
+
+**Request Header**
+
+In each REST API request, you can specify the global request ID
+in ``X-Openstack-Request-Id`` header, starting from microversion 2.46.
+The format must be ``req-`` + UUID (UUID4).
+If not in accordance with the format, the global request ID is ignored by Nova.
+
+Request header example::
+
+  X-Openstack-Request-Id: req-3dccb8c4-08fe-4706-a91d-e843b8fe9ed2
+
+**Response Header**
+
+In each REST API request, ``X-Compute-Request-Id`` is returned
+in the response header.
+Starting from microversion 2.46, ``X-Openstack-Request-Id`` is also returned
+in the response header.
+
+``X-Compute-Request-Id`` and ``X-Openstack-Request-Id`` are local request IDs.
+The global request IDs are not returned.
+
+Response header example::
+
+  X-Compute-Request-Id: req-d7bc29d0-7b99-4aeb-a356-89975043ab5e
+  X-Openstack-Request-Id: req-d7bc29d0-7b99-4aeb-a356-89975043ab5e
 
 Server Actions
 --------------
@@ -31,9 +76,33 @@ http://developer.openstack.org/api-ref/compute/#servers-run-an-action-servers-ac
 Logs
 ----
 
-All logs on the system, by default, include the request-id when available.
+All logs on the system, by default, include the global request ID and
-This allows an administrator to track the API request processing as it
+the local request ID when available. This allows an administrator to
-transitions between all the different nova services.
+track the API request processing as it transitions between all the
+different nova services or between nova and other component services
+called by nova during that request.
+
+When nova services receive the local request IDs of other components in the
+``X-Openstack-Request-Id`` header, the local request IDs are output to logs
+along with the local request IDs of nova services.
+
+.. tip::
+
+   If a session client is used in client library, set ``DEBUG`` level to
+   the ``keystoneauth`` log level. If not, set ``DEBUG`` level to the client
+   library package. e.g. ``glanceclient``, ``cinderclient``.
+
+Sample log output is provided below.
+In this example, nova is using local request ID
+``req-034279a7-f2dd-40ff-9c93-75768fda494d``,
+while neutron is using local request ID
+``req-39b315da-e1eb-4ab5-a45b-3f2dbdaba787``::
+
+  Jun 19 09:16:34 devstack-master nova-compute[27857]: DEBUG keystoneauth.session [None req-034279a7-f2dd-40ff-9c93-75768fda494d admin admin] POST call to network for http://10.0.2.15:9696/v2.0/ports used request id req-39b315da-e1eb-4ab5-a45b-3f2dbdaba787 {{(pid=27857) request /usr/local/lib/python2.7/dist-packages/keystoneauth1/session.py:640}}
+
+.. note::
+
+   The local request IDs are useful to make 'call graphs'.
 
 Instance Faults
 ---------------

api-ref/source/index.rst

@@ -12,6 +12,7 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 
 .. include:: versions.inc
 .. include:: urls.inc
+.. include:: request-ids.inc
 .. include:: servers.inc
 .. include:: servers-actions.inc
 .. include:: servers-action-fixed-ip.inc

api-ref/source/parameters.yaml

@@ -26,14 +26,47 @@ tag_location:
   required: true
   type: string
   min_version: 2.26
-x-openstack-request-id:
+x-compute-request-id_resp:
   description: |
-    A unique ID for tracking the request. The request ID associated with the request
+    The local request ID, which is a unique ID generated automatically
-    appears in the log lines for that request. By default, the middleware configuration
+    for tracking each request to nova.
-    ensures that the request ID appears in the log files.
+    It is associated with the request and appears in the log lines
+    for that request.
+    By default, the middleware configuration
+    ensures that the local request ID appears in the log files.
+
+    .. note::
+
+       This header exists for backward compatibility.
   in: header
   required: true
   type: string
+x-openstack-request-id_req:
+  description: |
+    The global request ID, which is a unique common ID
+    for tracking each request in OpenStack components.
+    The format of the global request ID must be ``req-`` + UUID (UUID4).
+    If not in accordance with the format, it is ignored.
+    It is associated with the request and appears in the log lines
+    for that request.
+    By default, the middleware configuration ensures that
+    the global request ID appears in the log files.
+  in: header
+  required: false
+  type: string
+  min_version: 2.46
+x-openstack-request-id_resp:
+  description: |
+    The local request ID, which is a unique ID generated automatically
+    for tracking each request to nova.
+    It is associated with the request and appears in the log lines
+    for that request.
+    By default, the middleware configuration
+    ensures that the local request ID appears in the log files.
+  in: header
+  required: true
+  type: string
+  min_version: 2.46
 
 # variables in path
 agent_build_id:

api-ref/source/request-ids.inc

@@ -0,0 +1,24 @@
+.. -*- rst -*-
+
+===========
+Request IDs
+===========
+
+Users can specify the global request ID in the request header.
+Users can receive the local request ID in the response header.
+
+For more details about Request IDs, please reference: `Faults
+<https://developer.openstack.org/api-guide/compute/faults.html>`_
+
+**Request**
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: x-openstack-request-id_req
+
+**Response**
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Compute-Request-Id: x-compute-request-id_resp
+  - X-Openstack-Request-Id: x-openstack-request-id_resp