"Nocode" instrumentation without modifying source

.fossa.yml

@@ -196,6 +196,12 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:mybatis-3.2:javaagent'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:nocode:bootstrap'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:nocode:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:opentelemetry-extension-annotations-1.0:javaagent'

dependencyManagement/build.gradle.kts

@@ -119,7 +119,8 @@ val DEPENDENCIES = listOf(
   "org.objenesis:objenesis:3.4",
   "javax.validation:validation-api:2.0.1.Final",
   "org.snakeyaml:snakeyaml-engine:2.9",
-  "org.elasticmq:elasticmq-rest-sqs_2.13:1.6.12"
+  "org.elasticmq:elasticmq-rest-sqs_2.13:1.6.12",
+  "org.apache.commons:commons-jexl3:3.4.0"
 )
 
 javaPlatform {

instrumentation/nocode/README.md

@@ -0,0 +1,47 @@
+# "nocode" instrumentation
+
+Sometimes, you need to apply custom instrumentation to code you don't control/can't edit
+(e.g., for a third-party app).  This module provides a way to do that, controlling many
+behaviors of instrumentation available through the trace api.
+
+# Usage
+
+Set `OTEL_JAVA_INSTRUMENTATION_NOCODE_YML_FILE=/path/to/your.yml`, where the yml describes
+what methods you want to instrument and how:
+
+```
+- class: myapp.BusinessObject
+  method: update
+  spanName: this.getName()
+  attributes:
+    - key: "business.context"
+      value: this.getDetails().get("context")
+
+- class: mycustom.SpecialClient
+  method: doRequest
+  spanKind: CLIENT
+  spanStatus: 'returnValue.code() > 3 ? "OK" : "ERROR"'
+  attributes:
+    - key: "special.header"
+      value: 'param0.headers().get("special-header").substring(5)'
+```
+
+Expressions are written in [JEXL](https://commons.apache.org/proper/commons-jexl/reference/syntax.html) and may use
+the following variables:
+  - `this` - which may be null for a static method
+  - `param0` through `paramN` where 0 indexes the first parameter to the method
+  - `returnValue` which is only defined for `spanStatus` and may be null (if an exception is thrown or the method returns void)
+  - `error` which is only defined for `spanStatus` and is the `Throwable` thrown by the method invocation (or null if a normal return)
+
+# See also
+
+If you don't need this much control over span creation, you might find
+[methods instrumentation](../methods/README.md) a simpler way to get started.
+
+# Safety
+
+Please be aware of all side effects of statements you write in "nocode" instrumentation.
+Avoid calling methods that permute state, interact with threads or locks, or might
+have signigicant performance impact.  Additionally, be aware that code under
+active development might have its class or method names change, breaking instrumentation
+created in this way.

instrumentation/nocode/bootstrap/build.gradle.kts

@@ -0,0 +1,3 @@
+plugins {
+  id("otel.javaagent-bootstrap")
+}

instrumentation/nocode/bootstrap/src/main/java/io/opentelemetry/javaagent/bootstrap/nocode/NocodeExpression.java

@@ -0,0 +1,13 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.javaagent.bootstrap.nocode;
+
+public interface NocodeExpression {
+
+  Object evaluate(Object thiz, Object[] params);
+
+  Object evaluateAtEnd(Object thiz, Object[] params, Object returnValue, Throwable error);
+}

instrumentation/nocode/bootstrap/src/main/java/io/opentelemetry/javaagent/bootstrap/nocode/NocodeInstrumentationRules.java

@@ -0,0 +1,159 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.javaagent.bootstrap.nocode;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import io.opentelemetry.api.trace.SpanKind;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+
+public final class NocodeInstrumentationRules {
+
+  public static final class Builder {
+    private String className;
+    private String methodName;
+    private NocodeExpression spanName;
+    private SpanKind spanKind;
+    private NocodeExpression spanStatus;
+    private final Map<String, NocodeExpression> attributes = new HashMap<>();
+
+    @CanIgnoreReturnValue
+    public Builder className(String className) {
+      this.className = className;
+      return this;
+    }
+
+    @CanIgnoreReturnValue
+    public Builder methodName(String methodName) {
+      this.methodName = methodName;
+      return this;
+    }
+
+    @CanIgnoreReturnValue
+    public Builder spanName(NocodeExpression spanName) {
+      this.spanName = spanName;
+      return this;
+    }
+
+    @CanIgnoreReturnValue
+    public Builder spanKind(SpanKind spanKind) {
+      this.spanKind = spanKind;
+      return this;
+    }
+
+    @CanIgnoreReturnValue
+    public Builder spanStatus(NocodeExpression spanStatus) {
+      this.spanStatus = spanStatus;
+      return this;
+    }
+
+    @CanIgnoreReturnValue
+    public Builder attribute(String key, NocodeExpression valueExpression) {
+      attributes.put(key, valueExpression);
+      return this;
+    }
+
+    public Rule build() {
+      return new Rule(className, methodName, spanName, spanKind, spanStatus, attributes);
+    }
+  }
+
+  public static final class Rule {
+    private static final AtomicInteger counter = new AtomicInteger();
+
+    private final int id = counter.incrementAndGet();
+    private final String className;
+    private final String methodName;
+    private final NocodeExpression spanName; // may be null - use default of "class.method"
+    private final SpanKind spanKind; // may be null
+    private final NocodeExpression spanStatus; // may be null, should return string from StatusCodes
+    private final Map<String, NocodeExpression> attributes; // key name to jexl expression
+
+    public Rule(
+        String className,
+        String methodName,
+        NocodeExpression spanName,
+        SpanKind spanKind,
+        NocodeExpression spanStatus,
+        Map<String, NocodeExpression> attributes) {
+      this.className = className;
+      this.methodName = methodName;
+      this.spanName = spanName;
+      this.spanKind = spanKind;
+      this.spanStatus = spanStatus;
+      this.attributes = Collections.unmodifiableMap(new HashMap<>(attributes));
+    }
+
+    public int getId() {
+      return id;
+    }
+
+    public Map<String, NocodeExpression> getAttributes() {
+      return attributes;
+    }
+
+    public String getClassName() {
+      return className;
+    }
+
+    public String getMethodName() {
+      return methodName;
+    }
+
+    public NocodeExpression getSpanName() {
+      return spanName;
+    }
+
+    public SpanKind getSpanKind() {
+      return spanKind;
+    }
+
+    public NocodeExpression getSpanStatus() {
+      return spanStatus;
+    }
+
+    @Override
+    public String toString() {
+      return "Nocode rule: "
+          + className
+          + "."
+          + methodName
+          + ":spanName="
+          + spanName
+          + ":spanKind="
+          + spanKind
+          + ":spanStatus="
+          + spanStatus
+          + ",attrs="
+          + attributes;
+    }
+  }
+
+  private NocodeInstrumentationRules() {}
+
+  // FUTURE setting the global and lookup could go away if the instrumentation could be
+  // parameterized with the Rule
+
+  private static final HashMap<Integer, Rule> ruleMap = new HashMap<>();
+
+  // Called by the NocodeInitializer
+  public static void setGlobalRules(List<Rule> rules) {
+    for (Rule r : rules) {
+      ruleMap.put(r.id, r);
+    }
+  }
+
+  public static Iterable<Rule> getGlobalRules() {
+    return ruleMap.values();
+  }
+
+  public static Rule find(int id) {
+    return ruleMap.get(id);
+  }
+}

instrumentation/nocode/javaagent-unit-tests/build.gradle.kts

@@ -0,0 +1,9 @@
+plugins {
+  id("otel.java-conventions")
+}
+
+dependencies {
+  testImplementation(project(":instrumentation:nocode:javaagent"))
+  testImplementation(project(":instrumentation:nocode:bootstrap"))
+  testImplementation("org.apache.commons:commons-jexl3")
+}