add TagListBuilder helper (#1205)

Helper to support more efficient building of tag lists
with fewer allocations than relying on varargs `withTags`
method. If the builder is reused, then there would only
be a single allocation to copy the buffer array for most
uses.

The user would be responsible for managing the reuse of
the builder instances. This could be a thread local,
concurrent queue, or other options that make sense for
their use-case.

Author: brharrington

build.gradle

@@ -100,7 +100,7 @@ subprojects {
     profilers = ['stack', 'gc']
     includeTests = false
     duplicateClassesStrategy = DuplicatesStrategy.WARN
-    includes = ['.*IdHash.*']
+    includes = ['.*Ids.*']
   }
 
   checkstyle {

spectator-api/src/jmh/java/com/netflix/spectator/perf/Ids.java

@@ -18,6 +18,8 @@
 import com.netflix.spectator.api.DefaultRegistry;
 import com.netflix.spectator.api.Id;
 import com.netflix.spectator.api.Registry;
+import com.netflix.spectator.api.TagList;
+import com.netflix.spectator.api.TagListBuilder;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
@@ -29,21 +31,47 @@
 
 /**
  * <pre>
- * Benchmark                         Mode  Cnt          Score         Error  Units
- * Ids.append1                      thrpt   10   22,932,447.185 ±  558909.207  ops/s
- * Ids.append2                      thrpt   10   14,126,066.627 ± 2205349.084  ops/s
- * Ids.append4                      thrpt   10    5,165,821.740 ±  144524.852  ops/s
- * Ids.append4sorted                thrpt   10    5,923,827.749 ±  258122.285  ops/s
- * Ids.baseline                     thrpt   10   14,868,887.021 ± 4627616.416  ops/s
- * Ids.emptyAppend1                 thrpt   10   63,193,729.846 ± 1158843.888  ops/s
- * Ids.emptyAppend2                 thrpt   10   28,797,024.419 ± 2348775.496  ops/s
- * Ids.emptyAppend4                 thrpt   10    9,818,389.953 ±  227597.860  ops/s
- * Ids.emptyAppend4sorted           thrpt   10   11,342,478.015 ±  315543.929  ops/s
- * Ids.justName                     thrpt   10  166,275,032.184 ± 5252541.293  ops/s
- * Ids.withTag                      thrpt   10    1,586,379.085 ±   40204.926  ops/s
- * Ids.withTagsMap                  thrpt   10    1,841,867.329 ±   32378.659  ops/s
- * Ids.withTagsVararg               thrpt   10    1,946,970.522 ±   37919.937  ops/s
- * Ids.withTagsVarargSorted         thrpt   10    3,426,008.758 ±  115232.165  ops/s
+ * Benchmark               Throughput (ops/s)      Error
+ * -----------------------------------------------------------
+ * append1                 56,794,079.309      ±1,529,009.842
+ * append2                 29,813,536.825        ±242,156.195
+ * append4                  6,473,803.925        ±915,892.515
+ * append4sorted            7,021,400.576        ±251,550.333
+ * baseline                49,883,390.694        ±431,626.254
+ * emptyAppend1           200,362,500.375      ±1,438,114.615
+ * emptyAppend2            78,510,857.178        ±125,060.880
+ * emptyAppend4            14,228,870.597        ±350,789.283
+ * emptyAppend4sorted      16,585,176.379        ±387,667.119
+ * justName               437,797,027.428     ±24,884,978.092
+ * unsafeCreate            12,531,161.873      ±4,295,429.889
+ * withTag                  3,294,585.839        ±124,723.980
+ * withTagsBuilder          3,213,126.689         ±37,382.051
+ * withTagsBuilderSorted   10,095,083.206        ±569,033.538
+ * withTagsMap              4,088,836.194        ±104,959.027
+ * withTagsVararg           2,860,050.248         ±39,131.668
+ * withTagsVarargSorted     8,168,124.655        ±154,663.209
+ * </pre>
+ *
+ * <pre>
+ * Benchmark               Alloc Rate Norm (B/op)   Error
+ * -----------------------------------------------------------
+ * append1                 136.008                ±0.001
+ * append2                 208.015                ±0.001
+ * append4                 256.071                ±0.011
+ * append4sorted           256.066                ±0.002
+ * baseline                312.009                ±0.001
+ * emptyAppend1             72.002                ±0.001
+ * emptyAppend2            112.006                ±0.001
+ * emptyAppend4            144.032                ±0.001
+ * emptyAppend4sorted      144.027                ±0.001
+ * justName                 24.001                ±0.001
+ * unsafeCreate             48.036                ±0.013
+ * withTag               1,416.133                ±0.005
+ * withTagsBuilder         184.140                ±0.003
+ * withTagsBuilderSorted   184.044                ±0.003
+ * withTagsMap             224.115                ±0.002
+ * withTagsVararg          296.167                ±0.002
+ * withTagsVarargSorted    296.058                ±0.001
  * </pre>
  */
 @State(Scope.Thread)
@@ -97,6 +125,8 @@ private Map<String, String> getTags() {
       .withTag(   "nf.zone", "us-east-1e")
       .withTag(   "nf.node", "i-1234567890");
 
+  private final TagListBuilder builder = TagListBuilder.create();
+
   @Threads(1)
   @Benchmark
   public void justName(Blackhole bh) {
@@ -186,6 +216,48 @@ public void withTagsVarargSorted(Blackhole bh) {
     bh.consume(id);
   }
 
+  @Threads(1)
+  @Benchmark
+  public void withTagsBuilder(Blackhole bh) {
+    TagList ts = builder
+        .add("nf.app", "test_app")
+        .add("nf.cluster", "test_app-main")
+        .add("nf.asg", "test_app-main-v042")
+        .add("nf.stack", "main")
+        .add("nf.ami", "ami-0987654321")
+        .add("nf.region", "us-east-1")
+        .add("nf.zone", "us-east-1e")
+        .add("nf.node", "i-1234567890")
+        .add("country", "US")
+        .add("device", "xbox")
+        .add("status", "200")
+        .add("client", "ab")
+        .buildAndReset();
+    Id id = registry.createId("http.req.complete").withTags(ts);
+    bh.consume(id);
+  }
+
+  @Threads(1)
+  @Benchmark
+  public void withTagsBuilderSorted(Blackhole bh) {
+    TagList ts = builder
+        .add("client", "ab")
+        .add("country", "US")
+        .add("device", "xbox")
+        .add("nf.ami", "ami-0987654321")
+        .add("nf.app", "test_app")
+        .add("nf.asg", "test_app-main-v042")
+        .add("nf.cluster", "test_app-main")
+        .add("nf.node", "i-1234567890")
+        .add("nf.region", "us-east-1")
+        .add("nf.stack", "main")
+        .add("nf.zone", "us-east-1e")
+        .add("status", "200")
+        .buildAndReset();
+    Id id = registry.createId("http.req.complete").withTags(ts);
+    bh.consume(id);
+  }
+
   @Threads(1)
   @Benchmark
   public void withTagsMap(Blackhole bh) {

spectator-api/src/main/java/com/netflix/spectator/api/ArrayTagSet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2023 Netflix, Inc.
+ * Copyright 2014-2025 Netflix, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -216,7 +216,7 @@ private ArrayTagSet addAll(String[] ts, int tsLength) {
   }
 
   /** Add a collection of tags to the set. */
-  private ArrayTagSet addAll(String[] ts, int tsLength, boolean sorted, boolean distinct) {
+  ArrayTagSet addAll(String[] ts, int tsLength, boolean sorted, boolean distinct) {
     if (tsLength == 0) {
       return this;
     } else if (length == 0) {

spectator-api/src/main/java/com/netflix/spectator/api/TagListBuilder.java

@@ -0,0 +1,194 @@
+/*
+ * Copyright 2014-2025 Netflix, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.netflix.spectator.api;
+
+import com.netflix.spectator.impl.Preconditions;
+
+import java.util.Arrays;
+
+/**
+ * Builder for creating TagList instances efficiently. This builder can be reused multiple times
+ * and provides optimizations for sorted tag insertion to avoid unnecessary sorting operations
+ * later. A builder instance is not thread safe and should only be used from a single thread at
+ * a time. The user is responsible for managing how to reuse builder instances to avoid initial
+ * allocation of the builder each time.
+ *
+ * <p>The builder tracks whether tags are added in sorted order and passes this information
+ * to the underlying TagList implementation to optimize performance. For best performance,
+ * add tags in lexicographically sorted order by key.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * TagListBuilder builder = TagListBuilder.create();
+ * TagList tags = builder
+ *     .add("app", "myapp")
+ *     .add("env", "prod")
+ *     .add("region", "us-east-1")
+ *     .buildAndReset();
+ * }</pre>
+ *
+ * <p>The builder can be reused after calling {@link #buildAndReset()}:</p>
+ * <pre>{@code
+ * TagList tags1 = builder.add("key1", "value1").buildAndReset();
+ * TagList tags2 = builder.add("key2", "value2").buildAndReset();
+ * }</pre>
+ */
+public final class TagListBuilder {
+
+  /**
+   * Creates a new TagListBuilder instance.
+   *
+   * @return a new builder instance
+   */
+  public static TagListBuilder create() {
+    return new TagListBuilder(ArrayTagSet.EMPTY);
+  }
+
+  /**
+   * Creates a new TagListBuilder instance with a set of base tags that will be included
+   * in all TagLists built by this builder. The base tags are automatically added when
+   * the builder is created and after each {@link #buildAndReset()} call.
+   *
+   * @param baseTags the base tags to include in all built TagLists, must not be null
+   * @return a new builder instance with the specified base tags
+   */
+  public static TagListBuilder create(TagList baseTags) {
+    return new TagListBuilder(Preconditions.checkNotNull(baseTags, "baseTags"));
+  }
+
+  private final int basePos;
+  private final String baseKey;
+  private final boolean baseSorted;
+
+  private String[] tags;
+  private int pos;
+
+  private String lastKey;
+  private boolean sorted;
+
+  /**
+   * Creates a new builder with initial capacity for 10 key-value pairs.
+   */
+  TagListBuilder(TagList baseTags) {
+    int n = baseTags.size() * 2 + 20;
+    tags = new String[n];
+    pos = 0;
+    lastKey = null;
+    sorted = true;
+
+    // Add base tags and keep track of state for the reset
+    add(baseTags);
+    basePos = pos;
+    baseKey = lastKey;
+    baseSorted = sorted;
+  }
+
+  /**
+   * Returns whether the tags added so far are in sorted order by key.
+   * This is used internally to optimize TagList creation.
+   *
+   * @return true if tags are sorted, false otherwise
+   */
+  boolean isSorted() {
+    return sorted;
+  }
+
+  /**
+   * Doubles the capacity of the internal array if needed.
+   */
+  private void resizeIfNeeded() {
+    if (pos >= tags.length) {
+      tags = Arrays.copyOf(tags, tags.length * 2);
+    }
+  }
+
+  /**
+   * Checks if the given key is lexicographically greater than the last added key.
+   *
+   * @param key the key to check
+   * @return true if key is greater than the last key, or if this is the first key
+   */
+  private boolean isGreaterThanLastKey(String key) {
+    return lastKey == null || lastKey.compareTo(key) < 0;
+  }
+
+  /**
+   * Adds all tags from the provided TagList to this builder.
+   *
+   * @param tags the TagList containing tags to add, must not be null
+   * @return this builder for method chaining
+   */
+  public TagListBuilder add(TagList tags) {
+    final int n = tags.size();
+    for (int i = 0; i < n; ++i) {
+      add(tags.getKey(i), tags.getValue(i));
+    }
+    return this;
+  }
+
+  /**
+   * Adds a key-value pair to the builder. Null keys or values are ignored.
+   *
+   * <p>For optimal performance, add tags in lexicographically sorted order by key.
+   * The builder tracks sort order and passes this information to the underlying
+   * TagList implementation to avoid unnecessary sorting operations.</p>
+   *
+   * @param key the tag key, must not be null
+   * @param value the tag value, must not be null
+   * @return this builder for method chaining
+   */
+  public TagListBuilder add(String key, String value) {
+    if (key != null && value != null) {
+      resizeIfNeeded();
+      sorted = sorted && isGreaterThanLastKey(key);
+      lastKey = key;
+      tags[pos++] = key;
+      tags[pos++] = value;
+    }
+    return this;
+  }
+
+  /**
+   * Adds a Tag object to the builder. Null keys or values are ignored.
+   *
+   * @param tag the tag to add, must not be null and must have non-null key and value
+   * @return this builder for method chaining
+   */
+  public TagListBuilder add(Tag tag) {
+    return add(tag.key(), tag.value());
+  }
+
+  /**
+   * Resets the builder to its initial empty state, allowing it to be reused.
+   */
+  public void reset() {
+    pos = basePos;
+    lastKey = baseKey;
+    sorted = baseSorted;
+  }
+
+  /**
+   * Builds a TagList from the accumulated tags and resets the builder for reuse.
+   *
+   * @return a new TagList containing all the added tags
+   */
+  public TagList buildAndReset() {
+    String[] copy = Arrays.copyOf(tags, pos);
+    TagList ts = ArrayTagSet.EMPTY.addAll(copy, pos, sorted, sorted);
+    reset();
+    return ts;
+  }
+}