Add javadoc note about metrics timestamps (#4820)

* Add javadoc note about metrics timestamps

* Move to class level

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

@@ -142,6 +142,11 @@ public final class InstrumenterBuilder<REQUEST, RESPONSE> {
    * Sets the {@link TimeExtractor} to extract the timestamp marking the start and end of
    * processing. If unset, the constructed instrumenter will defer determining start and end
    * timestamps to the OpenTelemetry SDK.
+   *
+   * <p>Note: if metrics are generated by the Instrumenter, the start and end times from the {@link
+   * TimeExtractor} will be used to generate any duration metrics, but the internal metric timestamp
+   * (when it occurred) will always be stamped with "now" when the metric is recorded (i.e. there is
+   * no way to back date a metric recording).
    */
   public InstrumenterBuilder<REQUEST, RESPONSE> setTimeExtractor(
       TimeExtractor<REQUEST, RESPONSE> timeExtractor) {

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/TimeExtractor.java

@@ -8,7 +8,14 @@ package io.opentelemetry.instrumentation.api.instrumenter;
 import java.time.Instant;
 import javax.annotation.Nullable;
 
-/** Extractor of the start and end times of request processing. */
+/**
+ * Extractor of the start and end times of request processing.
+ *
+ * <p>Note: if metrics are generated by the Instrumenter, the start and end times from the {@code
+ * TimeExtractor} will be used to generate any duration metrics, but the internal metric timestamp
+ * (when it occurred) will always be stamped with "now" when the metric is recorded (i.e. there is
+ * no way to back date a metric recording).
+ */
 public interface TimeExtractor<REQUEST, RESPONSE> {
 
   /** Returns the timestamp marking the start of the request processing. */