htrace-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Colin McCabe <>
Subject htrace-core compatibility policy for htrace 4.x
Date Tue, 15 Sep 2015 00:13:36 GMT
Hi all,

In the recent 4.0 release, we changed the htrace-core API. The API
that programs use to create traces, annotations, etc. (aka the "Java
client API") went through some changes. This was necessary to clean up
some core architectural issues (such as the use of overly short 64 bit
IDs that will collide in a real-world deployment, or the overuse of

Since we want to make it easy for projects to integrate with HTrace, I
think we should have some compatibility rules for htrace-core for the

Specifically, I think that we should include only backwards-compatible
changes to the htrace-core API in HTrace 4.x So, for example, adding a
new function is OK. Deleting an existing function or altering it in an
incompatible way is not. It is OK to add a new function to a public
abstract base class (provided you also add a default implementation in
the base), but not to add a new function to a public interface, since
that would break compilation.

We should save incompatible changes for HTrace 5.x. In general, each
"major release" such as 4.x or 5.x should contain only compatible
changes to htrace-core. There should be no guarantees between 4.x and
5.x, or between any major releases-- this is the time to address
architectural debt that can't be resolved any other way. Major
releases should change the namespace of htrace-core classes so that
both a 4.x and a 5.x jar can reside on the same CLASSPATH, similar to
how we did with 3.x and 4.x. This is important because it will require
some time for downstream projects to upgrade from 4.x to 5.x, and in
the meantime we must avoid CLASSPATH conflict issues. There is no
requirement that tracing work when the major version of the client and
the span receivers are different. However, the programs themselves
should function.

Let's focus on just compatibility rules for htrace-core right now,
since that's where our integration issues are. The other subprojects
of htrace generally don't have the same integration issues. For
example, it is easy for an admin to standardize on a single version of
htrace-hbase or htrace-htraced across the entire cluster. They simply
install the jars for the version they want. It is not easy for that
same admin to standardize htrace-core, since they might have Hadoop
pulling in 4.1 and HBase pulling in 4.0. The different subprojects are
also at different levels of maturity. For example, htrace-flume is
still very immature, whereas htrace-htraced is starting to get more
mature. So I think the subprojects should come up with their own
compatibility policies rather than trying to be one-size-fits-all.

This policy should only apply to publicly visible symbols in
htrace-core, not to private or package-private symbols.  Test
functions should also not be covered, since they don't appear in the
final htrace-core jar.

I think having a compatibility policy for htrace-core will be very
nice for the users of our core APIs. Let me know what you think.


View raw message