Package names to use when adopting open source into specs

[donbo...@gmail.com]

We've been discussing using the Dropwizard metrics API in the Microprofile metrics spec as it is a mature API with lots of existing users.  If we do use that API, a question we need to answer is -- should the published API that is part of our spec use the package names from the open source package, or should we use a package naming scheme that is consistent with other MicroProfile specs?

Option A - use Dropwizard package names...

com.codahale.metrics.*

Option B - use Microprofile package names...

org.eclipse.microprofile.metrics.*

A case can be made for Option A as it would enable people with existing code instrumented using the Dropwizard metrics API to transition to a server with the Microprofile API without requiring code migration.

A case can be made for Option B as it would be good for consistency with other Microprofile code.

Please let me know your thoughts!

Regards,

Don

[Werner Keil]

Don,

What do you mean by "use Dropwizard package names"?

We cannot create another "spec" or API under the same name. I suppose you mean "implement Dropwizard" by that?

Implementing common interfaces like http://metrics.dropwizard.io/3.1.0/apidocs/com/codahale/metrics/Metric.html instead of trying to reinvent the wheel is not a bad thing to ask ourselves.

Spring keeps doing that almost more often than creating its own APIs, Dropwizard, Hystrix and many other examples are used there.

So using an established project like Dropwizard or (in other cases, though the "boat" has gone a bit further there already) Typesafe Config, Apache Commons Config, etc. would be quite possible. With some inspiration and contributions from various Apache projects you can actually take MicroProfile Config as a fairly compatible approach to the config challenge under org.eclipse.microprofile.config but with similar patterns and signatures as one or the other Apache project tackling the same problem.

As long as the license is compatible or a project already in Orbit, nothing would prevent a feature like Health or Monitoring from integrating Dropwizard with CDI instead of redefining APIs. 

Happy to hear thoughts by others and thanks Don for starting this discussion.

Regards,

Werner

[Ondrej Mihályi]

I would say both options have drawbacks, we just need to decide which drawbacks are smaller.

Option A would mean that all MicroProfile implementations would provide a specific library, which wouldn't be possible to exchange for another library or extend. Also, we would need to specify exactly which version of the library is used in MP to have consistence API.

Option B means that we have to replicate the API and it would need to be revised with every new version of the library. It would also mean that existing apps would have to be changed to use the new package names.

But it would also allow alternative implementations and some improvements to the existing API to fit it better into MicroProfile.

I'd rather choose option B, since option A has little advantage over just putting the library right into the application instead of into the MicroProfile implementation.

I think it's better to specify a thin API with Object arguments, which could be used to plug in any library, not just Dropwizard. In this case, something like registerMetric(Object metric)

If the server doesn't support it, it would simply ignore the metrics, or allow to add some plugin to handle DropWizard metrics.

Hence, I'm rather for describing how MP implementations work with some library provided by the application than to force every implementation to provide a specific library.

--Ondro

[Emily Jiang]

After looking into the bulk size of dropwizard packages and classes, I agree with Ondro and would also like to say Option B is better.

With option B, we have more control on what to expose and we can make the api neat. Judging from the wizard's package nams etc, it looks like there are no distinction between api /spi and internal classes. I think it is great for MP to properly define the boundary and improve the future maintenance. Hopefully, dropwizard can consume MP metrics apis in due course.

Emily

[donbo...@gmail.com]

@Werner, by "use Dropwizard package names" I meant -- if we want to have an API that mimics a snapshot of Dropwizard metrics (that we could update with future versions of the MP spec), we might want to make it easy for people with apps that already are instrumented with the Dropwizard metrics by keeping their package names.  The API could be exactly the API that is provided by Dropwizard-metrics -- or a subset that we decide is sufficient for our needs, avoiding any classes that are strictly present for implementation.

I think I see what you mean that we can't hijack their package name and call some derivative of their work com.codahale.metrics -- but, if we were keeping a true and exact subset of their API I don't think that would be a problem.

@Ondro, I agree with you about Option A -- effectively anyone implementing the spec would just take the appropriate version of Dropwizard-metrics and include it in their jars.  I could see that version becoming the MP "sample implementation" for metrics to keep us from being dependent on Dropwizard to supply that.  I do think though that an implementor of the API could choose to change the methods to their needs, based on that sample implementation, if needed.

On Option B, you said... "I'd rather choose option B, since option A has little advantage over just putting the library right into the application instead of into the MicroProfile implementation".  The value IMO is to standardize Dropwizard-metrics as the API across all vendor implementations of MicroProfile.  That would cover the need for a standard for metrics with something that's been widely used.  It would ensure that there is a consistent metrics implementation that could be used for any MicroProfile-dependent app, without having to worry about differences between server implementations.

@Emily, we're looking through the Dropwizard-metrics packages to separate the API parts from the implementation parts.  For example, I'm not sure we'd need all of the different Reporters given we're just planning to mandate one HTTP API "reporter" in the spec.  We also wouldn't need all of the pre-instrumented things like Jersey, Jetty, log4J, etc -- the MP spec could limit itself to the core parts of the dropwizard-metrics API, and leave it open to vendor implementations to decide if they want to include anything more.

Don

[Werner Keil]

Don,

Thanks for the clarification. Quite frankly, I would not throw as many elements into a single top level package as Dropwizard Metrics:

http://metrics.dropwizard.io/3.1.0/apidocs/com/codahale/metrics/package-frame.html

Parfait https://github.com/performancecopilot/parfait 

or even the ill-fated (because just retired into attic from Apache Incubator)
Sirona https://github.com/apache/sirona/tree/trunk/api/src/main/java/org/apache/sirona

IMO have a much better package layout. E.g. separating JMX related aspects into a separate package or even module instead of putting everything into a single package.

Werner

[Emily Jiang]

Don,

For refactoring Dropwizard. is that community willing to do so? How much time/effort is involved for such a refactoring? You can start the discussion in DropWizard community to see what they think. If it unlikely happens in a short timeframe, it is best for MicroProfile to define the APIs.

Emily

[donbo...@gmail.com]

@Werner, I see what you're saying about the dropwizard metrics top level package (and appreciate your relevant counter-examples!)

I'll try to start a conversation with dropwizard about whether they would be up for refactoring some of this.  In particular, I could envision all of the types related to Reporters moving to their own sub-package, which could make things a bit cleaner without making the API seem too fragmented.

@Emily - good questions - I'll see what they say.  I agree with you on needing to either enlist their quick cooperation or have our own API.  The former would be great as it would make it much easier to consume future DW metrics drivers, but we don't want to delay if it doesn't look promising.

[Kevin Sutter]

Emily,
We created a DropWizard Issue asking that exact question...  I didn't have a specific contact on the DropWizard team, so I went the generic route of creating an Issue and asking for a discussion:
https://github.com/dropwizard/metrics/issues/1161

-- Kevin