[exporter/azuremonitor] Enhance AAD Documentation.

.chloggen/update-azuremonitor-service-version.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: azuremonitorexporter
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Updated Azure Monitor Exporter service version from v2.0 to v2.1.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [29234]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

exporter/azuremonitorexporter/AUTHENTICATION.md

@@ -2,42 +2,41 @@
 
 ## Local Authentication
 
-The default authentication mechanism used by the Azure Monitor Exporter is "Local Authentication" - based solely on the Application Insights Instrumentation Key. An example of the exporters section of the configuration is
+The default authentication mechanism used by the Azure Monitor Exporter is "Local Authentication", which relies exclusively on the `InstrumentationKey` obtained from the connection string of the Application Insights. Below is an illustrative example of the exporters section in a configuration file:
 
 ```yaml
 exporters:
    azuremonitor:
-      instrumentation_key: 00000000-0000-0000-0000-000000000000
+      connection_string: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://ingestion.azuremonitor.com/"
 ```
 
-Where the zero guid is replaced with the instrumentation key of your Application Insights instance.
+Use the connection string from your Application Insights instance.
 
 The same can be achieved by using an environment variable to hold the key
 
 ```yaml
 exporters:
    azuremonitor:
-      instrumentation_key: ${env:APP_INSIGHTS_KEY}
+      connection_string: ${env:APPLICATIONINSIGHTS_CONNECTION_STRING}
 ```
 
 ## AAD/Entra Authentication
 
-Local Authentication can be disabled in [Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/azure-ad-authentication) and an AAD based identity can be used in conjunction with the instrumentation key. The instrumentation key is still required by the Exporter, but it is no long  sufficient to just have this in order to import data.
+Local Authentication can be disabled in [Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/azure-ad-authentication) and an AAD based identity can be used in conjunction with the instrumentation key.
 
 The Azure Monitor Exporter does not support this approach directly, but it can be used with the [AAD Authentication Proxy](https://github.com/Azure/aad-auth-proxy) from the Azure Monitor product group.
 
 The AAD Auth Proxy is a separate container/side-car that proxies calls to the Application Insights ingestion endpoint and attaches a bearer token to each call, asserting an AAD identity. This identity is managed by a certificate in the container that is registered with a Service Principal in AAD.
 
-To use this, both Azure Monitor Exporter and the AAD Auth Proxy require specific configuration. In the Exporter's configuration, it is necessary to override the default endpoint used to send data to. In the following example, it is assumed the AAD Auth Proxy is listening on localhost:8081.
+To integrate this setup, both the Azure Monitor Exporter and the AAD Auth Proxy must be configured appropriately. For the Exporter, replace the ingestion endpoint in the connection string with the proxy endpoint. For instance, if the AAD Auth Proxy listens on localhost:8081, configure as follows:
 
 ```yaml
 exporters:
    azuremonitor:
-      instrumentation_key: ${env:APP_INSIGHTS_KEY}
-      endpoint: http://localhost:8081/v2.1/track
+      connection_string: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=http://localhost:8081"
 ```
 
-The key difference is this uses the `v2.1` endpoint, not the standard `v2` one.
+The original `IngestionEndpoint` from the connection string needs to be set as the `TARGET_HOST` environment variable in the aad-auth-proxy configuration.
 
 In the docker compose file for AAD Auth Proxy, the following values need to be set:
 
@@ -60,7 +59,7 @@ azuremonitor-ingestion-proxy:
 ```
 
 - `AUDIENCE`: value is the generic Azure Monitor Scope.
-- `TARGET_HOST`: the Application Insights IngestionEndpoint value from the Connection String, available in the Azure Portal.
+- `TARGET_HOST`: the Application Insights `IngestionEndpoint` value from the Connection String, available in the Azure Portal.
 - `AAD_CLIENT_ID`: client id of the service principal representing the AAD identity to use.
 - `AAD_TENANT_ID`: id of the AAD Tenant the service principal exists in.
 - `AAD_CLIENT_CERTIFICATE_PATH`: path to the .pem certificate file containing the CERTIFICATE and PRIVATE KEY parts of the certificate registered with the service principal.

exporter/azuremonitorexporter/connection_string_parser.go

@@ -75,6 +75,6 @@ func getIngestionURL(ingestionEndpoint string) string {
 		ingestionURL, _ = url.Parse(DefaultIngestionEndpoint)
 	}
 
-	ingestionURL.Path = path.Join(ingestionURL.Path, "/v2/track")
+	ingestionURL.Path = path.Join(ingestionURL.Path, "/v2.1/track")
 	return ingestionURL.String()
 }

exporter/azuremonitorexporter/connection_string_parser_test.go

@@ -27,7 +27,7 @@ func TestParseConnectionString(t *testing.T) {
 			},
 			want: &ConnectionVars{
 				InstrumentationKey: "00000000-0000-0000-0000-000000000000",
-				IngestionURL:       "https://ingestion.azuremonitor.com/v2/track",
+				IngestionURL:       "https://ingestion.azuremonitor.com/v2.1/track",
 			},
 			wantError: false,
 		},
@@ -38,7 +38,7 @@ func TestParseConnectionString(t *testing.T) {
 			},
 			want: &ConnectionVars{
 				InstrumentationKey: "00000000-0000-0000-0000-000000000000",
-				IngestionURL:       DefaultIngestionEndpoint + "v2/track",
+				IngestionURL:       DefaultIngestionEndpoint + "v2.1/track",
 			},
 			wantError: false,
 		},
@@ -49,7 +49,7 @@ func TestParseConnectionString(t *testing.T) {
 			},
 			want: &ConnectionVars{
 				InstrumentationKey: "00000000-0000-0000-0000-000000000000",
-				IngestionURL:       "https://ingestion.azuremonitor.com/v2/track",
+				IngestionURL:       "https://ingestion.azuremonitor.com/v2.1/track",
 			},
 			wantError: false,
 		},
@@ -93,7 +93,7 @@ func TestParseConnectionString(t *testing.T) {
 			},
 			want: &ConnectionVars{
 				InstrumentationKey: "00000000-0000-0000-0000-000000000000",
-				IngestionURL:       "https://ingestion.azuremonitor.com/v2/track",
+				IngestionURL:       "https://ingestion.azuremonitor.com/v2.1/track",
 			},
 			wantError: false,
 		},
@@ -104,7 +104,7 @@ func TestParseConnectionString(t *testing.T) {
 			},
 			want: &ConnectionVars{
 				InstrumentationKey: "00000000-0000-0000-0000-000000000000",
-				IngestionURL:       "https://ingestion.azuremonitor.com/v2/track",
+				IngestionURL:       "https://ingestion.azuremonitor.com/v2.1/track",
 			},
 			wantError: false,
 		},