Skip to content

Files

instrumentation

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Jul 18, 2024
Aug 5, 2024
Aug 5, 2024
Jun 20, 2024
Jun 20, 2024
Jun 20, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Aug 5, 2024
Apr 16, 2024
Apr 16, 2024
Jan 2, 2025
Mar 25, 2024
Apr 12, 2024
Nov 1, 2024
Apr 12, 2024
Dec 2, 2024
Jan 14, 2025
Aug 5, 2024
Aug 5, 2024
Jul 10, 2024
Jan 17, 2025
Jan 17, 2025
Jan 17, 2025
Jan 17, 2025
Jan 17, 2025
Jan 17, 2025
Jan 17, 2025
Dec 13, 2024
Dec 13, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Jan 23, 2025
Jan 21, 2025
Jun 27, 2023
Mar 1, 2023
Mar 1, 2023
Aug 5, 2024
May 15, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Aug 22, 2024
Mar 1, 2023
Jan 17, 2025
Mar 1, 2023
Sep 16, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Jul 10, 2024
Jul 10, 2024
Jul 10, 2024
Jul 10, 2024
Mar 5, 2024
Mar 5, 2024
Mar 5, 2024
Mar 5, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Jul 12, 2024
Feb 15, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 20, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 20, 2024
Mar 1, 2023
Mar 1, 2023
Feb 16, 2024
Feb 15, 2024
Jan 10, 2025
Oct 4, 2024
Nov 5, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
May 22, 2024
Mar 1, 2023
May 22, 2024
Apr 16, 2024
Jan 9, 2024
Mar 1, 2023
Mar 1, 2023
May 7, 2024
Jun 27, 2023
Mar 1, 2023
Dec 7, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 4, 2025
Feb 4, 2025
Feb 4, 2025
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Apr 13, 2023
Mar 1, 2023
Mar 1, 2023
Oct 19, 2022
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Oct 12, 2023
Mar 1, 2023
Aug 15, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Sep 6, 2023
Aug 3, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 21, 2024
Oct 20, 2023
Oct 20, 2023
Nov 12, 2024
Oct 20, 2023
Apr 12, 2024
Apr 12, 2024
Apr 12, 2024
Apr 12, 2024
Mar 1, 2023
Mar 1, 2023
Jul 10, 2024
Aug 9, 2024
Mar 1, 2023
Jun 12, 2024
Jun 18, 2024
Aug 28, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Jun 22, 2023
Jan 14, 2025
Jan 14, 2025
Jan 21, 2025
Jan 22, 2025
Jan 22, 2025
Jan 22, 2025
Jan 15, 2025
Mar 8, 2023
Jun 22, 2023
Jul 25, 2023
Jul 25, 2023
Mar 28, 2023
Mar 7, 2023
Mar 7, 2023
Mar 7, 2023
Feb 27, 2024
Nov 7, 2024
Mar 1, 2023
Nov 29, 2023
Nov 1, 2024
Apr 16, 2024
Mar 28, 2024
Sep 4, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 2, 2023
Sep 25, 2024
Mar 1, 2023
Mar 1, 2023
Nov 21, 2023
Nov 21, 2023
Nov 21, 2023
Nov 21, 2023
Mar 21, 2024
Mar 21, 2024
Mar 21, 2024
Mar 25, 2024
Dec 20, 2024
Mar 1, 2023
Mar 1, 2023
Jul 12, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 9, 2024
Mar 4, 2024
May 17, 2024
May 17, 2024
May 17, 2024
Mar 1, 2023
Mar 1, 2023
Jun 27, 2023
Feb 21, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 26, 2024
Apr 5, 2023
Jun 23, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Aug 5, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 4, 2025
Feb 4, 2025
Feb 4, 2025
Dec 13, 2024
Feb 4, 2025
Feb 4, 2025
Mar 28, 2024
May 28, 2024
Jul 12, 2024
Jul 12, 2024
Jul 12, 2024
Jul 12, 2024
Jul 12, 2024
Dec 13, 2024
Mar 1, 2023
Jun 27, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Dec 6, 2023
Dec 6, 2023
Dec 6, 2023
May 12, 2023
May 12, 2023
Mar 1, 2023
Aug 23, 2024
Aug 23, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Jul 11, 2023
Mar 1, 2023
Mar 1, 2023
Feb 21, 2024
Feb 21, 2024
Mar 1, 2023
Oct 20, 2023
Oct 20, 2023
Oct 20, 2023
Jan 18, 2024
Jan 18, 2024
Mar 1, 2023
Mar 6, 2024
Mar 6, 2024
Sep 27, 2024
Oct 20, 2023
Mar 1, 2023
Feb 22, 2024
Dec 21, 2023
Feb 22, 2024
Mar 6, 2023
Mar 6, 2023
Mar 6, 2023
Nov 17, 2023
Feb 26, 2024
Jan 18, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Feb 22, 2024
Mar 1, 2023
Mar 1, 2023
Feb 22, 2024
Mar 1, 2023
Mar 1, 2023
Feb 22, 2024
Mar 1, 2023
Mar 1, 2023
Oct 11, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 6, 2023
Mar 1, 2023
Mar 1, 2023
Jan 29, 2024
Aug 5, 2024
Aug 5, 2024
Jan 29, 2024
Dec 24, 2024
Dec 24, 2024
Dec 24, 2024
Dec 24, 2024
Dec 24, 2024
Dec 24, 2024
Dec 24, 2024
Aug 12, 2024
Oct 12, 2023
Aug 5, 2024
Oct 12, 2023
Oct 12, 2023
Oct 12, 2023
Oct 12, 2023
Jun 26, 2024
Nov 11, 2024
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Mar 1, 2023
Aug 28, 2023
Mar 1, 2023
Jun 27, 2023
Aug 22, 2023
Mar 1, 2023
Mar 4, 2024
Mar 4, 2024
Aug 8, 2020
May 24, 2023

Instrumentation modules

This gradle project contains subprojects for each individual instrumentation module. Instrumentation modules are typically packaged as simple jar files.

Introduction

Instrumentation modules may contain three types of classes.

  1. Weave classes. Weave classes are required. Weave classes are usually annotated with @Weave or @WeaveWithAnnotation. At runtime, the weaver will extract the bytecode from these classes and insert it into the target class. Although the previous style was to put the weave class in the same package and class name, newer patterns use the class name suffixed with "_Instrumentation" and the originalName attribute on the annotation.
  2. Utility classes. Utility classes are common, but optional. These classes are usually not annotated at all. When an instrumentation module is applied, utility classes are made available to the woven code.
  3. SkipIfPresent classes. SkipIfPresent classes are optional. These classes are annotated with @SkipIfPresent and are empty. They are used to narrow the focus of a given instrumentation module. For example, imagine a module successfully applies to versions 1, 2, and 3 of a given application server, but it won't actually function correctly on version 3. Module authors will look for a class that may have been introduced in version 3 and annotate it with @SkipIfPresent. If the weaver finds a @SkipIfPresent class on the classpath, the instrumentation module will not be applied.

Expectations

Instrumentation modules can use any dependencies they need for compilation or testing. However, there are some expectations that the agent puts on instrumentation modules.

  1. Instrumentation modules cannot use lambdas. Instead, use anonymous or inner classes. At runtime, utility classes (those without the @Weave annotation) are loaded directly onto the classpath of the classloader. The weaver does not support the required rewrite of the invokedynamic instruction, nor the relocation of the corresponding class.
  2. All required classes must either be already present on the classpath, or they must be present in the instrumentation module jar. The weaver does not provide any POM-like dependency resolution, so the instrumentation module must be wholly contained. Module authors may assume that the New Relic API classes are available (see newrelic-api). The agent will always inject New Relic API classes on the bootstrap classloader.

Cached Weave Attributes

On JVM startup, the Java agent looks at all the available instrumentation modules and determines the classes and methods that would be required for weaving. Normally, it would have to load every class in the instrumentation module to figure out what's required. As a speed optimization, existing instrumentation modules ship with all the necessary information stored as attributes in the instrumentation module's manifest. Then the agent can get the same information from a single text file in the jar.

In a Java-only, Scala-only, or Java+Scala instrumentation module, these attributes are calculated automatically and added to the jar. A task is added to the graph by cache_weave_attributes.gradle.kts. The task uses the weaver to calculate the attributes and store them in a temporary manifest. This temporary manifest is later added to the manifest by the jar task.

In rare cases, an instrumentation module needs 3rd-party dependencies. This should generally be avoided. If it cannot be avoided, you should shadow those dependencies. In an instrumentation module that uses shadow, there are some additional steps that need to be taken.

  1. Don't apply the shadow plugin. Instead, create the task manually. Otherwise, shadow will attempt to add the weave attributes to the shadowJar task, creating a circular dependency.
    tasks.create("shadowJar", ShadowJar) {
        archiveClassifier.set("shadowed")
        // add additional configuration here
    }
  2. Make the writeCachedWeaveAttributes task dependent on your task that generates the shadow jar. Usually this looks like this:
    project.tasks.getByName("writeCachedWeaveAttributes").dependsOn(shadowJar)
  3. Add the shadow jar artifact to the instrumentationWithDependencies configuration:
    artifacts {
        instrumentationWithDependencies shadowJar
    }