Add transaction_name_groups config (#2676)

Author: felixbarny

CHANGELOG.asciidoc

@@ -27,6 +27,8 @@ endif::[]
 ===== Features
 * Add support for Spring WebClient - {pull}2229[#2229]
 * Added undocumented and unsupported configuration `metric_set_limit` to increase the metric set limit - {pull}2148[#2148]
+* Added <<config-transaction-name-groups, `transaction_name_groups`>> configuration option.
+** Deprecated <<config-url-groups, `url_groups`>> in favor of <<config-transaction-name-groups, `transaction_name_groups`>>.
 
 [float]
 ===== Bug fixes

apm-agent-core/src/main/java/co/elastic/apm/agent/configuration/CoreConfiguration.java

@@ -714,6 +714,22 @@ public String toString(Collection<String> value) {
         .dynamic(false)
         .buildWithDefault(false);
 
+    private final ConfigurationOption<List<WildcardMatcher>> transactionNameGroups = ConfigurationOption
+        .builder(new org.stagemonitor.configuration.converter.ListValueConverter<>(new WildcardMatcherValueConverter()), List.class)
+        .key("transaction_name_groups")
+        .tags("added[1.33.0]")
+        .configurationCategory(CORE_CATEGORY)
+        .description("With this option,\n" +
+            "you can group transaction names that contain dynamic parts with a wildcard expression.\n" +
+            "For example,\n" +
+            "the pattern `GET /user/*/cart` would consolidate transactions,\n" +
+            "such as `GET /users/42/cart` and `GET /users/73/cart` into a single transaction name `GET /users/*/cart`,\n" +
+            "hence reducing the transaction name cardinality.\n" +
+            "\n" +
+            WildcardMatcher.DOCUMENTATION)
+        .dynamic(true)
+        .buildWithDefault(Collections.<WildcardMatcher>emptyList());
+
     public boolean isEnabled() {
         return enabled.get();
     }
@@ -943,6 +959,10 @@ public boolean isEnablePublicApiAnnotationInheritance() {
         return enablePublicApiAnnotationInheritance.get();
     }
 
+    public List<WildcardMatcher> getTransactionNameGroups() {
+        return transactionNameGroups.get();
+    }
+
     public enum EventType {
         /**
          * Request bodies will never be reported

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/context/web/WebConfiguration.java

@@ -103,15 +103,18 @@ public class WebConfiguration extends ConfigurationOptionProvider {
             "WARNING: If your URLs contain path parameters like `/user/$userId`,\n" +
             "you should be very careful when enabling this flag,\n" +
             "as it can lead to an explosion of transaction groups.\n" +
-            "Take a look at the `url_groups` option on how to mitigate this problem by grouping URLs together.")
+            "Take a look at the <<config-transaction-name-groups,`transaction_name_groups`>> option on how to mitigate this problem by grouping URLs together.")
         .dynamic(true)
         .buildWithDefault(false);
 
     private final ConfigurationOption<List<WildcardMatcher>> urlGroups = ConfigurationOption
         .builder(new ListValueConverter<>(new WildcardMatcherValueConverter()), List.class)
         .key("url_groups")
+        .tags("deprecated")
         .configurationCategory(HTTP_CATEGORY)
-        .description("This option is only considered, when `use_path_as_transaction_name` is active.\n" +
+        .description("Deprecated in favor of <<config-transaction-name-groups,`transaction_name_groups`>>.\n" +
+            "\n" +
+            "This option is only considered, when `use_path_as_transaction_name` is active.\n" +
             "\n" +
             "With this option, you can group several URL paths together by using a wildcard expression like `/user/*`.\n" +
             "\n" +

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/transaction/AbstractSpan.java

@@ -306,7 +306,7 @@ public void updateName(Class<?> clazz, String methodName) {
      * @return name
      */
     public String getNameAsString() {
-        return name.toString();
+        return getNameForSerialization().toString();
     }
 
     /**

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/transaction/Transaction.java

@@ -25,6 +25,7 @@
 import co.elastic.apm.agent.impl.context.TransactionContext;
 import co.elastic.apm.agent.impl.context.web.ResultUtil;
 import co.elastic.apm.agent.impl.sampling.Sampler;
+import co.elastic.apm.agent.matcher.WildcardMatcher;
 import co.elastic.apm.agent.metrics.Labels;
 import co.elastic.apm.agent.metrics.MetricRegistry;
 import co.elastic.apm.agent.metrics.Timer;
@@ -67,6 +68,8 @@ protected Labels.Mutable initialValue() {
      */
     private final KeyListConcurrentHashMap<String, KeyListConcurrentHashMap<String, Timer>> timerBySpanTypeAndSubtype = new KeyListConcurrentHashMap<>();
     private final WriterReaderPhaser phaser = new WriterReaderPhaser();
+    private final CoreConfiguration coreConfig;
+    private final SpanConfiguration spanConfig;
 
     /**
      * The result of the transaction. HTTP status code for HTTP-related
@@ -110,6 +113,8 @@ public Transaction getTransaction() {
 
     public Transaction(ElasticApmTracer tracer) {
         super(tracer);
+        coreConfig = tracer.getConfig(CoreConfiguration.class);
+        spanConfig = tracer.getConfig(SpanConfiguration.class);
     }
 
     public <T> Transaction start(TraceContext.ChildContextCreator<T> childContextCreator, @Nullable T parent, long epochMicros, Sampler sampler) {
@@ -125,10 +130,10 @@ public <T, A> Transaction start(TraceContext.ChildContextCreatorTwoArg<T, A> chi
     }
 
     private void onTransactionStart(boolean startedAsChild, long epochMicros, Sampler sampler) {
-        maxSpans = tracer.getConfig(CoreConfiguration.class).getTransactionMaxSpans();
-        spanCompressionEnabled = tracer.getConfig(SpanConfiguration.class).isSpanCompressionEnabled();
-        spanCompressionExactMatchMaxDurationUs = tracer.getConfig(SpanConfiguration.class).getSpanCompressionExactMatchMaxDuration().getMicros();
-        spanCompressionSameKindMaxDurationUs = tracer.getConfig(SpanConfiguration.class).getSpanCompressionSameKindMaxDuration().getMicros();
+        maxSpans = coreConfig.getTransactionMaxSpans();
+        spanCompressionEnabled = spanConfig.isSpanCompressionEnabled();
+        spanCompressionExactMatchMaxDurationUs = spanConfig.getSpanCompressionExactMatchMaxDuration().getMicros();
+        spanCompressionSameKindMaxDurationUs = spanConfig.getSpanCompressionSameKindMaxDuration().getMicros();
         if (!startedAsChild) {
             traceContext.asRootSpan(sampler);
         }
@@ -374,6 +379,17 @@ public long getSpanCompressionSameKindMaxDurationUs() {
         return spanCompressionSameKindMaxDurationUs;
     }
 
+    @Override
+    public StringBuilder getNameForSerialization() {
+        StringBuilder name = this.name;
+        WildcardMatcher match = WildcardMatcher.anyMatch(coreConfig.getTransactionNameGroups(), name);
+        if (match != null) {
+            name.setLength(0);
+            name.append(match);
+        }
+        return name;
+    }
+
     @Override
     protected Transaction thiz() {
         return this;

apm-agent-core/src/main/java/co/elastic/apm/agent/matcher/WildcardMatcher.java

@@ -164,7 +164,7 @@ public static boolean isNoneMatch(List<WildcardMatcher> matchers, @Nullable Char
      */
     @Nullable
     public static WildcardMatcher anyMatch(List<WildcardMatcher> matchers, @Nullable CharSequence s) {
-        if (s == null) {
+        if (s == null || matchers.isEmpty()) {
             return null;
         }
         return anyMatch(matchers, s, null);

apm-agent-core/src/test/java/co/elastic/apm/agent/impl/ElasticApmTracerTest.java

@@ -32,13 +32,13 @@
 import co.elastic.apm.agent.impl.transaction.TraceContext;
 import co.elastic.apm.agent.impl.transaction.Transaction;
 import co.elastic.apm.agent.matcher.WildcardMatcher;
+import co.elastic.apm.agent.metrics.Labels;
 import co.elastic.apm.agent.objectpool.TestObjectPoolFactory;
 import co.elastic.apm.agent.report.ApmServerClient;
 import co.elastic.apm.agent.report.ReporterConfiguration;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
-import org.mockito.Mockito;
 import org.stagemonitor.configuration.ConfigurationRegistry;
 
 import javax.annotation.Nullable;
@@ -224,6 +224,28 @@ void testDoesNotRecordIgnoredExceptions() {
         assertThat(reporter.getErrors()).isEmpty();
     }
 
+    @Test
+    void testTransactionNameGrouping() {
+        when(config.getConfig(CoreConfiguration.class).getTransactionNameGroups())
+            .thenReturn(List.of(WildcardMatcher.valueOf("GET /foo/*/bar")));
+
+        Transaction transaction = tracerImpl.startRootTransaction(null).appendToName("GET ").appendToName("/foo/42/bar");
+        try (Scope scope = transaction.activateInScope()) {
+            transaction.captureException(new RuntimeException("Test error capturing"));
+        }
+        transaction.end();
+        assertThat(reporter.getFirstTransaction().getNameAsString()).isEqualTo("GET /foo/*/bar");
+        assertThat(reporter.getFirstError().getTransactionInfo().getName().toString()).isEqualTo("GET /foo/*/bar");
+        tracerImpl.getMetricRegistry().flipPhaseAndReport(metricSets -> {
+            assertThat(metricSets.get(Labels.Mutable.of()
+                .transactionName("GET /foo/*/bar")
+                .transactionType("custom")
+                .spanType("app")))
+                .isNotNull();
+        });
+
+    }
+
     private static class DummyException1 extends Exception {
         DummyException1() {
         }

docs/configuration.asciidoc

@@ -131,6 +131,7 @@ Click on a key to get more information.
 ** <<config-span-min-duration>>
 ** <<config-cloud-provider>>
 ** <<config-enable-public-api-annotation-inheritance>>
+** <<config-transaction-name-groups>>
 * <<config-http>>
 ** <<config-capture-body-content-types>>
 ** <<config-transaction-ignore-urls>>
@@ -1371,6 +1372,39 @@ A boolean specifying if the agent should search the class hierarchy for public a
 | `elastic.apm.enable_public_api_annotation_inheritance` | `enable_public_api_annotation_inheritance` | `ELASTIC_APM_ENABLE_PUBLIC_API_ANNOTATION_INHERITANCE`
 |============
 
+// This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter
+[float]
+[[config-transaction-name-groups]]
+==== `transaction_name_groups` (added[1.33.0])
+
+With this option,
+you can group transaction names that contain dynamic parts with a wildcard expression.
+For example,
+the pattern `GET /user/*/cart` would consolidate transactions,
+such as `GET /users/42/cart` and `GET /users/73/cart` into a single transaction name `GET /users/*/cart`,
+hence reducing the transaction name cardinality.
+
+This option supports the wildcard `*`, which matches zero or more characters.
+Examples: `/foo/*/bar/*/baz*`, `*foo*`.
+Matching is case insensitive by default.
+Prepending an element with `(?-i)` makes the matching case sensitive.
+
+<<configuration-dynamic, image:./images/dynamic-config.svg[] >>
+
+
+[options="header"]
+|============
+| Default                          | Type                | Dynamic
+| `<none>` | List | true
+|============
+
+
+[options="header"]
+|============
+| Java System Properties      | Property file   | Environment
+| `elastic.apm.transaction_name_groups` | `transaction_name_groups` | `ELASTIC_APM_TRANSACTION_NAME_GROUPS`
+|============
+
 [[config-http]]
 === HTTP configuration options
 // This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter
@@ -1477,7 +1511,7 @@ transaction names of unsupported or partially-supported frameworks will be in th
 WARNING: If your URLs contain path parameters like `/user/$userId`,
 you should be very careful when enabling this flag,
 as it can lead to an explosion of transaction groups.
-Take a look at the `url_groups` option on how to mitigate this problem by grouping URLs together.
+Take a look at the <<config-transaction-name-groups,`transaction_name_groups`>> option on how to mitigate this problem by grouping URLs together.
 
 <<configuration-dynamic, image:./images/dynamic-config.svg[] >>
 
@@ -1498,7 +1532,9 @@ Take a look at the `url_groups` option on how to mitigate this problem by groupi
 // This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter
 [float]
 [[config-url-groups]]
-==== `url_groups`
+==== `url_groups` (deprecated)
+
+Deprecated in favor of <<config-transaction-name-groups,`transaction_name_groups`>>.
 
 This option is only considered, when `use_path_as_transaction_name` is active.
 
@@ -3476,6 +3512,24 @@ Example: `5ms`.
 #
 # enable_public_api_annotation_inheritance=false
 
+# With this option,
+# you can group transaction names that contain dynamic parts with a wildcard expression.
+# For example,
+# the pattern `GET /user/*/cart` would consolidate transactions,
+# such as `GET /users/42/cart` and `GET /users/73/cart` into a single transaction name `GET /users/*/cart`,
+# hence reducing the transaction name cardinality.
+# 
+# This option supports the wildcard `*`, which matches zero or more characters.
+# Examples: `/foo/*/bar/*/baz*`, `*foo*`.
+# Matching is case insensitive by default.
+# Prepending an element with `(?-i)` makes the matching case sensitive.
+#
+# This setting can be changed at runtime
+# Type: comma separated list
+# Default value: 
+#
+# transaction_name_groups=
+
 ############################################
 # HTTP                                     #
 ############################################
@@ -3534,14 +3588,16 @@ Example: `5ms`.
 # WARNING: If your URLs contain path parameters like `/user/$userId`,
 # you should be very careful when enabling this flag,
 # as it can lead to an explosion of transaction groups.
-# Take a look at the `url_groups` option on how to mitigate this problem by grouping URLs together.
+# Take a look at the <<config-transaction-name-groups,`transaction_name_groups`>> option on how to mitigate this problem by grouping URLs together.
 #
 # This setting can be changed at runtime
 # Type: Boolean
 # Default value: false
 #
 # use_path_as_transaction_name=false
 
+# Deprecated in favor of <<config-transaction-name-groups,`transaction_name_groups`>>.
+# 
 # This option is only considered, when `use_path_as_transaction_name` is active.
 # 
 # With this option, you can group several URL paths together by using a wildcard expression like `/user/*`.