10:42 a.m.
Hello,
Following the discussions here:
https://github.com/hawkular/hawkular-metrics/pull/584 I would like to bring
that up:
---------
The problem
I came to some limitation of the current REST API of hawkular-metrics when
adding features to the Grafana plugin. The main point here is that because
of an issue in Grafana (and/or golang) which you've certainly already
discussed before I join, we're limited in the use of @get endpoints when
metric ids are sent as query parameters. Although it has already been
solved in the current version of the grafana plugin, the problem reappears
when I'm trying to add features.
But beside those grafana centric considerations I think that it could be a
good occasion to bring more consistency to the REST API when querying data
for multiple metrics. There's several endpoints that, in my opinion, could
be harmonized.
-----
So what's missing?
(note, by "*" I mean "gauges", "counters",
"availability" or "string" ; not
"metrics". When I write "/raw", same applies for "/rate".)
- Some endpoints like "@get */stats" allow to query by list of ids or list
of tags, but there's no equivalent on "@get */raw", and the "@post
*/raw/query" doesn't handle tags
Note that I've already opened a JIRA ticket for query-by-tag
generalization: https://issues.jboss.org/browse/HWKMETRICS-466 . I can't
find any good reason why we could do it when querying stats, but not when
querying raw data.
- On the other hand, endpoints like "@post */raw/query", used for grafana,
has no equivalent for "stats". I would really like to have this one for
Grafana.
- List of metrics sometimes referred as "ids" (class QueryRequest),
sometimes "metrics" (all @get query params). We could add "metrics"
in
QueryRequest but keep/deprecate "ids" for compatibility?
-----
Suggestions:
1st Option: keep the API in the current form and bring all endpoints up to
the same level of functionality, that is:
* Create "@get */raw" that can take ids or tags
* Make "@post */raw/query" understand tags
* Create "@post */stats/query" that can take ids or tags
---
2d Option: change the current model to dissociate query by ids or by tags
Basically the idea is to provide different path if we want to query by ids
or by tags, to avoid having the assertion we currently have "must provide
either ids or tags but not both". I think it's cleaner to separate them. Of
course it has the downside of breaking (making deprecated) all query-by-tag
in the current API.
So, queries by ids would be the default one:
* "@get */raw"
* "@get */stats"
* "@post */raw/query"
* "@post */stats/query"
None of them would accept tags
And query by tag would be:
* "@get */raw/tags" (or "*/raw/tags/{tags}" ?)
* "@get */stats/tags"
* "@post */raw/tags/query"
* "@post */stats/tags/query"
None of them would accept ids
---
Other Option?
=> Personally, given the downside of the 2/ I would rather go for the 1st
one.
10:49 a.m.
New subject: metrics: REST API evolution when querying for multiple metrics
A side comment.
If we are going to suggest strong changes on API I think it could be a good moment to hold
them and install a strong versioning mechanism on the REST API across the components.
So, in that way, it could be for a user to maintain old APIs and new ones.
They way to do this can be discussed and get some consensus, but I guess we should be
aligned (inventory, metrics, alerting) here.
Lucas
----- Mensaje original -----
De: "Joel Takvorian" <jtakvori(a)redhat.com>
Para: "Discussions around Hawkular development"
<hawkular-dev(a)lists.jboss.org>
Enviados: Miércoles, 14 de Septiembre 2016 10:42:50
Asunto: [Hawkular-dev] metrics: REST API evolution when querying for multiple metrics
Hello,
Following the discussions here:
https://github.com/hawkular/hawkular-metrics/pull/584 I would like to bring
that up:
---------
The problem
I came to some limitation of the current REST API of hawkular-metrics when
adding features to the Grafana plugin. The main point here is that because
of an issue in Grafana (and/or golang) which you've certainly already
discussed before I join, we're limited in the use of @get endpoints when
metric ids are sent as query parameters. Although it has already been solved
in the current version of the grafana plugin, the problem reappears when I'm
trying to add features.
But beside those grafana centric considerations I think that it could be a
good occasion to bring more consistency to the REST API when querying data
for multiple metrics. There's several endpoints that, in my opinion, could
be harmonized.
-----
So what's missing?
(note, by "*" I mean "gauges", "counters",
"availability" or "string" ; not
"metrics". When I write "/raw", same applies for "/rate".)
- Some endpoints like "@get */stats" allow to query by list of ids or list of
tags, but there's no equivalent on "@get */raw", and the "@post
*/raw/query"
doesn't handle tags
Note that I've already opened a JIRA ticket for query-by-tag generalization:
https://issues.jboss.org/browse/HWKMETRICS-466 . I can't find any good
reason why we could do it when querying stats, but not when querying raw
data.
- On the other hand, endpoints like "@post */raw/query", used for grafana,
has no equivalent for "stats". I would really like to have this one for
Grafana.
- List of metrics sometimes referred as "ids" (class QueryRequest), sometimes
"metrics" (all @get query params). We could add "metrics" in
QueryRequest
but keep/deprecate "ids" for compatibility?
-----
Suggestions:
1st Option: keep the API in the current form and bring all endpoints up to
the same level of functionality, that is:
* Create "@get */raw" that can take ids or tags
* Make "@post */raw/query" understand tags
* Create "@post */stats/query" that can take ids or tags
---
2d Option: change the current model to dissociate query by ids or by tags
Basically the idea is to provide different path if we want to query by ids or
by tags, to avoid having the assertion we currently have "must provide
either ids or tags but not both". I think it's cleaner to separate them. Of
course it has the downside of breaking (making deprecated) all query-by-tag
in the current API.
So, queries by ids would be the default one:
* "@get */raw"
* "@get */stats"
* "@post */raw/query"
* "@post */stats/query"
None of them would accept tags
And query by tag would be:
* "@get */raw/tags" (or "*/raw/tags/{tags}" ?)
* "@get */stats/tags"
* "@post */raw/tags/query"
* "@post */stats/tags/query"
None of them would accept ids
---
Other Option?
=> Personally, given the downside of the 2/ I would rather go for the 1st
one.
_______________________________________________
hawkular-dev mailing list
hawkular-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
10:57 a.m.
On 09/14/2016 10:52 AM, Heiko W.Rupp wrote:
Rest has content negotiation for this purpose.
That implies that we'd make a special content type for the REST
endpoints. From what I could see so far, our content-type is mostly
application/json , so, do you mean we would have to change that to, say,
application/json+metrics-x.y ?
- Juca.
4:02 p.m.
On 14 Sep 2016, at 10:57, Juraci Paixão Kröhling wrote:
On 09/14/2016 10:52 AM, Heiko W.Rupp wrote:
> Rest has content negotiation for this purpose.
That implies that we'd make a special content type for the REST
endpoints. From what I could see so far, our content-type is mostly
application/json , so, do you mean we would have to change that to, say,
application/json+metrics-x.y ?
I was a bit sloppy in my first reply here, but it is a pet-thingy of
mine to point out what REST offers :)
Yes, clients would need to request such a special content-type
I think most of the time it would be something like
application/json+hawkular-metrics;vX where there is a
fallback to application/json+hawkular when there is no version
given. Old clients would just request application/json and get
what we server today.
The above only addresses the content submitted (Content-type header)
or received (Accepts header), but not changes in endpoints.
The later can be achieved by conditional redirects where the endpoint
looks at the content-type(s) and then sends a 302 to the new endpoint
accordingly.
New clients can directly use the new endpoint to circumvent the performance
hit of the redirect.
4:49 p.m.
I like option 1 as well. And thanks for the detailed explanation.
On Sep 14, 2016, at 4:42 AM, Joel Takvorian
<jtakvori(a)redhat.com> wrote:
Hello,
Following the discussions here: https://github.com/hawkular/hawkular-metrics/pull/584
<https://github.com/hawkular/hawkular-metrics/pull/584> I would like to bring that
up:
---------
The problem
I came to some limitation of the current REST API of hawkular-metrics when adding
features to the Grafana plugin. The main point here is that because of an issue in Grafana
(and/or golang) which you've certainly already discussed before I join, we're
limited in the use of @get endpoints when metric ids are sent as query parameters.
Although it has already been solved in the current version of the grafana plugin, the
problem reappears when I'm trying to add features.
But beside those grafana centric considerations I think that it could be a good occasion
to bring more consistency to the REST API when querying data for multiple metrics.
There's several endpoints that, in my opinion, could be harmonized.
-----
So what's missing?
(note, by "*" I mean "gauges", "counters",
"availability" or "string" ; not "metrics". When I write
"/raw", same applies for "/rate".)
- Some endpoints like "@get */stats" allow to query by list of ids or list of
tags, but there's no equivalent on "@get */raw", and the "@post
*/raw/query" doesn't handle tags
Note that I've already opened a JIRA ticket for query-by-tag generalization:
https://issues.jboss.org/browse/HWKMETRICS-466
<https://issues.jboss.org/browse/HWKMETRICS-466> . I can't find any good reason
why we could do it when querying stats, but not when querying raw data.
- On the other hand, endpoints like "@post */raw/query", used for grafana, has
no equivalent for "stats". I would really like to have this one for Grafana.
- List of metrics sometimes referred as "ids" (class QueryRequest), sometimes
"metrics" (all @get query params). We could add "metrics" in
QueryRequest but keep/deprecate "ids" for compatibility?
-----
Suggestions:
1st Option: keep the API in the current form and bring all endpoints up to the same level
of functionality, that is:
* Create "@get */raw" that can take ids or tags
* Make "@post */raw/query" understand tags
* Create "@post */stats/query" that can take ids or tags
---
2d Option: change the current model to dissociate query by ids or by tags
Basically the idea is to provide different path if we want to query by ids or by tags, to
avoid having the assertion we currently have "must provide either ids or tags but not
both". I think it's cleaner to separate them. Of course it has the downside of
breaking (making deprecated) all query-by-tag in the current API.
So, queries by ids would be the default one:
* "@get */raw"
* "@get */stats"
* "@post */raw/query"
* "@post */stats/query"
None of them would accept tags
And query by tag would be:
* "@get */raw/tags" (or "*/raw/tags/{tags}" ?)
* "@get */stats/tags"
* "@post */raw/tags/query"
* "@post */stats/tags/query"
None of them would accept ids
---
Other Option?
=> Personally, given the downside of the 2/ I would rather go for the 1st one.
_______________________________________________
hawkular-dev mailing list
hawkular-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
5:42 p.m.
On Wed, Sep 14, 2016 at 3:42 AM, Joel Takvorian <jtakvori(a)redhat.com> wrote:
1st Option: keep the API in the current form and bring all endpoints
up to
the same level of functionality, that is:
* Create "@get */raw" that can take ids or tags
* Make "@post */raw/query" understand tags
* Create "@post */stats/query" that can take ids or tags
Thanks for the detailed explanation.
Option 1 might be the only way to go. Adding end-points for tags would just
increase the API without any benefits. Since the output is identical, tags
or ids is just a query parameter. Also, we need to think about backwards
compatibility and expectations that we already set. We already have APIs
that support both, so we need to continue that path.
For making these changes, I would break your proposal into several PRs and
Jira tickets. A single massive PR will make the review process more
difficult.
Thank you,
Stefan
6:03 p.m.
Ok, I will create these JIRA tickets. Thank you all.
Just one thing about the versioning question raised by Lucas: if we go for
the first option (and it seems that's where we're going), there will be no
breaking change. Of course that doesn't mean the subject shouldn't be
discussed :)
On Wed, Sep 14, 2016 at 5:42 PM, Stefan Negrea <snegrea(a)redhat.com> wrote:
On Wed, Sep 14, 2016 at 3:42 AM, Joel Takvorian <jtakvori(a)redhat.com>
wrote:
> 1st Option: keep the API in the current form and bring all endpoints up
> to the same level of functionality, that is:
> * Create "@get */raw" that can take ids or tags
> * Make "@post */raw/query" understand tags
> * Create "@post */stats/query" that can take ids or tags
>
Thanks for the detailed explanation.
Option 1 might be the only way to go. Adding end-points for tags would
just increase the API without any benefits. Since the output is identical,
tags or ids is just a query parameter. Also, we need to think about
backwards compatibility and expectations that we already set. We already
have APIs that support both, so we need to continue that path.
For making these changes, I would break your proposal into several PRs and
Jira tickets. A single massive PR will make the review process more
difficult.
Thank you,
Stefan
_______________________________________________
hawkular-dev mailing list
hawkular-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
2788
days inactive
2788
days old
8 comments
6 participants
participants (6)
-
Heiko W.Rupp -
Joel Takvorian -
John Sanda -
Juraci Paixão Kröhling -
Lucas Ponce -
Stefan Negrea