You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2020/01/03 17:33:15 UTC
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request
#4127: Rewrite GET stats_summary from Perl to Golang
ocket8888 commented on a change in pull request #4127: Rewrite GET stats_summary from Perl to Golang
URL: https://github.com/apache/trafficcontrol/pull/4127#discussion_r362893961
##########
File path: docs/source/api/stats_summary.rst
##########
@@ -0,0 +1,178 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-stats-summary:
+
+*****************
+``stats_summary``
+*****************
+
+``GET``
+=======
+Either retrieve a list of summary stats or the timestamp of the latest recorded stats summary.
+
+What is returned is driven by the query parameter ``lastSummaryDate``.
+
+If the parameter is set it will return an object with the latest timestamp, else an array of summary stats will be returned.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array or Object
+
+Request Structure
+-----------------
+
+Summary Stats
+"""""""""""""
+
+.. table:: Request Query Parameters
+
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=====================+==========+=======================================================================================================+
+ | deliveryServiceName | no | Return only summary stats that were reported for :term:`Delivery Service` with the given display name |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | cdnName | no | Return only summary stats that were reported for CDN with the given name |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | statName | no | Return only summary stats that were reported for given stat name |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | orderby | no | Choose the ordering of the results - can only be one of deliveryServiceName, statName or cdnName |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or |
+ | | | descending ("desc") |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are |
+ | | | ``limit`` long and the first page is 1. If ``offset`` was defined, this query parameter has no |
+ | | | effect. ``limit`` must be defined to make use of ``page``. |
+ +---------------------+----------+-------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/stats_summary HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Last Updated Summary Stat
+""""""""""""""""""""""""""
+
+.. table:: Request Query Parameters
+
+ +-----------------+----------+---------------------------------------------------+
+ | Name | Required | Description |
+ +=================+==========+===================================================+
+ | statName | no | Get lastest updated date for the given stat |
+ +-----------------+----------+---------------------------------------------------+
+ | lastSummaryDate | yes | Tells route to get only lastest updated timestamp |
+ +-----------------+----------+---------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/stats_summary?lastSummaryDate=true HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+
+Summary Stats
+"""""""""""""
+
+:cdnName: The CDN name for which the summary stat was taken for
+:deliveryServiceName: The :term:`Delivery Service` display name for which the summary stat was taken for
+
+ .. note:: If the ``deliveryServiceName`` is equal to ``all`` it represents summary_stats across all delivery services within the given CDN
+
+:statName: Stat name summary stat represents
+:statValue: Summary stat value
+:summaryTime: Timestamp of summary, in an ISO-like format
+:statDate: Date stat was taken, in :rfc:`3339` format
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
+ Whole-Content-Sha512: dHNip9kpTGGS1w39/fWcFehNktgmXZus8XaufnmDpv0PyG/3fK/KfoCO3ZOj9V74/CCffps7doEygWeL/xRtKA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Mon, 10 Dec 2018 20:56:59 GMT
+ Content-Length: 150
+
+ { "response": [
+ {
+ "cdnName": "CDN-in-a-Box",
+ "deliveryServiceName": "all",
+ "statName": "daily_maxgbps",
+ "statValue": 5,
+ "summaryTime": "2019-11-19 00:04:06+00",
+ "statDate": "2019-11-19
Review comment:
You're missing a closing quote here, which is breaking syntax highlighting - because lexical analysis is failing.
But also this code block is mixing indentation with alignment (i.e. spaces and tabs). It's fine to indent the actual contained code with spaces, but for consistency the content of a `.. code-block` (or any other directive) should be tab-indented. Because of that it's also best for the code therein contained to be indented using tabs, but that's up to you.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services