Add a caching API based on caffeine for use from instrumentation, not just javaagent

gradle/dependencies.gradle

@@ -30,6 +30,9 @@ ext {
     systemLambda      : "1.1.0",
     prometheus        : "0.9.0",
     assertj           : '3.19.0',
+    awaitility        : '4.0.3',
+    // Caffeine 2.x to support Java 8+. 3.x is 11+.
+    caffeine          : '2.9.0',
     testcontainers    : '1.15.2'
   ]
 
@@ -73,6 +76,7 @@ ext {
       dependencies.create(group: 'io.prometheus', name: 'simpleclient', version: "${versions.prometheus}"),
       dependencies.create(group: 'io.prometheus', name: 'simpleclient_httpserver', version: "${versions.prometheus}"),
     ],
+    caffeine                     : "com.github.ben-manes.caffeine:caffeine:${versions.caffeine}",
 
     // Testing
 
@@ -97,5 +101,6 @@ ext {
     coroutines                   : dependencies.create(group: 'org.jetbrains.kotlinx', name: 'kotlinx-coroutines-core', version: "${versions.coroutines}"),
     junitApi                     : "org.junit.jupiter:junit-jupiter-api:${versions.junit5}",
     assertj                      : "org.assertj:assertj-core:${versions.assertj}",
+    awaitility                   : "org.awaitility:awaitility:${versions.awaitility}"
   ]
 }

gradle/spotbugs-exclude.xml

@@ -10,6 +10,7 @@
     <Or>
       <Class name="io.opentelemetry.instrumentation.test.utils.GcUtils"/>
       <Class name="io.opentelemetry.javaagent.util.GcUtils"/>
+      <Class name="~io.opentelemetry.instrumentation.api.caching.CacheTest.*"/>
     </Or>
     <Bug pattern="DM_GC"/>
   </Match>

instrumentation-api-caching/instrumentation-api-caching.gradle

@@ -0,0 +1,29 @@
+plugins {
+  id "com.github.johnrengelman.shadow"
+}
+
+group = 'io.opentelemetry.instrumentation'
+
+apply from: "$rootDir/gradle/java.gradle"
+apply from: "$rootDir/gradle/publish.gradle"
+
+dependencies {
+  implementation(deps.caffeine) {
+    exclude group: 'com.google.errorprone', module: 'error_prone_annotations'
+    exclude group: 'org.checkerframework', module: 'checker-qual'
+  }
+}
+
+shadowJar {
+  archiveClassifier.set("")
+
+  relocate "com.github.benmanes.caffeine", "io.opentelemetry.instrumentation.internal.shaded.caffeine"
+
+  minimize()
+}
+
+jar {
+  enabled = false
+
+  dependsOn shadowJar
+}

instrumentation-api-caching/src/main/java/com/github/benmanes/caffeine/cache/CacheImplementations.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package com.github.benmanes.caffeine.cache;
+
+// Caffeine uses reflection to load cache implementations based on parameters specified by a user.
+// We use gradle-shadow-plugin to minimize the dependency on Caffeine, but it does not allow
+// specifying classes to keep, only artifacts. It's a relatively simple workaround for us to use
+// this non-public class to create a static link to the required implementations we use.
+final class CacheImplementations {
+
+  // Each type of cache has a cache implementation and a node implementation.
+
+  // Strong keys, strong values, maximum size
+  SSMS<?, ?> ssms; // cache
+  PSMS<?, ?> psms; // node
+
+  // Weak keys, strong values, maximum size
+  WSMS<?, ?> wsms; // cache
+  FSMS<?, ?> fsms; // node
+
+  private CacheImplementations() {}
+}

instrumentation-api-caching/src/main/java/io/opentelemetry/instrumentation/api/caching/Cache.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.caching;
+
+import java.util.function.Function;
+
+/** A cache from keys to values. */
+public interface Cache<K, V> {
+
+  /** Returns a new {@link CacheBuilder} to configure a {@link Cache}. */
+  static CacheBuilder newBuilder() {
+    return new CacheBuilder();
+  }
+
+  /**
+   * Returns the cached value associated with the provided {@code key}. If no value is cached yet,
+   * computes the value using {@code mappingFunction}, stores the result, and returns it.
+   */
+  V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction);
+}

instrumentation-api-caching/src/main/java/io/opentelemetry/instrumentation/api/caching/CacheBuilder.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.caching;
+
+import com.github.benmanes.caffeine.cache.Caffeine;
+import java.util.concurrent.Executor;
+
+/** A builder of {@link Cache}. */
+public final class CacheBuilder {
+
+  private final Caffeine<?, ?> caffeine = Caffeine.newBuilder();
+
+  /** Sets the maximum size of the cache. */
+  public CacheBuilder setMaximumSize(long maximumSize) {
+    caffeine.maximumSize(maximumSize);
+    return this;
+  }
+
+  /**
+   * Sets that keys should be referenced weakly. If used, keys will use identity comparison, not
+   * {@link Object#equals(Object)}.
+   */
+  public CacheBuilder setWeakKeys() {
+    caffeine.weakKeys();
+    return this;
+  }
+
+  // Visible for testing
+  CacheBuilder setExecutor(Executor executor) {
+    caffeine.executor(executor);
+    return this;
+  }
+
+  /** Returns a new {@link Cache} with the settings of this {@link CacheBuilder}. */
+  public <K, V> Cache<K, V> build() {
+    @SuppressWarnings("unchecked")
+    com.github.benmanes.caffeine.cache.Cache<K, V> delegate =
+        (com.github.benmanes.caffeine.cache.Cache<K, V>) caffeine.build();
+    return new CaffeineCache<K, V>(delegate);
+  }
+
+  CacheBuilder() {}
+}

instrumentation-api-caching/src/main/java/io/opentelemetry/instrumentation/api/caching/CaffeineCache.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.caching;
+
+import java.util.Set;
+import java.util.function.Function;
+
+final class CaffeineCache<K, V> implements Cache<K, V> {
+
+  private final com.github.benmanes.caffeine.cache.Cache<K, V> delegate;
+
+  CaffeineCache(com.github.benmanes.caffeine.cache.Cache<K, V> delegate) {
+    this.delegate = delegate;
+  }
+
+  @Override
+  public V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction) {
+    return delegate.get(key, mappingFunction);
+  }
+
+  // Visible for testing
+  Set<K> keySet() {
+    return delegate.asMap().keySet();
+  }
+
+  // Visible for testing
+  void cleanup() {
+    delegate.cleanUp();
+  }
+}

instrumentation-api-caching/src/test/README.md

@@ -0,0 +1 @@
+Tests for this module are in the instrumentation-api project to verify against the shaded artifact.

instrumentation-api/instrumentation-api.gradle

@@ -4,6 +4,8 @@ apply from: "$rootDir/gradle/java.gradle"
 apply from: "$rootDir/gradle/publish.gradle"
 
 dependencies {
+  api project(":instrumentation-api-caching")
+
   api deps.opentelemetryApi
   api deps.opentelemetryContext
   api deps.opentelemetrySemConv
@@ -16,4 +18,5 @@ dependencies {
   testImplementation project(':testing-common')
   testImplementation group: 'org.mockito', name: 'mockito-core', version: '3.6.0'
   testImplementation deps.assertj
+  testImplementation deps.awaitility
 }

instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/caching/CacheTest.java

@@ -0,0 +1,120 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.caching;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+class CacheTest {
+
+  @Nested
+  class StrongKeys {
+    @Test
+    void unbounded() {
+      Cache<String, String> cache = Cache.newBuilder().build();
+
+      CaffeineCache<?, ?> caffeineCache = ((CaffeineCache<?, ?>) cache);
+      assertThat(cache.computeIfAbsent("cat", unused -> "meow")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent("cat", unused -> "bark")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent("dog", unused -> "bark")).isEqualTo("bark");
+      assertThat(caffeineCache.keySet()).hasSize(2);
+      assertThat(cache.computeIfAbsent("cat", unused -> "meow")).isEqualTo("meow");
+    }
+
+    @Test
+    void bounded() {
+      Cache<String, String> cache = Cache.newBuilder().setMaximumSize(1).build();
+
+      CaffeineCache<?, ?> caffeineCache = ((CaffeineCache<?, ?>) cache);
+      assertThat(cache.computeIfAbsent("cat", unused -> "meow")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent("cat", unused -> "bark")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent("dog", unused -> "bark")).isEqualTo("bark");
+      caffeineCache.cleanup();
+      assertThat(caffeineCache.keySet()).hasSize(1);
+      assertThat(cache.computeIfAbsent("cat", unused -> "purr")).isEqualTo("purr");
+    }
+  }
+
+  @Nested
+  class WeakKeys {
+    @Test
+    void unbounded() {
+      Cache<String, String> cache = Cache.newBuilder().setWeakKeys().build();
+
+      CaffeineCache<?, ?> caffeineCache = ((CaffeineCache<?, ?>) cache);
+      String cat = new String("cat");
+      String dog = new String("dog");
+      assertThat(cache.computeIfAbsent(cat, unused -> "meow")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent(cat, unused -> "bark")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent(dog, unused -> "bark")).isEqualTo("bark");
+      assertThat(caffeineCache.keySet()).hasSize(2);
+      assertThat(cache.computeIfAbsent(cat, unused -> "meow")).isEqualTo("meow");
+
+      cat = null;
+      System.gc();
+      // Wait for GC to be reflected.
+      await()
+          .untilAsserted(
+              () -> {
+                caffeineCache.cleanup();
+                assertThat(caffeineCache.keySet()).hasSize(1);
+              });
+      assertThat(cache.computeIfAbsent(dog, unused -> "bark")).isEqualTo("bark");
+      dog = null;
+      System.gc();
+      // Wait for GC to be reflected.
+      await()
+          .untilAsserted(
+              () -> {
+                caffeineCache.cleanup();
+                assertThat(caffeineCache.keySet()).isEmpty();
+              });
+    }
+
+    @Test
+    void bounded() throws Exception {
+      Cache<String, String> cache = Cache.newBuilder().setWeakKeys().setMaximumSize(1).build();
+
+      CaffeineCache<?, ?> caffeineCache = ((CaffeineCache<?, ?>) cache);
+
+      String cat = new String("cat");
+      String dog = new String("dog");
+      assertThat(cache.computeIfAbsent(cat, unused -> "meow")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent(cat, unused -> "bark")).isEqualTo("meow");
+      assertThat(caffeineCache.keySet()).hasSize(1);
+
+      assertThat(cache.computeIfAbsent(dog, unused -> "bark")).isEqualTo("bark");
+      caffeineCache.cleanup();
+      assertThat(caffeineCache.keySet()).hasSize(1);
+      dog = null;
+      System.gc();
+      // Wait for GC to be reflected.
+      await()
+          .untilAsserted(
+              () -> {
+                caffeineCache.cleanup();
+                assertThat(caffeineCache.keySet()).isEmpty();
+              });
+    }
+  }
+}