Address bric3 final review: errorLatencies + resetHandlers doc wording

- AggregateEntry.errorLatencies: note it is not thread-safe (bric3 suggestion)
- PeerTagSchema.resetHandlers: adopt bric3's clearer javadoc wording

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dougqh

dd-trace-core/src/main/java/datadog/trace/common/metrics/AggregateEntry.java

@@ -50,7 +50,8 @@ public final class AggregateEntry extends Hashtable.Entry {
   // into the entry.
   private final Histogram okLatencies;
 
-  // Null until first error; SerializingMetricWriter writes empty histogram form when null.
+  // Null until first error; SerializingMetricWriter writes empty histogram form when null. Not
+  // thread-safe as well.
   @Nullable private Histogram errorLatencies;
 
   private int errorCount;

dd-trace-core/src/main/java/datadog/trace/common/metrics/PeerTagSchema.java

@@ -119,11 +119,15 @@ UTF8BytesString register(int i, String value) {
   }
 
   /**
-   * Resets every {@link TagCardinalityHandler}'s working set and flushes this cycle's per-tag block
-   * counts to both {@link HealthMetrics} (as a per-cycle count) and {@code reporter} (accumulated
-   * by tag name for the rate-limited summary). Flushing by name here is what lets a peer-tag schema
-   * rebuild discard these handlers without losing counts. Must be called on the aggregator thread;
-   * handlers are not thread-safe.
+   * Resets cardinality tracking for each peer tag and reports how many values were blocked since
+   * the previous reset.
+   *
+   * <p>The counts are sent to {@link HealthMetrics} for the current reporting cycle. They are also
+   * added to {@code reporter}, which groups them by tag name for a rate-limited warning. Grouping
+   * counts by name ensures they are not lost when a schema rebuild replaces the handlers.
+   *
+   * <p>This method must be called only from the aggregator thread because the handlers are not
+   * thread-safe.
    */
   void resetHandlers(HealthMetrics healthMetrics, CardinalityLimitReporter reporter) {
     long totalCollapsed = 0;