Document muzzle

[iNikem]

The whole story around muzzle is extremely confusing, but one encounters it almost everywhere in this repo. It has 0 documentation and huge number of moving parts:

• Muzzle plugin in buildSrc folder
• Two muzzle plugins in auto-tooling module
• Muzzle task and its configuration
• Muzzle task's logs that one has to read and understand when muzzle task fails
• What does it mean "instrumentation was muzzled"??
• What is muzzle's relationship with different class loaders? I sense there is one, but I am not sure.
• What is MuzzleMatcher and how is it connected to muzzle task and muzzle plugins?
• What does the javadoc on io.opentelemetry.auto.tooling.Instrumenter.Default#getInstrumentationMuzzle actually mean? And why do we generate our own code with "compile-time bytecode transformations"?
• Muzzle plugin does some extremely convoluted things with Gradle. Such as arbitrarily reaching to other projects. This makes it impossible to use Gradle's configuration on demand. That could significantly increase build time in some cases.
• Why MuzzleVisitor uses ASM and not ByteBuddy?

[anuraaga]

+100 - getting a presentation from @trask helped me a lot but indeed there's so much muzzle around I do get re-lost.

Want to give credit for the help in working around the issues from reviewers but it's naturally not as scalable as us having a proper guide to muzzle. Based on the name, I assume it's originally datadog and I hope they can help us with documenting this to improve the contributor experience.

[trask]

I will take a first stab at this, and call in @tylerbenson for backup as needed

[trask]

See #654 for another muzzle thing to investigate and doc

[trask]

Another interesting thing to doc: #696

[trask]

Another good thing to doc: #701 (comment)

[trask]

And another: #694 (comment)

[trask]

Another quirk: updates to muzzle java sources in auto-tooling don't seem to take effect when running

./gradlew :instrumentation:<module>:muzzle

without adding --rerun-tasks

[anuraaga]

@trask #1121 (comment) :)

[trask]

@trask #1121 (comment) :)

e.g. recommend instrumentation authors not to use lambdas

[trask]

More

• Doc assertInverse
• Does muzzle fail if an Instrumentation doesn't match anything? E.g. seems it doesn't fail if it doesn't match, see running muzzle against elasticsearch 7 doesn't fail Elasticsearch6TransportClientInstrumentation even though Action class doesn't exist anymore

[trask]

Doc printReferences task, e.g.

./gradlew :instrumentation:google-http-client-1.19:printReferences

[trask]

Youtube clip from SIG meeting describing muzzle, maybe worth referencing(?)

https://www.youtube.com/watch?v=2iL91CwfxCo&feature=youtu.be&t=2682

[mateuszrzeszutek]

I've compiled a list of questions that have not been answered yet in our muzzle docs:

• Muzzle task's logs that one has to read and understand when muzzle task fails
  • Should we work on the readability of those logs? They seemed okay to me, but maybe we can improve them somehow.
• Muzzle plugin does some extremely convoluted things with Gradle. Such as arbitrarily reaching to other projects. This makes it impossible to use Gradle's configuration on demand. That could significantly increase build time in some cases.
• Why MuzzleVisitor uses ASM and not ByteBuddy?
• do not use static fields in InstrumentationModule/TypeInstrumentation (and probably advice classes too)
• Does muzzle fail if an Instrumentation doesn't match anything? E.g. seems it doesn't fail if it doesn't match, see running muzzle against elasticsearch 7 doesn't fail Elasticsearch6TransportClientInstrumentation even though Action class doesn't exist anymore
  • I assume that this concerns the typeMatcher()/transformers() methods, right?

I've skipped questions that no longer apply or will be solved by #1714 or that have been answered. Is there anything else that we should add here, any other questions?
I probably have a different idea about what's obvious and does not need explaining due to working with muzzle a lot, so don't hesitate to ask even obvious things, I'll add them all to docs.