ocket8888 commented on a change in pull request #3758: Rewrote
deliveryservice_stats to Go
URL: https://github.com/apache/trafficcontrol/pull/3758#discussion_r330308059
##########
File path: docs/source/api/deliveryservice_stats.rst
##########
@@ -37,140 +33,184 @@ Request Structure
-----------------
.. table:: Request Query Parameters
-
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======================+==========+====================================================================================================================+
- | deliveryServiceName | yes | The name of the :term:`Delivery
Service` for which statistics will be aggregated
|
-
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
- | metricType | yes | The metric type being reported -
one of:
|
- | | |
|
- | | | kbps
|
- | | | The total traffic rate in
kilobytes per second served by the :term:`Delivery Service`
|
- | | | out_bytes
|
- | | | The total number of bytes sent
out to clients through the :term:`Delivery Service`
|
- | | | status_4xx
|
- | | | The amount of requests that were
serviced with 400-499 HTTP status codes
|
- | | | status_5xx
|
- | | | The amount of requests that were
serviced with 500-599 HTTP status codes
|
- | | | tps_total
|
- | | | The total traffic rate in
transactions per second served by the :term:`Delivery Service`
|
- | | | tps_2xx
|
- | | | The total traffic rate in
transactions per second serviced with 200-299 HTTP status codes
|
- | | | tps_3xx
|
- | | | The total traffic rate in
transactions per second serviced with 300-399 HTTP status codes
|
- | | | tps_4xx
|
- | | | The total traffic rate in
transactions per second serviced with 400-499 HTTP status codes
|
- | | | tps_5xx
|
- | | | The total traffic rate in
transactions per second serviced with 500-599 HTTP status codes
|
- | | |
|
-
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
- | startDate | yes | The date and time from which
statistics shall be aggregated in ISO8601 format, e.g.
``2018-08-11T12:30:00-07:00`` |
-
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
- | endDate | yes | The date and time until which
statistics shall be aggregated in ISO8601 format, e.g.
``2018-08-12T12:30:00-07:00`` |
-
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+=====================+===================+===========================================================================================================================================================================================+
+ | deliveryService | yes\ [#ds-param]_ | Either the :ref:`ds-xmlid`
of a :term:`Delivery Service` for which statistics will be aggregated or the
integral, unique identifier of said :term:`Delivery Service`
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | deliveryServiceName | yes\ [#ds-param]_ | The :ref:`ds-xmlid` of the
:term:`Delivery Service` for which statistics will be aggregated
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | endDate | yes | The date and time until
which statistics shall be aggregated in :rfc:`3339` format (with or without
sub-second precision), the number of nanoseconds since the Unix
|
+ | | | Epoch, or in the same,
proprietary format as the ``lastUpdated`` fields prevalent throughout the
Traffic Ops API
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | exclude | no | Either "series" to omit the
data series from the result, or "summary" to omit the summary data from the
result - directly corresponds to fields in the
|
+ | | | `Response Structure`_
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | interval | no | Specifies the interval
within which data will be "bucketed"; e.g. when requesting data from
2019-07-25T00:00:00Z to 2019-07-25T23:59:59Z with an interval of "1m",
|
+ | | | the resulting data series
(assuming it is not excluded) should contain
|
+ | | |
:math:`24\frac{\mathrm{hours}}{\mathrm{day}}\times60\frac{\mathrm{minutes}}{\mathrm{hour}}\times1\mathrm{day}\times1\frac{\mathrm{minute}}{\mathrm{data
point}}=1440\mathrm{data\;points}`|
+ | | | The allowed values for this
parameter are:
|
+ | | |
|
+ | | | 1m
|
+ | | | Groups data in intervals
of one minute
|
+ | | | 5m
|
+ | | | Groups data in intervals
of five minutes
|
+ | | | 1h
|
+ | | | Groups data in intervals
of one hour
|
+ | | | 6h
|
+ | | | Groups data in intervals
of six hours
|
+ | | | 1d
|
+ | | | Groups data in intervals
of one day
|
+ | | | 1w
|
+ | | | Groups data in intervals
of one week
|
+ | | | 4w
|
+ | | | Groups data in intervals
of one month (literally 4 weeks or 28 days)
|
+ | | |
|
+ | | | If this parameter is not
provided, a default of "1m" is used.
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | limit | no | A natural number indicating
the maximum amount of data points should be returned in the ``series`` object
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | metricType | yes | The metric type being
reported - one of:
|
+ | | |
|
+ | | | kbps
|
+ | | | The total traffic rate in
kilobytes per second served by the :term:`Delivery Service`
|
+ | | | out_bytes
|
+ | | | The total number of bytes
sent out to clients through the :term:`Delivery Service`
|
+ | | | status_4xx
|
+ | | | The amount of requests
that were serviced with 400-499 HTTP status codes
|
+ | | | status_5xx
|
+ | | | The amount of requests
that were serviced with 500-599 HTTP status codes
|
+ | | | tps_total
|
+ | | | The total traffic rate in
transactions per second served by the :term:`Delivery Service`
|
+ | | | tps_2xx
|
+ | | | The total traffic rate in
transactions per second serviced with 200-299 HTTP status codes
|
+ | | | tps_3xx
|
+ | | | The total traffic rate in
transactions per second serviced with 300-399 HTTP status codes
|
+ | | | tps_4xx
|
+ | | | The total traffic rate in
transactions per second serviced with 400-499 HTTP status codes
|
+ | | | tps_5xx
|
+ | | | The total traffic rate in
transactions per second serviced with 500-599 HTTP status codes
|
+ | | |
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | offset | no | A natural number of data
points to drop from the beginning of the returned data set
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | orderby | no | Though one struggles to
imagine why, this can be used to specify "time" to sort data points by their
"time" (which is the default behavior), or "value" to sort them by their
"value" |
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | startDate | yes | The date and time from
which statistics shall be aggregated in :rfc:`3339` format (with or without
sub-second precision), the number of nanoseconds since the Unix
|
+ | | | Epoch, or in the same,
proprietary format as the ``lastUpdated`` fields prevalent throughout the
Traffic Ops API
|
+
+---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _deliveryservice_stats-get-request-example:
+.. code-block:: http
+ :caption: Request Example
+
+ GET
/api/1.3/deliveryservice_stats?deliveryServiceName=demo1&startDate=2019-07-22T17:55:00Z&endDate=2019-07-22T17:56:00.000Z&metricType=tps_total
HTTP/1.1
+ User-Agent: python-requests/2.20.1
+ Accept-Encoding: gzip, deflate
+ Accept: application/json;timestamp=unix,
application/json;timestamp=rfc;q=0.9, application/json;q=0.8, */*;q=0.7
+ Connection: keep-alive
+ Cookie: mojolicious=...
+
+Content Format
+""""""""""""""
+It's important to note in :ref:`deliveryservice_stats-get-request-example` the
use of a complex "Accept" header. This endpoint accepts two special media types
in the "Accept" header that instruct it on how to format the timestamps
associated with the returned data. Specifically, Traffic Ops will recognize the
special, optional, non-standard parameter of :mimetype:`application/json`:
``timestamp``. The values of this parameter are restricted to one of
+
+rfc
+ Returned timestamps will be formatted according to :rfc:`3339` (no
sub-second precision).
+unix
+ Returned timestamps will be formatted as the number of nanoseconds
since the Unix Epoch (midnight on January 1\ :sup:`st` 1970 UTC).
+
+ .. impl-detail:: The endpoint passes back nanoseconds, specifically,
because that is the form used both by InfluxDB, which is used to store the data
being served, and Go's standard library. Clients may need to convert the value
to match their own standard libraries - e.g. the :js:class:`Date` class in
Javascript expects milliseconds.
+
+The default behavior - when only e.g. :mimetype:`application/json` or
:mimetype:`*/*` is given - is to use :rfc:`3339` formatting. It will, however,
respect quality parameters. It is suggested that clients request timestamps
they can handle specifically, rather than relying on this default behavior, as
it **is subject to change** and is in fact **expected to invert in the next
major release** as string-based time formats become deprecated.
+
+.. seealso:: For more information on the "Accept" HTTP header, consult `its
dedicated page on MDN
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept>`_.
Response Structure
------------------
-.. table:: Response Keys
-
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- | Parameter | Type | Description
|
-
+============================+===============+=========================================================================================+
- |``source`` | string | The source of the data
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``summary`` | hash | Summary data
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>totalBytes`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>count`` | int |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>min`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>max`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>fifthPercentile`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>ninetyEighthPercentile`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>ninetyFifthPercentile`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>average`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>totalTransactions`` | int |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``series`` | hash | Series data
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>count`` | int |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>columns`` | array |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>name`` | string |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>values`` | array |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>>time`` | string |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
- |``>>value`` | float |
|
-
+----------------------------+---------------+-----------------------------------------------------------------------------------------+
-
-.. code-block:: json
+:series: An object containing the actual data series and information necessary
for working with it.
+
+ :columns: This is an array of names of the columns of the data
contained in the "values" array - should always be ``["time", "value"]``
Review comment:
Yeah, that's how it used to be in my version too. I decided to make it
`value` instead, since `sum_count` is both puzzling to the user, as well as an
exposure of implementation detail.
At the time it didn't occur to me that that'd be a breaking API change. But
it would be...
----------------------------------------------------------------
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:
[email protected]
With regards,
Apache Git Services
