Add high level Muzzle docs

[pavolloffay]

Updates #536

[trask]

Our first muzzle doc!!! 🥳

I think muzzle is pervasive enough that this doc deserves to be under docs/contributing, with a new section/link from CONTRIBUTING.md

[anuraaga]

Nice, thanks!

[pavolloffay]

Is this correct? In this location there is MuzzleGradlePlugin but it more seems like ByteBuddy plugin as it implements bytebuddy plugin interface.

[pavolloffay]

cc) @tylerbenson

[tylerbenson]

The ByteBuddy plugin is what does the source graph traversal to find all the references for purposes of matching at run time as well as build time in the muzzle task.

[mateuszrzeszutek]

Yeah, it's a ByteBuddy plugin. The name's a bit misleading and it should be changed in the future -- though to be honest I don't have any great idea right now.

[pavolloffay]

We could rename it to MuzzleByteBuddyPlugin

[trask]

I created #1288 for renaming it

[iNikem]

Do you mean classLoaderMatcher?

[pavolloffay]

No I meant this

opentelemetry-java-instrumentation/instrumentation/google-http-client-1.19/src/main/java/io/opentelemetry/instrumentation/auto/googlehttpclient/GoogleHttpClientInstrumentation.java

Line 57 in 5d2ae07

return named("com.google.api.client.http.HttpRequest");

[tylerbenson]

This part of muzzle isn't really documented above. This plugin is responsible for downloading the range of libraries from Maven Central and verifying expected compatibility. If a new incompatible version is published, this is what will break the build.

[pavolloffay]

Is there also a task to run it explicitly?

[tylerbenson]

Yeah, this is what actually runs when you call the muzzle task.
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/master/.circleci/config.yml#L132

That can be called at the top level, or for an individual project.
As an optimization, these tasks are only added to gradle if muzzle is explicitly listed as a task, otherwise it slows down the config stage substantially.

[mateuszrzeszutek]

Muzzle actually collects symbols from advice classes -- values of the map returned by transformers() method. Muzzle by itself calls neither classLoaderMatcher() nor typeMatcher().

[pavolloffay]

@trask mentioned that muzzle first checks API referenced in typeMatcher() for optimization purposes

[trask]

another suggestion 😄

Suggested change

	and symbols in the application class loader. Before inspecting the class loader
	the Muzzle plugin checks symbols defined in `SomeInstrumentation.typeMatcher()`
	as a performance optimization. If the symbols do not match the instrumentation
	is not loaded.
	and symbols in the application class loader. If the symbols do not match the instrumentation is not loaded.
	Because the muzzle matcher is expensive, it is only performed after a match has been made by the `classLoaderMatcher()` and `typeMatcher()` matchers.

[pavolloffay]

+1. The match for classLoaderMatcher() and typeMatcher() is done by ByteBuddy right?

[mateuszrzeszutek]

Yeah, it's done a few steps before the MuzzleMatcher runs.

[pavolloffay]

@tylerbenson @iNikem @mateuszrzeszutek @trask @anuraaga thanks for the feedback. The PR is updated with your suggestions.

[trask]

@pavolloffay can you run spotlessApply, and merge master into your branch to get the build fix from #1280? then I think this is good to merge!

[trask]

Thanks again for this 💯