Prepare release notes and docs for 1.8.0 (#757)

Author: felixbarny

CHANGELOG.md

@@ -1,16 +1,34 @@
-# next (1.8.0)
+# 1.8.0
 
 ## Features
- * Add support for Spring's JMS flavor - instrumenting `org.springframework.jms.listener.SessionAwareMessageListener`
- * Add support to legacy ApacheHttpClient APIs (which adds support to Axis2 configured to use ApacheHttpClient)
- * Added support for setting `server_urls` dynamically via properties file [#723](https://github.com/elastic/apm-agent-java/issues/723)
- * Add [`config_file`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-config-file) option 
+ * Added support for tracking [time spent by span type](https://www.elastic.co/guide/en/kibana/7.3/transactions.html).
+   Can be disabled by setting [`breakdown_metrics`](https://www.elastic.co/guide/en/apm/agent/java/7.3/config-core.html#config-breakdown-metrics) to `false`. 
+ * Added support for [central configuration](https://www.elastic.co/guide/en/kibana/7.3/agent-configuration.html).
+   Can be disabled by setting [`central_config`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-central-config) to `false`.
+ * Added support for Spring's JMS flavor - instrumenting `org.springframework.jms.listener.SessionAwareMessageListener`
+ * Added support to legacy ApacheHttpClient APIs (which adds support to Axis2 configured to use ApacheHttpClient)
+ * Added support for setting [`server_urls`](https://www.elastic.co/guide/en/apm/agent/java/1.x/config-reporter.html#config-server-urls) dynamically via properties file [#723](https://github.com/elastic/apm-agent-java/issues/723)
+ * Added [`config_file`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-config-file) option 
+ * Added option to use `@javax.ws.rs.Path` value as transaction name [`use_jaxrs_path_as_transaction_name`](https://www.elastic.co/guide/en/apm/agent/java/current/config-jax-rs.html#config-use-jaxrs-path-as-transaction-name)
+ * Instrument quartz jobs ([docs](https://www.elastic.co/guide/en/apm/agent/java/current/supported-technologies-details.html#supported-scheduling-frameworks))
+ * SQL parsing improvements (#696)
+ * Introduce priorities for transaction name (#748)
+ 
+   Now uses the path as transaction name if [`use_path_as_transaction_name`](https://www.elastic.co/guide/en/apm/agent/java/current/config-http.html#config-use-path-as-transaction-name) is set to `true`
+   rather than `ServletClass#doGet`.
+   But if a name can be determined from a high level framework,
+   like Spring MVC, that takes precedence.
+   User-supplied names from the API always take precedence over any others.
+ * Use JSP path name as transaction name as opposed to the generated servlet class name (#751)
+
 
 ## Bug Fixes
  * Some JMS Consumers and Producers are filtered due to class name filtering in instrumentation matching
  * Jetty: When no display name is set and context path is "/" transaction service names will now correctly fall back to configured values
  * JDBC's `executeBatch` is not traced
  * Drops non-String labels when connected to APM Server < 6.7 to avoid validation errors (#687)
+ * Parsing container ID in cloud foundry garden (#695)
+ * Automatic instrumentation should not override manual results (#752)
 
 ## Breaking changes
  * The log correlation feature does not add `span.id` to the MDC anymore but only `trace.id` and `transaction.id` (see #742).

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

@@ -341,6 +341,7 @@ public class CoreConfiguration extends ConfigurationOptionProvider {
 
     private final ConfigurationOption<String> appendPackagesToBootDelagationProperty = ConfigurationOption.stringOption()
         .key("boot_delegation_packages")
+        .tags("added[1.7.0]")
         .configurationCategory(CORE_CATEGORY)
         .description("A comma-separated list of packages to be appended to the boot delegation system property. \n" +
             "If set with an empty string, nothing will be appended to the boot delegation system property.\n" +
@@ -361,19 +362,22 @@ public class CoreConfiguration extends ConfigurationOptionProvider {
 
     private final ConfigurationOption<Boolean> centralConfig = ConfigurationOption.booleanOption()
         .key("central_config")
+        .tags("added[1.8.0]")
         .configurationCategory(CORE_CATEGORY)
         .description("When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration.")
         .dynamic(true)
         .buildWithDefault(true);
 
     private final ConfigurationOption<Boolean> breakdownMetrics = ConfigurationOption.booleanOption()
         .key("breakdown_metrics")
+        .tags("added[1.8.0]")
         .configurationCategory(CORE_CATEGORY)
         .description("Disables the collection of breakdown metrics (`span.self_time`)")
         .buildWithDefault(true);
 
     private final ConfigurationOption<String> configFileLocation = ConfigurationOption.stringOption()
         .key(CONFIG_FILE)
+        .tags("added[1.8.0]")
         .configurationCategory(CORE_CATEGORY)
         .description("Sets the path of the agent config file.\n" +
             "The special value `_AGENT_HOME_` is a placeholder for the folder the elastic-apm-agent.jar is in.\n" +

apm-agent-core/src/main/java/co/elastic/apm/agent/report/ReporterConfiguration.java

@@ -67,7 +67,9 @@ public class ReporterConfiguration extends ConfigurationOptionProvider {
             "\n" +
             "If outgoing HTTP traffic has to go through a proxy," +
             "you can use the Java system properties `http.proxyHost` and `http.proxyPort` to set that up.\n" +
-            "See also [Java's proxy documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) for more information.")
+            "See also [Java's proxy documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) for more information.\n" +
+            "\n" +
+            "NOTE: This configuration can only be reloaded dynamically as of 1.8.0")
         .dynamic(true)
         .buildWithDefault(Collections.singletonList(UrlValueConverter.INSTANCE.convert("http://localhost:8200")));
 

apm-agent-plugins/apm-jaxrs-plugin/src/main/java/co/elastic/apm/agent/jaxrs/JaxRsConfiguration.java

@@ -45,7 +45,8 @@ public class JaxRsConfiguration extends ConfigurationOptionProvider {
         .buildWithDefault(true);
 
     private final ConfigurationOption<Boolean> useAnnotationValueForTransactionName = ConfigurationOption.booleanOption()
-        .key("use_jaxrs_path_for_transaction_name")
+        .key("use_jaxrs_path_as_transaction_name")
+        .tags("added[1.8.0]")
         .configurationCategory(JAXRS_CATEGORY)
         .description("By default, the agent will use `ClassName#methodName` for the transaction name of JAX-RS requests.\n" +
             "If you want to use the URI template from the `@Path` annotation, set the value to `true`.")

docs/configuration.asciidoc

@@ -73,8 +73,9 @@ Click on a key to get more information.
 ** <<config-trace-methods>>
 ** <<config-trace-methods-duration-threshold>>
 ** <<config-boot-delegation-packages>>
+** <<config-central-config>>
 ** <<config-breakdown-metrics>>
-** <<config-config-file-location>>
+** <<config-config-file>>
 * <<config-http>>
 ** <<config-capture-body>>
 ** <<config-capture-body-content-types>>
@@ -85,7 +86,7 @@ Click on a key to get more information.
 ** <<config-url-groups>>
 * <<config-jax-rs>>
 ** <<config-enable-jaxrs-annotation-inheritance>>
-** <<config-use-jaxrs-path-for-transaction-name>>
+** <<config-use-jaxrs-path-as-transaction-name>>
 * <<config-logging>>
 ** <<config-log-level>>
 ** <<config-log-file>>
@@ -483,7 +484,7 @@ The default unit for this option is `ms`
 
 [float]
 [[config-boot-delegation-packages]]
-==== `boot_delegation_packages`
+==== `boot_delegation_packages` (added[1.7.0])
 
 A comma-separated list of packages to be appended to the boot delegation system property. 
 If set with an empty string, nothing will be appended to the boot delegation system property.
@@ -516,9 +517,29 @@ boot_delegation_packages=org.apache.karaf.jaas.boot, org.apache.karaf.jaas.boot.
 | `elastic.apm.boot_delegation_packages` | `boot_delegation_packages` | `ELASTIC_APM_BOOT_DELEGATION_PACKAGES`
 |============
 
+[float]
+[[config-central-config]]
+==== `central_config` (added[1.8.0])
+
+When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration.
+
+
+[options="header"]
+|============
+| Default                          | Type                | Dynamic
+| `true` | Boolean | true
+|============
+
+
+[options="header"]
+|============
+| Java System Properties      | Property file   | Environment
+| `elastic.apm.central_config` | `central_config` | `ELASTIC_APM_CENTRAL_CONFIG`
+|============
+
 [float]
 [[config-breakdown-metrics]]
-==== `breakdown_metrics`
+==== `breakdown_metrics` (added[1.8.0])
 
 Disables the collection of breakdown metrics (`span.self_time`)
 
@@ -537,8 +558,8 @@ Disables the collection of breakdown metrics (`span.self_time`)
 |============
 
 [float]
-[[config-config-file-location]]
-==== `config_file_location`
+[[config-config-file]]
+==== `config_file` (added[1.8.0])
 
 Sets the path of the agent config file.
 The special value `_AGENT_HOME_` is a placeholder for the folder the elastic-apm-agent.jar is in.
@@ -555,7 +576,7 @@ The location can either be in the classpath of the application or on the file sy
 [options="header"]
 |============
 | Java System Properties      | Property file   | Environment
-| `elastic.apm.config_file_location` | `config_file_location` | `ELASTIC_APM_CONFIG_FILE_LOCATION`
+| `elastic.apm.config_file` | `config_file` | `ELASTIC_APM_CONFIG_FILE`
 |============
 
 [[config-http]]
@@ -782,8 +803,8 @@ If your application does not use @Path annotation inheritance, set this property
 |============
 
 [float]
-[[config-use-jaxrs-path-for-transaction-name]]
-==== `use_jaxrs_path_for_transaction_name`
+[[config-use-jaxrs-path-as-transaction-name]]
+==== `use_jaxrs_path_as_transaction_name` (added[1.8.0])
 
 By default, the agent will use `ClassName#methodName` for the transaction name of JAX-RS requests.
 If you want to use the URI template from the `@Path` annotation, set the value to `true`.
@@ -799,7 +820,7 @@ If you want to use the URI template from the `@Path` annotation, set the value t
 [options="header"]
 |============
 | Java System Properties      | Property file   | Environment
-| `elastic.apm.use_jaxrs_path_for_transaction_name` | `use_jaxrs_path_for_transaction_name` | `ELASTIC_APM_USE_JAXRS_PATH_FOR_TRANSACTION_NAME`
+| `elastic.apm.use_jaxrs_path_as_transaction_name` | `use_jaxrs_path_as_transaction_name` | `ELASTIC_APM_USE_JAXRS_PATH_AS_TRANSACTION_NAME`
 |============
 
 [[config-logging]]
@@ -862,7 +883,8 @@ it's content is deleted when the application starts.
 A boolean specifying if the agent should integrate into SLF4J's https://www.slf4j.org/api/org/slf4j/MDC.html[MDC] to enable trace-log correlation.
 If set to `true`, the agent will set the `trace.id` and `transaction.id` for the currently active spans and transactions to the MDC.
 You can then use the pattern format of your logging implementation to write the MDC values to your log file.
-If you are using logback or log4j, add `%X` to the format to log all MDC values or `%X{trace.id}` to only log the trace id.With the help of Filebeat and Logstash or an Elasticsearch ingest pipeline,
+If you are using logback or log4j, add `%X` to the format to log all MDC values or `%X{trace.id}` to only log the trace id.
+With the help of Filebeat and Logstash or an Elasticsearch ingest pipeline,
 you can index your log files and correlate them with APM traces.
 With this integration you can get all logs belonging to a particular trace and vice-versa:
 for a specific log, see in which context it has been logged and which parameters the user provided. 
@@ -920,6 +942,8 @@ When multiple agents are active, they'll tend towards spreading evenly across th
 If outgoing HTTP traffic has to go through a proxy,you can use the Java system properties `http.proxyHost` and `http.proxyPort` to set that up.
 See also [Java's proxy documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) for more information.
 
+NOTE: This configuration can only be reloaded dynamically as of 1.8.0
+
 
 [options="header"]
 |============
@@ -1459,6 +1483,14 @@ The default unit for this option is `ms`
 #
 # boot_delegation_packages=co.elastic.apm.agent.*
 
+# When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration.
+#
+# This setting can be changed at runtime
+# Type: Boolean
+# Default value: true
+#
+# central_config=true
+
 # Disables the collection of breakdown metrics (`span.self_time`)
 #
 # This setting can not be changed at runtime. Changes require a restart of the application.
@@ -1475,7 +1507,7 @@ The default unit for this option is `ms`
 # Type: String
 # Default value: _AGENT_HOME_/elasticapm.properties
 #
-# config_file_location=_AGENT_HOME_/elasticapm.properties
+# config_file=_AGENT_HOME_/elasticapm.properties
 
 ############################################
 # HTTP                                     #
@@ -1615,7 +1647,7 @@ The default unit for this option is `ms`
 # Type: Boolean
 # Default value: false
 #
-# use_jaxrs_path_for_transaction_name=false
+# use_jaxrs_path_as_transaction_name=false
 
 ############################################
 # Logging                                  #
@@ -1651,7 +1683,8 @@ The default unit for this option is `ms`
 # A boolean specifying if the agent should integrate into SLF4J's https://www.slf4j.org/api/org/slf4j/MDC.html[MDC] to enable trace-log correlation.
 # If set to `true`, the agent will set the `trace.id` and `transaction.id` for the currently active spans and transactions to the MDC.
 # You can then use the pattern format of your logging implementation to write the MDC values to your log file.
-# If you are using logback or log4j, add `%X` to the format to log all MDC values or `%X{trace.id}` to only log the trace id.With the help of Filebeat and Logstash or an Elasticsearch ingest pipeline,
+# If you are using logback or log4j, add `%X` to the format to log all MDC values or `%X{trace.id}` to only log the trace id.
+# With the help of Filebeat and Logstash or an Elasticsearch ingest pipeline,
 # you can index your log files and correlate them with APM traces.
 # With this integration you can get all logs belonging to a particular trace and vice-versa:
 # for a specific log, see in which context it has been logged and which parameters the user provided. 
@@ -1688,6 +1721,8 @@ The default unit for this option is `ms`
 # 
 # If outgoing HTTP traffic has to go through a proxy,you can use the Java system properties `http.proxyHost` and `http.proxyPort` to set that up.
 # See also [Java's proxy documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) for more information.
+# 
+# NOTE: This configuration can only be reloaded dynamically as of 1.8.0
 #
 # This setting can be changed at runtime
 # Type: comma separated list