make metric rest docs more consumable #454
Conversation
chungg
commented
Oct 27, 2017
chungg
commented
- divide metric endpoint into crud sections
|
Tests SUCCESS for HEAD f27f55d
|
chungg
force-pushed
the
rest-split
branch
2 times, most recently
from
45b2955
to
7e29b67
Compare
|
Tests SUCCESS for HEAD 7e29b67
|
chungg
force-pushed
the
rest-split
branch
2 times, most recently
from
bbce50b
to
8374c47
Compare
|
Tests SUCCESS for HEAD 8374c47
|
doc/source/rest.j2
Outdated
| @@ -187,7 +222,7 @@ By default, new |measures| can only be processed if they have timestamps in the | |||
| future or part of the last aggregation period. The last aggregation period size | |||
| is based on the largest |granularity| defined in the |archive policy| | |||
| definition. To allow processing |measures| that are older than the period, the | |||
| `back_window` parameter can be used to set the number of coarsest periods to | |||
| `back_window` parameter can be used to set the number of historical periods to | |||
There was a problem hiding this comment.
Except you don't need the number of historical period.
We need to change that unit anyway. Logging a big.
There was a problem hiding this comment.
i'm not entirely sure what you mean by
We need to change that unit anyway. Logging a big.
you want me to change something in this patch?
There was a problem hiding this comment.
s/big/bug/
I opened #459 to track that. I don't think your change here makes sense.
That does not mean I think the original text is easy to understand. But this line change remove information.
So it makes from hard to impossible to understand the parameter. :)
chungg
force-pushed
the
rest-split
branch
2 times, most recently
from
fe7d4ba
to
a4ba5b9
Compare
| can try to create them as long as an |archive policy| rule matches: | ||
|
|
||
| {{ scenarios['post-measures-batch-named-create']['doc'] }} | ||
|
|
There was a problem hiding this comment.
Since that measures and aggregates have been distinguished now, maybe there should be a new section:
Aggregates
==========
There was a problem hiding this comment.
sorry, i don't understand your comment. i already have an aggregates section below?
There was a problem hiding this comment.
At some point before, the incoming data points and the processed(aggregated) ones are both called measures. But since one of my commit and the discussion with jd, the processed ones are now called aggregates. To explain in another way, now we have 'measure storage', 'aggregate storage', 'index storage', and the Aggregates I mentioned is the one in 'aggregate' storage.
To make the document more consistent, measures can only be pushed(POST), and the ones get read(GET) are actually aggregates. So I hope that the Read part here should belong to Aggregates section rather than Measures section.
BTW, I know that for the endpoint, measures is still used when getting aggregates, but I'm planning to deprecate that and create a new aggregates endpoint. #421
There was a problem hiding this comment.
so i understand the comment about terminology but i would probably have a discussion first about moving all GET actions to another endpoints. imo, it's a bad idea. people are use to CRUD concept and gnocch itself is already built on principle that everything is aggregated.
to me, aggregates endpoint is a custom-retrieval endpoint, not a simple read.
There was a problem hiding this comment.
To circle back on this discussion, I lean toward @Asu4ni about terminology because I encountered a lot of people confused about measures vs. aggregates and having it clearer is better. The changes proposed in #421 are orthogonal to this though – they could happen one day, but for now we should just focus on what exists. :)
That being said, that seems good enough for me now. The doc really talks about retrieving aggregates and not measures. :)
| The list of points returned is composed of tuples with (timestamp, | ||
| |granularity|, value) sorted by timestamp. The |granularity| is the |timespan| | ||
| covered by aggregation for this point. | ||
| Filter |
There was a problem hiding this comment.
I consider Filter should be the subsection of Read since it is used when reading aggregates
There was a problem hiding this comment.
yeah, i considered this. i really wanted filter to be top level but ok.
doc/source/rest.j2
Outdated
| @@ -119,24 +162,25 @@ timestamp: | |||
|
|
|||
| {{ scenarios['get-measures-from']['doc'] }} | |||
|
|
|||
| Aggregate | |||
There was a problem hiding this comment.
Maybe Aggregation is better. not to be confused with 'aggregates'. and the parameter in url uses aggregation as well
doc/source/rest.j2
Outdated
|
|
||
| .. _aggregates: | ||
|
|
||
| Aggregates: on the fly, measurements modification and aggregation | ||
| =================================================================== | ||
| Aggregates |
There was a problem hiding this comment.
on the fly should be retained. Otherwise, it'll be confused with the stored Aggregates above.
There was a problem hiding this comment.
how about dynamic aggregates? 'on the fly' is more slang i feel.
- divide metric section into crud tasks - divide measures section into crud tasks - divide archive-policy section into crud tasks - divide archive-policy-rule section into crud tasks - divide resources section into crud tasks - divide resource-type section into crud tasks - create common search section - create anchors for each functionality - better highlight aggregates API - remove redundant create-resource-with-new-metrics example
| can try to create them as long as an |archive policy| rule matches: | ||
|
|
||
| {{ scenarios['post-measures-batch-named-create']['doc'] }} | ||
|
|
There was a problem hiding this comment.
To circle back on this discussion, I lean toward @Asu4ni about terminology because I encountered a lot of people confused about measures vs. aggregates and having it clearer is better. The changes proposed in #421 are orthogonal to this though – they could happen one day, but for now we should just focus on what exists. :)
That being said, that seems good enough for me now. The doc really talks about retrieving aggregates and not measures. :)
|
Tests SUCCESS for HEAD 20bcfaa
|
|
Tests SUCCESS for HEAD eb37433
|
ghost
merged commit
|
Tests SUCCESS for HEAD eb37433
|
