Update Intellij setup docs
MODIFY
docs/contributing/debugging.md
docs/contributing/debugging.md
-### Debugging
+## Debugging
Debugging java agent can be a challenging task since some instrumentation
code is directly inlined into target classes.
-#### Advice methods
+### Advice methods
Breakpoints do not work in advice methods, because their code is directly inlined
by ByteBuddy into the target class. It is good to keep these methods as small as possible.
@@ -21,13 +21,13 @@ System.out.println()
Thread.dumpStack()
```
-#### Agent initialization code
+### Agent initialization code
If you want to debug agent initialization code (e.g. `OpenTelemetryAgent`, `AgentInitializer`,
`AgentInstaller`, `OpenTelemetryInstaller`, etc.) then it's important to specify the `-agentlib:` JVM arg
before the `-javaagent:` JVM arg and use `suspend=y` (see full example below).
-#### Enabling debugging
+### Enabling debugging
The following example shows remote debugger configuration. The breakpoints
should work in any code except ByteBuddy advice methods.

MODIFY
docs/contributing/intellij-setup.md
docs/contributing/intellij-setup.md
-### IntelliJ setup
+# IntelliJ setup
**NB!** Please ensure that Intellij uses the same java installation as you do for building this
project from command line. This ensures that Gradle task avoidance and build cache work properly and
@@ -6,23 +6,23 @@ can greatly reduce build time.
Suggested plugins and settings:
-* Editor > Code Style > Java/Groovy > Imports
- ![code style](https://user-images.githubusercontent.com/5099946/132923944-5737a731-351a-46a3-8fc4-5fe64e5a630c.png)
- * Class count to use import with '*': `9999` (some number sufficiently large that is unlikely to
- matter)
- * Names count to use static import with '*': `9999`
- * Default Import Layout should be used:
- ![import layout](https://user-images.githubusercontent.com/5099946/132924187-daf2df16-3e46-48db-9cf6-348252268a86.png)
+## [google-java-format](https://plugins.jetbrains.com/plugin/8527-google-java-format)
+
+Installation:
-* [Google Java Format](https://plugins.jetbrains.com/plugin/8527-google-java-format) plugin is
- suggested to be installed
![google format](https://user-images.githubusercontent.com/5099946/131758519-14d27c17-5fc2-4447-84b0-dbe7a7329022.png)
- Enable google-java-format
+
+Configuration:
+
![enable google format](https://user-images.githubusercontent.com/5099946/131759832-36437aa0-a5f7-42c0-9425-8c5b45c16765.png)
-* Install [Save Actions](https://plugins.jetbrains.com/plugin/7642-save-actions)
+## [Save Actions](https://plugins.jetbrains.com/plugin/7642-save-actions)
+
+Installation:
![save action](https://user-images.githubusercontent.com/5099946/131758940-7a1820db-3cf4-4e30-b346-c45c1ff4646e.png)
- Configure Save Actions as follows:
+
+Configuration:
+
![Recommended Settings](save-actions.png)

MODIFY
docs/contributing/javaagent-jar-components.md
docs/contributing/javaagent-jar-components.md
-### Understanding the javaagent components
+# Understanding the javaagent components
The javaagent jar can logically be divided into 3 parts:
@@ -6,9 +6,9 @@ The javaagent jar can logically be divided into 3 parts:
* Modules that live in the bootstrap class loader
* Modules that live in the agent class loader
-### Modules that live in the system class loader
+## Modules that live in the system class loader
-#### `javaagent` module
+### `javaagent` module
This module consists of single class
`io.opentelemetry.javaagent.OpenTelemetryAgent` which implements [Java
@@ -20,14 +20,14 @@ classloader and immediately delegate to
`io.opentelemetry.javaagent.bootstrap.AgentInitializer` (now in the bootstrap class loader)
class from there.
-### Modules that live in the bootstrap class loader
+## Modules that live in the bootstrap class loader
-#### `javaagent-bootstrap` module
+### `javaagent-bootstrap` module
`io.opentelemetry.javaagent.bootstrap.AgentInitializer` and a few other classes that live in the bootstrap class
loader but are not used directly by auto-instrumentation
-#### `instrumentation-api` and `javaagent-instrumentation-api` modules
+### `instrumentation-api` and `javaagent-instrumentation-api` modules
These modules contain support classes for actual instrumentations to be loaded
later and separately. These classes should be available from all possible
@@ -40,9 +40,9 @@ the actual application.
`instrumentation-api` contains classes that are needed for both library and auto-instrumentation,
while `javaagent-instrumentation-api` contains classes that are only needed for auto-instrumentation.
-### Modules that live in the agent class loader
+## Modules that live in the agent class loader
-#### `javaagent-tooling`, `javaagent-extension-api` modules and `instrumentation` submodules
+### `javaagent-tooling`, `javaagent-extension-api` modules and `instrumentation` submodules
Contains everything necessary to make instrumentation machinery work,
including integration with [ByteBuddy](https://bytebuddy.net/) and actual
@@ -69,7 +69,7 @@ auto-instrumentation agent's classes are totally isolated from application
classes, and an instrumented class from arbitrary classloader in JVM can
still access helper classes from bootstrap classloader.
-#### Agent jar structure
+### Agent jar structure
If you now look inside
`javaagent/build/libs/opentelemetry-javaagent-<version>-all.jar`, you will see the

MODIFY
docs/contributing/javaagent-test-infra.md
docs/contributing/javaagent-test-infra.md
-### Understanding the javaagent instrumentation testing components
+# Understanding the javaagent instrumentation testing components
Javaagent instrumentation tests are run using a fully shaded `-javaagent` in order to perform
the same bytecode instrumentation as when the agent is run against a normal app.
There are a few key components that make this possible, described below.
-### gradle/instrumentation.gradle
+## gradle/instrumentation.gradle
* shades the instrumentation
* adds jvm args to the test configuration
@@ -15,7 +15,7 @@ There are a few key components that make this possible, described below.
The `otel.javaagent.experimental.initializer.jar` property is used to load the shaded instrumentation jar into the
`AgentClassLoader`, so that the javaagent jar doesn't need to be re-built each time.
-### :testing:agent-exporter
+## :testing:agent-exporter
This contains the span and metric exporters that are used.
@@ -27,11 +27,11 @@ so that they can be serialized into byte arrays inside the `AgentClassLoader`, t
to the tests and deserialized inside their class loader where they can be verified. The
`:testing-common` module (described below) hides this complexity from instrumentation test authors.
-### :agent-for-testing
+## :agent-for-testing
This is a custom distro of the javaagent that embeds the `:testing:agent-exporter`.
-### :testing-common
+## :testing-common
This module provides methods to help verify the span and metric data produced by the
instrumentation, hiding the complexity of accessing the in-memory exporters that live in the

MODIFY
docs/contributing/running-tests.md
docs/contributing/running-tests.md
-## Running the tests
+# Running the tests
-### Java versions
+## Java versions
Open Telemetry Auto Instrumentation's minimal supported version is java 8.
All jar files that we produce, unless noted otherwise, have bytecode
@@ -13,32 +13,32 @@ higher java version as required by library. The resulting classes will have
higher bytecode level, but as it matches library's java version, no runtime
problem arise.
-### Instrumentation tests
+## Instrumentation tests
Executing `./gradlew instrumentation:test` will run tests for all supported
auto-instrumentations using that java version which runs the Gradle build
itself. These tests usually use the minimal supported version of the
instrumented library.
-#### Executing tests with specific java version
+### Executing tests with specific java version
We run all tests on Java 11 by default, along with Java 8 and 15. To run on the later, set the
`testJavaVersion` Gradle property to the desired major version, e.g., `./gradlew test -PtestJavaVersion=8`,
`./gradlew test -PtestJavaVersion=15`. If you don't have a JDK of these versions
installed, Gradle will automatically download it for you.
-#### Executing tests against the latest versions of libraries under instrumentation
+### Executing tests against the latest versions of libraries under instrumentation
This is done as part of the nightly build in order to catch when a new version of a library is
released that breaks our instrumentation tests.
To run these tests locally, add `-PtestLatestDeps=true` to your existing `gradlew` command line.
-#### Executing single test
+### Executing single test
Executing `./gradlew :instrumentation:<INSTRUMENTATION_NAME>:test --tests <GROOVY TEST FILE NAME>` will run only the selected test.
-### Smoke tests
+## Smoke tests
The smoke tests are not run as part of a global `test` task run since they take a long time and are
not relevant for most contributions. Explicitly specify `:smoke-tests:test` to run them.

MODIFY
docs/contributing/style-guideline.md
docs/contributing/style-guideline.md
-## Style guideline
+# Style guideline
We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html).
-### Auto-formatting
+## Auto-formatting
The build will fail if the source code is not formatted according to the google java style.
@@ -25,7 +25,7 @@ Running
runs formatting verify task only.
-#### Pre-commit hook
+### Pre-commit hook
To completely delegate code style formatting to the machine,
there is a pre-commit hook setup to verify formatting before committing.
@@ -35,14 +35,14 @@ It can be activated with this command:
git config core.hooksPath .githooks
```
-#### Editorconfig
+### Editorconfig
As additional convenience for IntelliJ users, we provide `.editorconfig`
file. IntelliJ will automatically use it to adjust its code formatting settings.
It does not support all required rules, so you still have to run
`spotlessApply` from time to time.
-### Additional checks
+## Additional checks
The build uses checkstyle to verify some parts of the Google Java Style Guide that cannot be handled
by auto-formatting.
@@ -53,7 +53,7 @@ To run these checks locally:
./gradlew checkstyleMain checkstyleTest
```
-### Static imports
+## Static imports
We leverage static imports for many common types of operations. However, not all static methods or
constants are necessarily good candidates for a static import. The following list is a very
@@ -67,7 +67,7 @@ rough guideline of what are commonly accepted static imports:
* Singleton instances (especially where clearly named an hopefully immutable)
* `tracer()` methods that expose tracer singleton instances
-### Ordering of class contents
+## Ordering of class contents
The following order is preferred:
@@ -84,7 +84,7 @@ the non-private methods that use it.
In static utility classes (where all members are static), the private constructor
(used to prevent construction) should be ordered after methods instead of before methods.
-### `final` keyword usage
+## `final` keyword usage
Public classes should be declared `final` where possible.
@@ -97,7 +97,7 @@ Method parameters should never be declared `final`.
Local variables should only be declared `final` if they are not initialized inline
(declaring these vars `final` can help prevent accidental double-initialization).
-### `@Nullable` annotation usage
+## `@Nullable` annotation usage
[Note: this section is aspirational, as opposed to a reflection of the current codebase]

Update Intellij setup docs (#4103)