From 9fbd7861dd5c8b49b3a9fe96c03d45234a55a6b6 Mon Sep 17 00:00:00 2001 From: Takashi NATSUME Date: Fri, 16 Jun 2017 11:38:55 +0900 Subject: [PATCH] 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 | 83 +++++++++++++++++++++++++++++++--- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 41 +++++++++++++++-- api-ref/source/request-ids.inc | 24 ++++++++++ 4 files changed, 138 insertions(+), 11 deletions(-) create mode 100644 api-ref/source/request-ids.inc diff --git a/api-guide/source/faults.rst b/api-guide/source/faults.rst index e0eace8fda09..c75327b1638d 100644 --- a/api-guide/source/faults.rst +++ b/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. -This is returned in a response header. -Here is an example response header: +There are two types of request ID. -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. -This allows an administrator to track the API request processing as it -transitions between all the different nova services. +All logs on the system, by default, include the global request ID and +the local request ID when available. This allows an administrator to +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 --------------- diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index e573c4b646dd..3e651881b2b5 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -12,6 +12,7 @@ the `API guide `_. .. include:: versions.inc .. include:: urls.inc +.. include:: request-ids.inc .. include:: servers.inc .. include:: servers-actions.inc .. include:: servers-action-fixed-ip.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 3312a5660801..be3eb06ef754 100644 --- a/api-ref/source/parameters.yaml +++ b/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 - appears in the log lines for that request. By default, the middleware configuration - ensures that the request ID appears in the log files. + 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. + + .. 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: diff --git a/api-ref/source/request-ids.inc b/api-ref/source/request-ids.inc new file mode 100644 index 000000000000..76c0efafedb6 --- /dev/null +++ b/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 +`_ + +**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