[Hawkular-dev] Hawkular Metrics - /data enpoint

Mon Apr 4 18:18:25 EDT 2016

On Mon, Apr 4, 2016 at 4:03 PM, John Sanda <jsanda at redhat.com> wrote:

> Making sure we don’t break clients is the most important aspect of this;
> however, there are some other questions I want to throw out. Today we only
> support clients adding raw data points. What if in the future though we add
> support for complex types like histograms and allow clients to directly
> store them. Would clients post that data to /raw, /stats, or something else?
>
> Today we compute aggregated metrics at query time. We are going to add
> support for pre-computed aggregate metrics that are persisted. Do we have
> different endpoints for each? I haven’t thought about it too much yet, but
> I don’t separate endpoints is the way to go.
>

In the actual JIRA ticket there were 3 ideas floated around: separate
endpoint, or /raw endpoint (because that is not bucketed data), or /stats
endpoint (because is bucketed, just server side). And I think those are all
the possible variations. One thing that I do not like about '/data' and
pre-computed aggregates, if we do not split that method will serve 3 or 4
different formats depending on query params. That is way too complicated
for both us and the users.

>
> With HWKMETRICS-373, we are introducing support for tag based bucketing as
> opposed to the date range bucketing already have. There are some minor
> differences in the data structures returned in the response, namely a map
> is returned instead of an array. Should we have a different endpoints for
> tag based buckets vs date range buckets?
>

I like the idea of just raw and stats. I associate /raw with raw data
stored by Hawkular Metrics, and that includes pre-computed aggregates too,
and /stats with some sort of statistical computation done do the raw data
before returned to the user. Based on this, the tag querying would fall
under '/stats' if data is bucketed and would fall under '/raw' if you query
for just raw data that is tagged.

>
> We currently have one increasingly complex method to handle queries for
> raw data, various permutations of date range buckets, and eventually tag
> based buckets once my changes for HWKMETRICS-373 are merged. These changes
> definitely will simplify things on the server side, but do they simply or
> otherwise improve things for clients? I am a little concerned that we might
> be letting our implementation bleed into the API a little too much. For
> example, we segment our data in our schema design by metric type. Do we
> necessarily need to do that everywhere in the API?
>

I like to think about the API in terms of code integration and not
necessarily from the perspective of an actual end-user. To me the end-users
will never see our interface, they just see some pretty UI. From an
integration perspective serving multiple data formats over a single
endpoint is not easy to accommodate on most frameworks. But we need to
balance exploding the API into too many end-points. The explanation I wrote
about raw and stats will help us keep the number of end-points under
control.

One of the reasons the JIRA ticket was opened is Angular and their design
of the REST framework. Serving multiple data formats over the same endpoint
is a big no-no. And there is also a special limitation that you need to
decided ahead of time if and end-point serves arrays or not; errors occur
if you expect array but get single object and vice-versa. With this in
mind, I think we need to focus on how consumable is our interface from a
machine code perspective.

And here is one more perspective to think on this. The current API served
us for the past year and a half. Are the changes proposed here going to go
good for the next year and half? I think based on the roadmap that we
published, the planned features, and the current code, these changes are a
step in a good direction.

>
> On Apr 4, 2016, at 10:21 AM, Matt Wringe <mwringe at redhat.com> wrote:
>
> ----- Original Message -----
>
> From: "Heiko W.Rupp" <hrupp at redhat.com>
> To: "Discussions around Hawkular development" <
> hawkular-dev at lists.jboss.org>
> Sent: Monday, April 4, 2016 4:56:15 AM
> Subject: Re: [Hawkular-dev] Hawkular Metrics - /data enpoint
>
> On 2 Apr 2016, at 0:24, Stefan Negrea wrote:
>
> The plan is to deprecate existing '*/data' endpoints in the upcoming
> release (0.15.0) and remove them in the release after that (0.16.0). That
> gives enough time (roughly 2 months) for all existing projects to migrate
> to the newer API. Does anybody see any problem with this timeline?
>
>
> Yes.
> There are users out there that use the old api in production.
> They may not even be aware that there is a new one.
>
> If they deploy the new hawkular-metrics (or someone does
> for them), their apps will break and they may not even know
> why.
>
>
> +1
>
> I think we need to make sure that we don't break the existing API for
> current users who are already using it. There will most likely be a bunch
> of complaints if we update this in OpenShift and then everyone's setup
> stops working.
>
> REST allows for content negotiation. So we should keep the
> old endpoint, deprecate them (and perhaps even spit regular
> warnings in the logs) and on top add the new endpoints
> that you suggested but with a new content type
> like "application/json+hawkular-v2".
>
>
> If we are going to introduce a new version for the REST API, it might make
> sense to release Hawkular Metrics with a new major version as well. But
> major versions can be tricky depending on how the project handles them.
> Some projects will have the same major versions for years, others will
> update the major version almost monthly (eg kernel version versus browser
> version)
>
> In fact if we keen old and new, that new content type
> is not exactly needed if the data format exchanged does not
> change.
>
> Btw: I doubt that GET ../data and POST ../data is confusing anyone
> and in Jax-Rs you can have those on two different methods anyway.
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
>
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20160404/9e88eef5/attachment.html 