Merge pull request #281446 from MicrosoftDocs/main

7/22/2024 AM Publish

Author: Taojunshen

.openpublishing.redirection.app-service.json

@@ -552,7 +552,12 @@
         },
         {
             "source_path_from_root": "/articles/app-service/containers/configure-language-java.md",
-            "redirect_url": "/azure/app-service/configure-language-java?pivots=platform-linux",
+            "redirect_url": "/azure/app-service/configure-language-java-deploy-run?pivots=platform-linux",
+            "redirect_document_id": false
+        },
+        {
+            "source_path_from_root": "/articles/app-service/configure-language-java.md",
+            "redirect_url": "/azure/app-service/configure-language-java-deploy-run",
             "redirect_document_id": false
         },
         {

articles/app-service/configure-authentication-user-identities.md

@@ -20,19 +20,19 @@ For all language frameworks, App Service makes the claims in the incoming token
 |------------------------------|-----------------------------------------------------------------------|
 | `X-MS-CLIENT-PRINCIPAL`      | A Base64 encoded JSON representation of available claims. For more information, see [Decoding the client principal header](#decoding-the-client-principal-header).   |
 | `X-MS-CLIENT-PRINCIPAL-ID`   | An identifier for the caller set by the identity provider.            |
-| `X-MS-CLIENT-PRINCIPAL-NAME` | A human-readable name for the caller set by the identity provider, e.g. Email Address, User Principal Name.   |
+| `X-MS-CLIENT-PRINCIPAL-NAME` | A human-readable name for the caller set by the identity provider, such as email address or user principal name.   |
 | `X-MS-CLIENT-PRINCIPAL-IDP`  | The name of the identity provider used by App Service Authentication. |
 
 Provider tokens are also exposed through similar headers. For example, Microsoft Entra also sets `X-MS-TOKEN-AAD-ACCESS-TOKEN` and `X-MS-TOKEN-AAD-ID-TOKEN` as appropriate.
 
 > [!NOTE]
-> Different language frameworks may present these headers to the app code in different formats, such as lowercase or title case.
+> Different language frameworks might present these headers to the app code in different formats, such as lowercase or title case.
 
-Code that is written in any language or framework can get the information that it needs from these headers. [Decoding the client principal header](#decoding-the-client-principal-header) covers this process. For some frameworks, the platform also provides extra options that may be more convenient.
+Code that is written in any language or framework can get the information that it needs from these headers. [Decoding the client principal header](#decoding-the-client-principal-header) covers this process. For some frameworks, the platform also provides extra options that might be more convenient.
 
 ### Decoding the client principal header
 
-`X-MS-CLIENT-PRINCIPAL` contains the full set of available claims as Base64 encoded JSON. These claims go through a default claims-mapping process, so some may have different names than you would see if processing the token directly. The decoded payload is structured as follows:
+`X-MS-CLIENT-PRINCIPAL` contains the full set of available claims as Base64 encoded JSON. These claims go through a default claims-mapping process, so some might have different names than you would see if processing the token directly. The decoded payload is structured as follows:
 
 ```json
 {
@@ -52,12 +52,12 @@ Code that is written in any language or framework can get the information that i
 |------------|------------------|---------------------------------------|
 | `auth_typ` | string           | The name of the identity provider used by App Service Authentication. |
 | `claims`   | array of objects | An array of objects representing the available claims. Each object contains `typ` and `val` properties. |
-| `typ`      | string           | The name of the claim. This may have been subject to default claims mapping and could be different from the corresponding claim contained in a token. |
+| `typ`      | string           | The name of the claim. It might be subject to default claims mapping and could be different from the corresponding claim contained in a token. |
 | `val`      | string           | The value of the claim.                                      |
 | `name_typ` | string           | The name claim type, which is typically a URI providing scheme information about the `name` claim if one is defined. |
 | `role_typ` | string           | The role claim type, which is typically a URI providing scheme information about the `role` claim if one is defined. |
 
-To process this header, your app will need to decode the payload and iterate through the `claims` array to find the claims of interest. It may be convenient to convert these into a representation used by the app's language framework. Here's an example of this process in C# that constructs a [ClaimsPrincipal](/dotnet/api/system.security.claims.claimsprincipal) type for the app to use:
+To process this header, your app needs to decode the payload and iterate through the `claims` array to find the claims of interest. It might be convenient to convert them into a representation used by the app's language framework. Here's an example of this process in C# that constructs a [ClaimsPrincipal](/dotnet/api/system.security.claims.claimsprincipal) type for the app to use:
 
 ```csharp
 using System;
@@ -123,7 +123,7 @@ public static class ClaimsPrincipalParser
 
 ### Framework-specific alternatives
 
-For ASP.NET 4.6 apps, App Service populates [ClaimsPrincipal.Current](/dotnet/api/system.security.claims.claimsprincipal.current) with the authenticated user's claims, so you can follow the standard .NET code pattern, including the `[Authorize]` attribute. Similarly, for PHP apps, App Service populates the `_SERVER['REMOTE_USER']` variable. For Java apps, the claims are [accessible from the Tomcat servlet](configure-language-java.md#authenticate-users-easy-auth).
+For ASP.NET 4.6 apps, App Service populates [ClaimsPrincipal.Current](/dotnet/api/system.security.claims.claimsprincipal.current) with the authenticated user's claims, so you can follow the standard .NET code pattern, including the `[Authorize]` attribute. Similarly, for PHP apps, App Service populates the `_SERVER['REMOTE_USER']` variable. For Java apps, the claims are [accessible from the Tomcat servlet](configure-language-java-security.md#authenticate-users-easy-auth).
 
 For [Azure Functions](../azure-functions/functions-overview.md), `ClaimsPrincipal.Current` isn't populated for .NET code, but you can still find the user claims in the request headers, or get the `ClaimsPrincipal` object from the request context or even through a binding parameter. For more information, see [Working with client identities in Azure Functions](../azure-functions/functions-bindings-http-webhook-trigger.md#working-with-client-identities).
 

articles/app-service/configure-common.md

@@ -34,7 +34,7 @@ Other language stacks, likewise, get the app settings as environment variables a
 - [Node.js](configure-language-nodejs.md#access-environment-variables)
 - [PHP](configure-language-php.md#access-environment-variables)
 - [Python](configure-language-python.md#access-app-settings-as-environment-variables)
-- [Java](configure-language-java.md#configure-data-sources)
+- [Java](configure-language-java-data-sources.md)
 - [Custom containers](configure-custom-container.md#configure-environment-variables)
 
 App settings are always encrypted when stored (encrypted-at-rest).
@@ -216,7 +216,7 @@ At runtime, connection strings are available as environment variables, prefixed
 * Notification Hub: `NOTIFICATIONHUBCONNSTR_`
 * Service Bus: `SERVICEBUSCONNSTR_`
 * Event Hub: `EVENTHUBCONNSTR_`
-* Document Db: `DOCDBCONNSTR_`
+* Document DB: `DOCDBCONNSTR_`
 * Redis Cache: `REDISCACHECONNSTR_`
 
 >[!Note]
@@ -229,7 +229,7 @@ For example, a MySQL connection string named *connectionstring1* can be accessed
 - [Node.js](configure-language-nodejs.md#access-environment-variables)
 - [PHP](configure-language-php.md#access-environment-variables)
 - [Python](configure-language-python.md#access-environment-variables)
-- [Java](configure-language-java.md#configure-data-sources)
+- [Java](configure-language-java-data-sources.md)
 - [Custom containers](configure-custom-container.md#configure-environment-variables)
 
 Connection strings are always encrypted when stored (encrypted-at-rest).
@@ -413,7 +413,7 @@ It's not possible to edit connection strings in bulk by using a JSON file with A
 - [Node.js](configure-language-nodejs.md)
 - [PHP](configure-language-php.md)
 - [Python](configure-language-python.md)
-- [Java](configure-language-java.md)
+- [Java](configure-language-java-deploy-run.md)
 
 <a name="alwayson"></a>
 

articles/app-service/configure-language-java-apm.md

@@ -0,0 +1,212 @@
+---
+title: Configure APM platforms for Tomcat, JBoss, or Java SE apps
+description: Learn how to configure APM platforms, such as Application Insights, NewRelic, and AppDynamics, for Tomcat, JBoss, or Java SE app on Azure App Service.
+keywords: azure app service, web app, windows, oss, java, tomcat, jboss, spring boot, quarkus
+ms.devlang: java
+ms.topic: article
+ms.date: 07/17/2024
+ms.custom: devx-track-java, devx-track-azurecli, devx-track-extended-java, linux-related-content
+zone_pivot_groups: app-service-java-hosting
+adobe-target: true
+author: cephalin
+ms.author: cephalin
+---
+
+# Configure APM platforms for Tomcat, JBoss, or Java SE apps in Azure App Service
+
+This article shows how to connect Java applications deployed on Azure App Service with Azure Monitor Application Insights, NewRelic, and AppDynamics application performance monitoring (APM) platforms.
+
+[!INCLUDE [java-variants](includes/configure-language-java/java-variants.md)]
+
+## Configure Application Insights
+
+Azure Monitor Application Insights is a cloud native application monitoring service that enables customers to observe failures, bottlenecks, and usage patterns to improve application performance and reduce mean time to resolution (MTTR). With a few clicks or CLI commands, you can enable monitoring for your Node.js or Java apps, autocollecting logs, metrics, and distributed traces, eliminating the need for including an SDK in your app. For more information about the available app settings for configuring the agent, see the [Application Insights documentation](../azure-monitor/app/java-standalone-config.md).
+
+# [Azure portal](#tab/portal)
+
+To enable Application Insights from the Azure portal, go to **Application Insights** on the left-side menu and select **Turn on Application Insights**. By default, a new application insights resource of the same name as your web app is used. You can choose to use an existing application insights resource, or change the name. Select **Apply** at the bottom.
+
+# [Azure CLI](#tab/cli)
+
+To enable via the Azure CLI, you need to create an Application Insights resource and set a couple app settings on the Azure portal to connect Application Insights to your web app.
+
+1. Enable the Applications Insights extension
+
+    ```azurecli
+    az extension add -n application-insights
+    ```
+
+2. Create an Application Insights resource using the following CLI command. Replace the placeholders with your desired resource name and group.
+
+    ```azurecli
+    az monitor app-insights component create --app <resource-name> -g <resource-group> --location westus2  --kind web --application-type web
+    ```
+
+    Note the values for `connectionString` and `instrumentationKey`, you'll need these values in the next step.
+
+    > [!NOTE]
+    > To retrieve a list of other locations, run `az account list-locations`.
+
+3. Set the instrumentation key, connection string, and monitoring agent version as app settings on the web app. Replace `<instrumentationKey>` and `<connectionString>` with the values from the previous step.
+
+    # [Windows](#tab/windows)
+
+    ```azurecli
+    az webapp config appsettings set -n <webapp-name> -g <resource-group> --settings "APPINSIGHTS_INSTRUMENTATIONKEY=<instrumentationKey>" "APPLICATIONINSIGHTS_CONNECTION_STRING=<connectionString>" "ApplicationInsightsAgent_EXTENSION_VERSION=~3" "XDT_MicrosoftApplicationInsights_Mode=default" "XDT_MicrosoftApplicationInsights_Java=1"
+    ```
+
+    # [Linux](#tab/linux)
+    
+    ```azurecli
+    az webapp config appsettings set -n <webapp-name> -g <resource-group> --settings "APPINSIGHTS_INSTRUMENTATIONKEY=<instrumentationKey>" "APPLICATIONINSIGHTS_CONNECTION_STRING=<connectionString>" "ApplicationInsightsAgent_EXTENSION_VERSION=~3" "XDT_MicrosoftApplicationInsights_Mode=default"
+    ```
+
+    ---
+
+---
+
+## Configure New Relic
+
+# [Windows](#tab/windows)
+
+1. Create a NewRelic account at [NewRelic.com](https://newrelic.com/signup)
+2. Download the Java agent from NewRelic. It has a file name similar to *newrelic-java-x.x.x.zip*.
+3. Copy your license key, you need it to configure the agent later.
+4. [SSH into your App Service instance](configure-linux-open-ssh-session.md) and create a new directory */home/site/wwwroot/apm*.
+5. Upload the unpacked NewRelic Java agent files into a directory under */home/site/wwwroot/apm*. The files for your agent should be in */home/site/wwwroot/apm/newrelic*.
+6. Modify the YAML file at */home/site/wwwroot/apm/newrelic/newrelic.yml* and replace the placeholder license value with your own license key.
+7. In the Azure portal, browse to your application in App Service and create a new Application Setting.
+
+    ::: zone pivot="java-javase"
+    
+    Create an environment variable named `JAVA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar`.
+
+    ::: zone-end
+
+    ::: zone pivot="java-tomcat"
+
+    Create an environment variable named `CATALINA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar`.
+
+    ::: zone-end
+
+    ::: zone pivot="java-jboss"
+
+    For **JBoss EAP**, `[TODO]`.
+
+    ::: zone-end
+
+# [Linux](#tab/linux)
+
+1. Create a NewRelic account at [NewRelic.com](https://newrelic.com/signup)
+2. Download the Java agent from NewRelic. It has a file name similar to *newrelic-java-x.x.x.zip*.
+3. Copy your license key, you need it to configure the agent later.
+4. [SSH into your App Service instance](configure-linux-open-ssh-session.md) and create a new directory */home/site/wwwroot/apm*.
+5. Upload the unpacked NewRelic Java agent files into a directory under */home/site/wwwroot/apm*. The files for your agent should be in */home/site/wwwroot/apm/newrelic*.
+6. Modify the YAML file at */home/site/wwwroot/apm/newrelic/newrelic.yml* and replace the placeholder license value with your own license key.
+7. In the Azure portal, browse to your application in App Service and create a new Application Setting.
+
+    ::: zone pivot="java-javase"
+    
+    Create an environment variable named `JAVA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar`.
+
+    ::: zone-end
+
+    ::: zone pivot="java-tomcat"
+
+    Create an environment variable named `CATALINA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar`.
+
+    ::: zone-end
+
+    ::: zone pivot="java-jboss"
+
+    For **JBoss EAP**, `[TODO]`.
+
+    ::: zone-end
+
+---
+
+> [!NOTE]
+> If you already have an environment variable for `JAVA_OPTS` or `CATALINA_OPTS`, append the `-javaagent:/...` option to the end of the current value.
+
+## Configure AppDynamics
+
+# [Windows](#tab/windows)
+
+1. Create an AppDynamics account at [AppDynamics.com](https://www.appdynamics.com/community/register/)
+2. Download the Java agent from the AppDynamics website. The file name is similar to *AppServerAgent-x.x.x.xxxxx.zip*
+3. Use the [Kudu console](https://github.com/projectkudu/kudu/wiki/Kudu-console) to create a new directory */home/site/wwwroot/apm*.
+4. Upload the Java agent files into a directory under */home/site/wwwroot/apm*. The files for your agent should be in */home/site/wwwroot/apm/appdynamics*.
+5. In the Azure portal, browse to your application in App Service and create a new Application Setting.
+
+    ::: zone pivot="java-javase"
+    
+    Create an environment variable named `JAVA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name>` where `<app-name>` is your App Service name. If you already have an environment variable for `JAVA_OPTS`, append the `-javaagent:/...` option to the end of the current value.
+
+    ::: zone-end
+
+    ::: zone pivot="java-tomcat"
+
+    Create an environment variable named `CATALINA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name>` where `<app-name>` is your App Service name. If you already have an environment variable for `CATALINA_OPTS`, append the `-javaagent:/...` option to the end of the current value.
+
+    ::: zone-end
+
+    ::: zone pivot="java-jboss"
+
+    For **JBoss EAP**, `[TODO]`.
+
+    ::: zone-end
+
+# [Linux](#tab/linux)
+
+1. Create an AppDynamics account at [AppDynamics.com](https://www.appdynamics.com/community/register/)
+2. Download the Java agent from the AppDynamics website. The file name is similar to *AppServerAgent-x.x.x.xxxxx.zip*
+3. [SSH into your App Service instance](configure-linux-open-ssh-session.md) and create a new directory */home/site/wwwroot/apm*.
+4. Upload the Java agent files into a directory under */home/site/wwwroot/apm*. The files for your agent should be in */home/site/wwwroot/apm/appdynamics*.
+5. In the Azure portal, browse to your application in App Service and create a new Application Setting.
+
+    ::: zone pivot="java-javase"
+
+    Create an environment variable named `JAVA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name>` where `<app-name>` is your App Service name. If you already have an environment variable for `JAVA_OPTS`, append the `-javaagent:/...` option to the end of the current value.
+
+    ::: zone-end
+
+    ::: zone pivot="java-tomcat"
+
+    Create an environment variable named `CATALINA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name>` where `<app-name>` is your App Service name. If you already have an environment variable for `CATALINA_OPTS`, append the `-javaagent:/...` option to the end of the current value.
+
+    ::: zone-end
+
+    ::: zone pivot="java-jboss"
+
+    For **JBoss EAP**, `[TODO]`.
+
+    ::: zone-end
+
+---
+
+## Configure Datadog
+
+# [Windows](#tab/windows)
+* The configuration options are different depending on which Datadog site your organization is using. See the official [Datadog Integration for Azure Documentation](https://docs.datadoghq.com/integrations/azure/)
+
+# [Linux](#tab/linux)
+* The configuration options are different depending on which Datadog site your organization is using. See the official [Datadog Integration for Azure Documentation](https://docs.datadoghq.com/integrations/azure/)
+
+---
+
+## Configure Dynatrace
+
+# [Windows](#tab/windows)
+* Dynatrace provides an [Azure Native Dynatrace Service](https://www.dynatrace.com/monitoring/technologies/azure-monitoring/). To monitor Azure App Services using Dynatrace, see the official [Dynatrace for Azure documentation](https://docs.datadoghq.com/integrations/azure/)
+
+# [Linux](#tab/linux)
+* Dynatrace provides an [Azure Native Dynatrace Service](https://www.dynatrace.com/monitoring/technologies/azure-monitoring/). To monitor Azure App Services using Dynatrace, see the official [Dynatrace for Azure documentation](https://docs.datadoghq.com/integrations/azure/)
+
+---
+
+## Next steps
+
+Visit the [Azure for Java Developers](/java/azure/) center to find Azure quickstarts, tutorials, and Java reference documentation.
+
+- [App Service Linux FAQ](faq-app-service-linux.yml)
+- [Environment variables and app settings reference](reference-app-settings.md)