Merge pull request #211638 from trask/update-to-3.4.0

Update to 3.4.0

Author: LJSpiller

articles/azure-monitor/app/java-in-process-agent.md

@@ -30,23 +30,29 @@ This section shows you how to download the auto-instrumentation jar file.
 
 #### Download the jar file
 
-Download the [applicationinsights-agent-3.3.1.jar](https://github.com/microsoft/ApplicationInsights-Java/releases/download/3.3.1/applicationinsights-agent-3.3.1.jar) file.
+Download the [applicationinsights-agent-3.4.0.jar](https://github.com/microsoft/ApplicationInsights-Java/releases/download/3.4.0/applicationinsights-agent-3.4.0.jar) file.
 
 > [!WARNING]
-> 
-> If you're upgrading from 3.2.x:
-> 
->    -  Starting from 3.3.0, `LoggingLevel` is not captured by default as part of Traces' custom dimension since that data is already captured in the `SeverityLevel` field. For details on how to re-enable this if needed, please see the [config options](./java-standalone-config.md#logginglevel)
+>
+> If you are upgrading from an earlier 3.x version,
+>
+> Starting from 3.4.0:
+>
+>    - Rate-limited sampling is now the default (if you have not configured a fixed percentage previously). By default, it will capture at most around 5 requests per second (along with their dependencies, traces and custom events). See [fixed-percentage sampling](./java-standalone-config.md#fixed-percentage-sampling) if you wish to revert to the previous behavior of capturing 100% of requests.
+>
+> Starting from 3.3.0:
+>
+>    - `LoggingLevel` is not captured by default as part of Traces' custom dimension since that data is already captured in the `SeverityLevel` field. For details on how to re-enable this if needed, please see the [config options](./java-standalone-config.md#logginglevel)
 >    - Exception records are no longer recorded for failed dependencies, they are only recorded for failed requests.
 >
-> If you're upgrading from 3.1.x:
+> Starting from 3.2.0:
 > 
->    -  Starting from 3.2.0, controller "InProc" dependencies are not captured by default. For details on how to enable this, please see the [config options](./java-standalone-config.md#autocollect-inproc-dependencies-preview).
+>    - Controller "InProc" dependencies are no longer captured by default. For details on how to re-enable these, please see the [config options](./java-standalone-config.md#autocollect-inproc-dependencies-preview).
 >    - Database dependency names are now more concise with the full (sanitized) query still present in the `data` field. HTTP dependency names are now more descriptive.
 >    This change can affect custom dashboards or alerts if they relied on the previous values.
 >    For details, see the [3.2.0 release notes](https://github.com/microsoft/ApplicationInsights-Java/releases/tag/3.2.0).
 > 
-> If you're upgrading from 3.0.x:
+> Starting from 3.1.0:
 > 
 >    - The operation names and request telemetry names are now prefixed by the HTTP method, such as `GET` and `POST`.
 >    This change can affect custom dashboards or alerts if they relied on the previous values.
@@ -56,7 +62,7 @@ Download the [applicationinsights-agent-3.3.1.jar](https://github.com/microsoft/
 
 #### Point the JVM to the jar file
 
-Add `-javaagent:"path/to/applicationinsights-agent-3.3.1.jar"` to your application's JVM args.
+Add `-javaagent:"path/to/applicationinsights-agent-3.4.0.jar"` to your application's JVM args.
 
 > [!TIP]
 > For help with configuring your application's JVM args, see [Tips for updating your JVM args](./java-standalone-arguments.md).
@@ -74,7 +80,7 @@ Add `-javaagent:"path/to/applicationinsights-agent-3.3.1.jar"` to your applicati
         APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>
         ```
 
-   - Or you can create a configuration file named `applicationinsights.json`. Place it in the same directory as `applicationinsights-agent-3.3.1.jar` with the following content:
+   - Or you can create a configuration file named `applicationinsights.json`. Place it in the same directory as `applicationinsights-agent-3.4.0.jar` with the following content:
 
         ```json
         {

articles/azure-monitor/app/java-spring-boot.md

@@ -15,24 +15,24 @@ You can enable the Azure Monitor Application Insights agent for Java by adding a
 
 ### Usual case
 
-Add the JVM arg `-javaagent:"path/to/applicationinsights-agent-3.3.1.jar"` somewhere before `-jar`, for example:
+Add the JVM arg `-javaagent:"path/to/applicationinsights-agent-3.4.0.jar"` somewhere before `-jar`, for example:
 
 ```
-java -javaagent:"path/to/applicationinsights-agent-3.3.1.jar" -jar <myapp.jar>
+java -javaagent:"path/to/applicationinsights-agent-3.4.0.jar" -jar <myapp.jar>
 ```
 
 ### Spring Boot via Docker entry point
 
-If you're using the *exec* form, add the parameter `-javaagent:"path/to/applicationinsights-agent-3.3.1.jar"` to the parameter list somewhere before the `"-jar"` parameter, for example:
+If you're using the *exec* form, add the parameter `-javaagent:"path/to/applicationinsights-agent-3.4.0.jar"` to the parameter list somewhere before the `"-jar"` parameter, for example:
 
 ```
-ENTRYPOINT ["java", "-javaagent:path/to/applicationinsights-agent-3.3.1.jar", "-jar", "<myapp.jar>"]
+ENTRYPOINT ["java", "-javaagent:path/to/applicationinsights-agent-3.4.0.jar", "-jar", "<myapp.jar>"]
 ```
 
-If you're using the *shell* form, add the JVM arg `-javaagent:"path/to/applicationinsights-agent-3.3.1.jar"` somewhere before `-jar`, for example:
+If you're using the *shell* form, add the JVM arg `-javaagent:"path/to/applicationinsights-agent-3.4.0.jar"` somewhere before `-jar`, for example:
 
 ```
-ENTRYPOINT java -javaagent:"path/to/applicationinsights-agent-3.3.1.jar" -jar <myapp.jar>
+ENTRYPOINT java -javaagent:"path/to/applicationinsights-agent-3.4.0.jar" -jar <myapp.jar>
 ```
 
 ## Programmatic configuration
@@ -42,7 +42,7 @@ To use the programmatic configuration and attach the Application Insights agent
 <dependency>
     <groupId>com.microsoft.azure</groupId>
     <artifactId>applicationinsights-runtime-attach</artifactId>
-    <version>3.3.1</version>
+    <version>3.4.0</version>
 </dependency>
 ```
 

articles/azure-monitor/app/java-standalone-arguments.md

@@ -25,18 +25,18 @@ Read the Spring Boot documentation [here](../app/java-in-process-agent.md).
 If you installed Tomcat via `apt-get` or `yum`, then you should have a file `/etc/tomcat8/tomcat8.conf`.  Add this line to the end of that file:
 
 ```
-JAVA_OPTS="$JAVA_OPTS -javaagent:path/to/applicationinsights-agent-3.3.1.jar"
+JAVA_OPTS="$JAVA_OPTS -javaagent:path/to/applicationinsights-agent-3.4.0.jar"
 ```
 
 ### Tomcat installed via download and unzip
 
 If you installed Tomcat via download and unzip from [https://tomcat.apache.org](https://tomcat.apache.org), then you should have a file `<tomcat>/bin/catalina.sh`.  Create a new file in the same directory named `<tomcat>/bin/setenv.sh` with the following content:
 
 ```
-CATALINA_OPTS="$CATALINA_OPTS -javaagent:path/to/applicationinsights-agent-3.3.1.jar"
+CATALINA_OPTS="$CATALINA_OPTS -javaagent:path/to/applicationinsights-agent-3.4.0.jar"
 ```
 
-If the file `<tomcat>/bin/setenv.sh` already exists, then modify that file and add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to `CATALINA_OPTS`.
+If the file `<tomcat>/bin/setenv.sh` already exists, then modify that file and add `-javaagent:path/to/applicationinsights-agent-3.4.0.jar` to `CATALINA_OPTS`.
 
 
 ## Tomcat 8 (Windows)
@@ -46,36 +46,36 @@ If the file `<tomcat>/bin/setenv.sh` already exists, then modify that file and a
 Locate the file `<tomcat>/bin/catalina.bat`.  Create a new file in the same directory named `<tomcat>/bin/setenv.bat` with the following content:
 
 ```
-set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:path/to/applicationinsights-agent-3.3.1.jar
+set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:path/to/applicationinsights-agent-3.4.0.jar
 ```
 
 Quotes aren't necessary, but if you want to include them, the proper placement is:
 
 ```
-set "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:path/to/applicationinsights-agent-3.3.1.jar"
+set "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:path/to/applicationinsights-agent-3.4.0.jar"
 ```
 
-If the file `<tomcat>/bin/setenv.bat` already exists, just modify that file and add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to `CATALINA_OPTS`.
+If the file `<tomcat>/bin/setenv.bat` already exists, just modify that file and add `-javaagent:path/to/applicationinsights-agent-3.4.0.jar` to `CATALINA_OPTS`.
 
 ### Running Tomcat as a Windows service
 
-Locate the file `<tomcat>/bin/tomcat8w.exe`.  Run that executable and add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to the `Java Options` under the `Java` tab.
+Locate the file `<tomcat>/bin/tomcat8w.exe`.  Run that executable and add `-javaagent:path/to/applicationinsights-agent-3.4.0.jar` to the `Java Options` under the `Java` tab.
 
 
 ## JBoss EAP 7
 
 ### Standalone server
 
-Add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to the existing `JAVA_OPTS` environment variable in the file `JBOSS_HOME/bin/standalone.conf` (Linux) or `JBOSS_HOME/bin/standalone.conf.bat` (Windows):
+Add `-javaagent:path/to/applicationinsights-agent-3.4.0.jar` to the existing `JAVA_OPTS` environment variable in the file `JBOSS_HOME/bin/standalone.conf` (Linux) or `JBOSS_HOME/bin/standalone.conf.bat` (Windows):
 
 ```java    ...
-    JAVA_OPTS="-javaagent:path/to/applicationinsights-agent-3.3.1.jar -Xms1303m -Xmx1303m ..."
+    JAVA_OPTS="-javaagent:path/to/applicationinsights-agent-3.4.0.jar -Xms1303m -Xmx1303m ..."
     ...
 ```
 
 ### Domain server
 
-Add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to the existing `jvm-options` in `JBOSS_HOME/domain/configuration/host.xml`:
+Add `-javaagent:path/to/applicationinsights-agent-3.4.0.jar` to the existing `jvm-options` in `JBOSS_HOME/domain/configuration/host.xml`:
 
 ```xml
 ...
@@ -85,7 +85,7 @@ Add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to the existing `jv
         <jvm-options>
             <option value="-server"/>
             <!--Add Java agent jar file here-->
-            <option value="-javaagent:path/to/applicationinsights-agent-3.3.1.jar"/>
+            <option value="-javaagent:path/to/applicationinsights-agent-3.4.0.jar"/>
             <option value="-XX:MetaspaceSize=96m"/>
             <option value="-XX:MaxMetaspaceSize=256m"/>
         </jvm-options>
@@ -125,20 +125,20 @@ Add these lines to `start.ini`
 
 ```
 --exec
--javaagent:path/to/applicationinsights-agent-3.3.1.jar
+-javaagent:path/to/applicationinsights-agent-3.4.0.jar
 ```
 
 
 ## Payara 5
 
-Add `-javaagent:path/to/applicationinsights-agent-3.3.1.jar` to the existing `jvm-options` in `glassfish/domains/domain1/config/domain.xml`:
+Add `-javaagent:path/to/applicationinsights-agent-3.4.0.jar` to the existing `jvm-options` in `glassfish/domains/domain1/config/domain.xml`:
 
 ```xml
 ...
 <java-config ...>
     <!--Edit the JVM options here-->
     <jvm-options>
-        -javaagent:path/to/applicationinsights-agent-3.3.1.jar>
+        -javaagent:path/to/applicationinsights-agent-3.4.0.jar>
     </jvm-options>
         ...
 </java-config>
@@ -155,7 +155,7 @@ Java and Process Management > Process definition >  Java Virtual Machine
 ```
 In "Generic JVM arguments" add the following JVM argument:
 ```
--javaagent:path/to/applicationinsights-agent-3.3.1.jar
+-javaagent:path/to/applicationinsights-agent-3.4.0.jar
 ```
 After that, save and restart the application server.
 
@@ -164,7 +164,7 @@ After that, save and restart the application server.
 
 Create a new file `jvm.options` in the server directory (for example `<openliberty>/usr/servers/defaultServer`), and add this line:
 ```
--javaagent:path/to/applicationinsights-agent-3.3.1.jar
+-javaagent:path/to/applicationinsights-agent-3.4.0.jar
 ```
 
 ## Others

articles/azure-monitor/app/java-standalone-config.md

@@ -32,14 +32,14 @@ You will find more details and additional configuration options below.
 
 ## Configuration file path
 
-By default, Application Insights Java 3.x expects the configuration file to be named `applicationinsights.json`, and to be located in the same directory as `applicationinsights-agent-3.3.1.jar`.
+By default, Application Insights Java 3.x expects the configuration file to be named `applicationinsights.json`, and to be located in the same directory as `applicationinsights-agent-3.4.0.jar`.
 
 You can specify your own configuration file path using either
 
 * `APPLICATIONINSIGHTS_CONFIGURATION_FILE` environment variable, or
 * `applicationinsights.configuration.file` Java system property
 
-If you specify a relative path, it will be resolved relative to the directory where `applicationinsights-agent-3.3.1.jar` is located.
+If you specify a relative path, it will be resolved relative to the directory where `applicationinsights-agent-3.4.0.jar` is located.
 
 Alternatively, instead of using a configuration file, you can specify the entire _content_ of the json configuration
 via the environment variable `APPLICATIONINSIGHTS_CONFIGURATION_CONTENT`.
@@ -62,7 +62,7 @@ You can also set the connection string using the environment variable `APPLICATI
 
 You can also set the connection string by specifying a file to load the connection string from.
 
-If you specify a relative path, it will be resolved relative to the directory where `applicationinsights-agent-3.3.1.jar` is located.
+If you specify a relative path, it will be resolved relative to the directory where `applicationinsights-agent-3.4.0.jar` is located.
 
 ```json
 {
@@ -140,10 +140,12 @@ Furthermore, sampling is trace ID based, to help ensure consistent sampling deci
 
 ### Rate-Limited Sampling
 
-Starting from 3.4.0-BETA, rate-limited sampling is available, and is now the default.
+Starting from 3.4.0, rate-limited sampling is available, and is now the default.
 
 If no sampling has been configured, the default is now rate-limited sampling configured to capture at most
-(approximately) 5 requests per second. This replaces the prior default which was to capture all requests.
+(approximately) 5 requests per second, along with all the dependencies and logs on those requests.
+
+This replaces the prior default which was to capture all requests.
 If you still wish to capture all requests, use [fixed-percentage sampling](#fixed-percentage-sampling) and set the
 sampling percentage to 100.
 
@@ -158,15 +160,15 @@ Here is an example how to set the sampling to capture at most (approximately) 1
 ```json
 {
   "sampling": {
-    "limitPerSecond": 1.0
+    "requestsPerSecond": 1.0
   }
 }
 ```
 
-Note that `limitPerSecond` can be a decimal, so you can configure it to capture less than one request per second if you
-wish.
+Note that `requestsPerSecond` can be a decimal, so you can configure it to capture less than one request per second if you wish.
+For example, a value of `0.5` means capture at most 1 request every 2 seconds.
 
-You can also set the sampling percentage using the environment variable `APPLICATIONINSIGHTS_SAMPLING_LIMIT_PER_SECOND`
+You can also set the sampling percentage using the environment variable `APPLICATIONINSIGHTS_SAMPLING_REQUESTS_PER_SECOND`
 (which will then take precedence over rate limit specified in the json configuration).
 
 ### Fixed-Percentage Sampling
@@ -266,7 +268,7 @@ Starting from version 3.2.0, if you want to set a custom dimension programmatica
 
 ## Connection string overrides (preview)
 
-This feature is in preview, starting from 3.4.0-BETA.
+This feature is in preview, starting from 3.4.0.
 
 Connection string overrides allow you to override the [default connection string](#connection-string), for example:
 * Set one connection string for one http path prefix `/myapp1`.
@@ -479,7 +481,7 @@ To disable auto-collection of Micrometer metrics (including Spring Boot Actuator
 
 Literal values in JDBC queries are masked by default in order to avoid accidentally capturing sensitive data.
 
-Starting from 3.4.0-BETA, this behavior can be disabled if desired, e.g.
+Starting from 3.4.0, this behavior can be disabled if desired, e.g.
 
 ```json
 {
@@ -493,6 +495,24 @@ Starting from 3.4.0-BETA, this behavior can be disabled if desired, e.g.
 }
 ```
 
+## Mongo query masking
+
+Literal values in Mongo queries are masked by default in order to avoid accidentally capturing sensitive data.
+
+Starting from 3.4.0, this behavior can be disabled if desired, e.g.
+
+```json
+{
+  "instrumentation": {
+    "mongo": {
+      "masking": {
+        "enabled": false
+      }
+    }
+  }
+}
+```
+
 ## HTTP headers
 
 Starting from version 3.3.0, you can capture request and response headers on your server (request) telemetry:
@@ -754,7 +774,7 @@ and the console, corresponding to this configuration:
 `level` can be one of `OFF`, `ERROR`, `WARN`, `INFO`, `DEBUG`, or `TRACE`.
 
 `path` can be an absolute or relative path. Relative paths are resolved against the directory where
-`applicationinsights-agent-3.3.1.jar` is located.
+`applicationinsights-agent-3.4.0.jar` is located.
 
 `maxSizeMb` is the max size of the log file before it rolls over.