renamed span_frames_min_duration to span_stack_trace_min_duration. Ch…

CHANGELOG.asciidoc

@@ -45,6 +45,9 @@ by the agent may be different. This was done in order to improve the integration
 * Add support for Spring AMQP batch API - {pull}1716[#1716]
 * Add the (current) transaction name to the error (when using APM Server 8.0) - {pull}2235[#2235]
 * The JVM/JMX metrics are reported for each service name individually (when using APM Server 8.0) - {pull}2233[#2233]
+* Added <<config-span-stack-trace-min-duration,`span_stack_trace_min_duration`>> option.
+ This replaces the now deprecated `span_frames_min_duration` option.
+ The difference is that the new option has more intuitive semantics for negative values (never collect stack trace) and zero (always collect stack trace). - {pull}2220[#2220]
 
 [float]
 ===== Performance improvements

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

@@ -466,7 +466,7 @@ public class CoreConfiguration extends ConfigurationOptionProvider {
  "Also note that there is a maximum amount of spans per transaction (see <<config-transaction-max-spans, `transaction_max_spans`>>).\n" +
  "\n" +
  "NOTE: The agent will create stack traces for spans which took longer than\n" +
- "<<config-span-frames-min-duration, `span_frames_min_duration`>>.\n" +
+ "<<config-span-stack-trace-min-duration, `span_stack_trace_min_duration`>>.\n" +
  "When tracing a large number of methods (for example by using wildcards),\n" +
  "this may lead to high overhead.\n" +
  "Consider increasing the threshold or disabling stack trace collection altogether.\n\n" +

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

@@ -407,9 +407,10 @@ private void reportSpan(Span span) {
  }
  // makes sure that parents are also non-discardable
  span.setNonDiscardable();
- long spanFramesMinDurationMs = stacktraceConfiguration.getSpanFramesMinDurationMs();
- if (spanFramesMinDurationMs != 0 && span.isSampled() && span.getStackFrames() == null) {
- if (span.getDurationMs() >= spanFramesMinDurationMs) {
+
+ long spanStackTraceMinDurationMs = stacktraceConfiguration.getSpanStackTraceMinDurationMs();
+ if (spanStackTraceMinDurationMs >= 0 && span.isSampled() && span.getStackFrames() == null) {
+ if (span.getDurationMs() >= spanStackTraceMinDurationMs) {
  span.withStacktrace(new Throwable());
  }
  }

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/stacktrace/StacktraceConfiguration.java

@@ -67,7 +67,7 @@ public class StacktraceConfiguration extends ConfigurationOptionProvider {
  private final ConfigurationOption<TimeDuration> spanFramesMinDurationMs = TimeDurationValueConverter.durationOption("ms")
  .key("span_frames_min_duration")
  .aliasKeys("span_frames_min_duration_ms")
- .tags("performance")
+ .tags("internal", "deprecated")
  .configurationCategory(STACKTRACE_CATEGORY)
  .description("While this is very helpful to find the exact place in your code that causes the span, " +
  "collecting this stack trace does have some overhead. " +
@@ -80,6 +80,21 @@ public class StacktraceConfiguration extends ConfigurationOptionProvider {
  .dynamic(true)
  .buildWithDefault(TimeDuration.of("5ms"));
 
+ private final ConfigurationOption<TimeDuration> spanStackTraceMinDurationMs = TimeDurationValueConverter.durationOption("ms")
+ .key("span_stack_trace_min_duration")
+ .tags("performance")
+ .configurationCategory(STACKTRACE_CATEGORY)
+ .description("While this is very helpful to find the exact place in your code that causes the span, " +
+ "collecting this stack trace does have some overhead. " +
+ "\n" +
+ "When setting this option to value `0ms`, stack traces will be collected for all spans. " +
+ "Setting it to a positive value, e.g. `5ms`, will limit stack trace collection to spans " +
+ "with durations equal to or longer than the given value, e.g. 5 milliseconds.\n" +
+ "\n" +
+ "To disable stack trace collection for spans completely, set the value to `-1ms`.")
+ .dynamic(true)
+ .buildWithDefault(TimeDuration.of("5ms"));
+
  public Collection<String> getApplicationPackages() {
  return applicationPackages.get();
  }
@@ -88,7 +103,17 @@ public int getStackTraceLimit() {
  return stackTraceLimit.get();
  }
 
- public long getSpanFramesMinDurationMs() {
- return spanFramesMinDurationMs.getValue().getMillis();
+ public long getSpanStackTraceMinDurationMs() {
+ if (spanStackTraceMinDurationMs.isDefault() && !spanFramesMinDurationMs.isDefault()) {
+ long spanFramesMinDurationMsValue = spanFramesMinDurationMs.getValue().getMillis();
+ if (spanFramesMinDurationMsValue == 0) {
+ return -1;
+ } else if (spanFramesMinDurationMsValue < 0) {
+ return 0;
+ } else {
+ return spanFramesMinDurationMsValue;
+ }
+ }
+ return spanStackTraceMinDurationMs.getValue().getMillis();
  }
 }

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

@@ -119,7 +119,8 @@ void testNestedSpan() {
 
  @Test
  void testDisableStacktraces() {
- when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanFramesMinDurationMs()).thenReturn(0L);
+ when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs()).thenReturn(-1L);
+
  Transaction transaction = startTestRootTransaction();
  try (Scope scope = transaction.activateInScope()) {
  Span span = tracerImpl.getActive().createSpan();
@@ -133,7 +134,7 @@ void testDisableStacktraces() {
 
  @Test
  void testEnableStacktraces() throws InterruptedException {
- when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanFramesMinDurationMs()).thenReturn(-1L);
+ when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs()).thenReturn(0L);
  Transaction transaction = startTestRootTransaction();
  try (Scope scope = transaction.activateInScope()) {
  Span span = tracerImpl.getActive().createSpan();
@@ -148,7 +149,7 @@ void testEnableStacktraces() throws InterruptedException {
 
  @Test
  void testDisableStacktracesForFastSpans() {
- when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanFramesMinDurationMs()).thenReturn(100L);
+ when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs()).thenReturn(100L);
  Transaction transaction = startTestRootTransaction();
  try (Scope scope = transaction.activateInScope()) {
  Span span = tracerImpl.getActive().createSpan();
@@ -163,7 +164,7 @@ void testDisableStacktracesForFastSpans() {
 
  @Test
  void testEnableStacktracesForSlowSpans() throws InterruptedException {
- when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanFramesMinDurationMs()).thenReturn(1L);
+ when(tracerImpl.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs()).thenReturn(1L);
  Transaction transaction = startTestRootTransaction();
  try (Scope scope = transaction.activateInScope()) {
  Span span = tracerImpl.getActive().createSpan();

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

@@ -0,0 +1,69 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.impl.stacktrace;
+
+import co.elastic.apm.agent.configuration.SpyConfiguration;
+import org.junit.jupiter.api.Test;
+import org.stagemonitor.configuration.ConfigurationRegistry;
+import org.stagemonitor.configuration.source.SimpleSource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class StacktraceConfigurationTest {
+
+ @Test
+ void testGetSpanStackTraceMinDurationMs_whenSpanStackTraceMinDurationNonDefault_thenGetValueFromSpanStackTraceMinDuration() {
+ ConfigurationRegistry configRegistry = SpyConfiguration.createSpyConfig(SimpleSource.forTest("span_frames_min_duration", "10ms").add("span_stack_trace_min_duration", "15ms"));
+
+ long actual = configRegistry.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs();
+ assertThat(actual).isEqualTo(15);
+ }
+
+ @Test
+ void testGetSpanStackTraceMinDurationMs_whenSpanStackTraceDefault_whenSpanFramesNonDefault_thenGetValueFromSpanFramesMinDuration() {
+ ConfigurationRegistry configRegistry = SpyConfiguration.createSpyConfig(SimpleSource.forTest("span_frames_min_duration", "15ms"));
+
+ long actual = configRegistry.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs();
+ assertThat(actual).isEqualTo(15);
+ }
+
+ @Test
+ void testGetSpanStackTraceMinDurationMs_whenSpanStackTraceDefault_whenSpanFramesMinDurationIsZero_thenGetSwappedValueOfSpanFramesMinDuration() {
+ ConfigurationRegistry configRegistry = SpyConfiguration.createSpyConfig(SimpleSource.forTest("span_frames_min_duration", "0ms"));
+
+ long actual = configRegistry.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs();
+ assertThat(actual).isEqualTo(-1);
+ }
+
+ @Test
+ void testGetSpanStackTraceMinDurationMs_whenSpanStackTraceDefault_whenSpanFramesMinDurationIsNegative_thenGetSwappedValueOfSpanFramesMinDuration() {
+ ConfigurationRegistry configRegistry = SpyConfiguration.createSpyConfig(SimpleSource.forTest("span_frames_min_duration", "-1ms"));
+
+ long actual = configRegistry.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs();
+ assertThat(actual).isEqualTo(0);
+ }
+
+ @Test
+ void testGetSpanStackTraceMinDurationMs_defaultValue() {
+ ConfigurationRegistry configRegistry = SpyConfiguration.createSpyConfig();
+
+ long actual = configRegistry.getConfig(StacktraceConfiguration.class).getSpanStackTraceMinDurationMs();
+ assertThat(actual).isEqualTo(5);
+ }
+}

apm-agent-core/src/test/java/org/example/stacktrace/StacktraceSerializationTest.java

@@ -58,7 +58,7 @@ void setUp() throws IOException {
  tracer = MockTracer.createRealTracer();
  stacktraceConfiguration = tracer.getConfig(StacktraceConfiguration.class);
  // always enable
- when(stacktraceConfiguration.getSpanFramesMinDurationMs()).thenReturn(-1L);
+ when(stacktraceConfiguration.getSpanStackTraceMinDurationMs()).thenReturn(0L);
  serializer = new DslJsonSerializer(stacktraceConfiguration, mock(ApmServerClient.class), tracer.getMetaData());
  objectMapper = new ObjectMapper();
  stacktrace = getStackTrace();

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/main/java/co/elastic/apm/agent/rabbitmq/AmqpConstants.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 public class AmqpConstants {

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/main/java/co/elastic/apm/agent/rabbitmq/MessageBatchHelper.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 import co.elastic.apm.agent.impl.ElasticApmTracer;

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/main/java/co/elastic/apm/agent/rabbitmq/MessageBatchIteratorWrapper.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/main/java/co/elastic/apm/agent/rabbitmq/MessageBatchListWrapper.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/main/java/co/elastic/apm/agent/rabbitmq/SpringAmqpBatchMessageListenerInstrumentation.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/main/java/co/elastic/apm/agent/rabbitmq/SpringAmqpTransactionHelper.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 import co.elastic.apm.agent.impl.ElasticApmTracer;

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/test/java/co/elastic/apm/agent/rabbitmq/SpringAmqpBatchTest.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq;
 
 

apm-agent-plugins/apm-rabbitmq/apm-rabbitmq-spring/src/test/java/co/elastic/apm/agent/rabbitmq/config/BatchConfiguration.java

@@ -1,3 +1,21 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 co.elastic.apm.agent.rabbitmq.config;