Skip to content

Commit 1596a61

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #281705 from AaronMaxwell/aaronmax-move-telem-init
Updating article for freshness
2 parents 5d553b3 + f415ac1 commit 1596a61

File tree

1 file changed

+27
-174
lines changed

1 file changed

+27
-174
lines changed

‎articles/azure-monitor/app/ip-collection.md

Lines changed: 27 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -2,46 +2,44 @@
22
title: Application Insights IP address collection | Microsoft Docs
33
description: Understand how Application Insights handles IP addresses and geolocation.
44
ms.topic: conceptual
5-
ms.date: 06/23/2023
6-
ms.custom:
7-
ms.reviewer: saars
5+
ms.date: 07/24/2024
6+
ms.reviewer: mmcc
87
---
98

109
# Geolocation and IP address handling
1110

12-
This article explains how geolocation lookup and IP address handling work in Application Insights, along with how to modify the default behavior.
11+
This article explains how geolocation lookup and IP address handling work in [Application Insights](app-insights-overview.md#application-insights-overview).
1312

1413
## Default behavior
1514

16-
By default, IP addresses are temporarily collected but not stored in Application Insights. This process follows some basic steps.
15+
By default, IP addresses are temporarily collected but not stored.
1716

18-
When telemetry is sent to Azure, Application Insights uses the IP address to do a geolocation lookup. Application Insights uses the results of this lookup to populate the fields `client_City`, `client_StateOrProvince`, and `client_CountryOrRegion`. The address is then discarded, and `0.0.0.0` is written to the `client_IP` field.
19-
20-
To remove geolocation data, see the following articles:
21-
22-
* [Remove the client IP initializer](../app/configuration-with-applicationinsights-config.md)
23-
* [Use a custom initializer](../app/api-filtering-sampling.md)
17+
When telemetry is sent to Azure, the IP address is used in a geolocation lookup. The result is used to populate the fields `client_City`, `client_StateOrProvince`, and `client_CountryOrRegion`. The address is then discarded, and `0.0.0.0` is written to the `client_IP` field.
2418

2519
The telemetry types are:
2620

2721
* **Browser telemetry**: Application Insights collects the sender's IP address. The ingestion endpoint calculates the IP address.
28-
* **Server telemetry**: The Application Insights telemetry module temporarily collects the client IP address. The IP address isn't collected locally when the `X-Forwarded-For` header is set. When the incoming IP address list has more than one item, the last IP address is used to populate geolocation fields.
22+
* **Server telemetry**: The Application Insights telemetry module temporarily collects the client IP address when the `X-Forwarded-For` header isn't set. When the incoming IP address list has more than one item, the last IP address is used to populate geolocation fields.
2923

30-
This behavior is by design to help avoid unnecessary collection of personal data and IP address location information. Whenever possible, we recommend avoiding the collection of personal data.
24+
This behavior is by design to help avoid unnecessary collection of personal data and IP address location information.
3125

32-
> [!NOTE]
33-
> Although the default is to not collect IP addresses, you can override this behavior. We recommend verifying that the collection doesn't break any compliance requirements or local regulations.
34-
>
35-
> To learn more about handling personal data in Application Insights, see [Guidance for personal data](../logs/personal-data-mgmt.md).
26+
When IP addresses aren't collected, city and other geolocation attributes also aren't collected.
27+
28+
## Storage of IP address data
3629

37-
When IP addresses aren't collected, city and other geolocation attributes populated by our pipeline by using the IP address also aren't collected. You can mask IP collection at the source. There are two ways to do it. You can:
30+
> [!WARNING]
31+
> The default and our recommendation is to not collect IP addresses. If you override this behavior, verify the collection doesn't break any compliance requirements or local regulations.
32+
>
33+
> To learn more about handling personal data, see [Guidance for personal data](../logs/personal-data-mgmt.md).
3834
39-
* Remove the client IP initializer. For more information, see [Configuration with Applications Insights Configuration](configuration-with-applicationinsights-config.md).
40-
* Provide your own custom initializer. For more information, see an [API filtering example](api-filtering-sampling.md).
35+
To enable IP collection and storage, the `DisableIpMasking` property of the Application Insights component must be set to `true`.
4136

42-
## Storage of IP address data
37+
Options to set this property include:
4338

44-
To enable IP collection and storage, the `DisableIpMasking` property of the Application Insights component must be set to `true`. You can set this property through Azure Resource Manager templates (ARM templates) or by calling the REST API.
39+
- [ARM template](#arm-template)
40+
- [Portal](#portal)
41+
- [REST API](#rest-api)
42+
- [PowerShell](#powershell)
4543

4644
### ARM template
4745

@@ -93,7 +91,7 @@ If you need to modify the behavior for only a single Application Insights resour
9391
9492
1. After the deployment is complete, new telemetry data will be recorded.
9593

96-
If you select and edit the template again, you'll see only the default template without the newly added property. If you aren't seeing IP address data and want to confirm that `"DisableIpMasking": true` is set, run the following PowerShell commands:
94+
If you select and edit the template again, only the default template without the newly added property. If you aren't seeing IP address data and want to confirm that `"DisableIpMasking": true` is set, run the following PowerShell commands:
9795

9896
```powershell
9997
# Replace `Fabrikam-dev` with the appropriate resource and resource group name.
@@ -103,13 +101,13 @@ If you need to modify the behavior for only a single Application Insights resour
103101
$AppInsights.Properties
104102
```
105103
106-
A list of properties is returned as a result. One of the properties should read `DisableIpMasking: true`. If you run the PowerShell commands before you deploy the new property with Azure Resource Manager, the property won't exist.
104+
A list of properties is returned as a result. One of the properties should read `DisableIpMasking: true`. If you run the PowerShell commands before you deploy the new property with Azure Resource Manager, the property doesn't exist.
107105
108106
### REST API
109107
110108
The following [REST API](/rest/api/azure/) payload makes the same modifications:
111109
112-
```
110+
```json
113111
PATCH https://management.azure.com/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/microsoft.insights/components/<resource-name>?api-version=2018-05-01-preview HTTP/1.1
114112
Host: management.azure.com
115113
Authorization: AUTH_TOKEN
@@ -128,160 +126,15 @@ Content-Length: 54
128126

129127
### PowerShell
130128

131-
The PoweShell 'Update-AzApplicationInsights' cmdlet can disable IP masking with the `DisableIPMasking` parameter.
129+
The PowerShell `Update-AzApplicationInsights` cmdlet can disable IP masking with the `DisableIPMasking` parameter.
132130

133131
```powershell
134132
Update-AzApplicationInsights -Name "aiName" -ResourceGroupName "rgName" -DisableIPMasking:$true
135133
```
136134

137-
For more information on the 'Update-AzApplicationInsights' cmdlet, see [Update-AzApplicationInsights](/powershell/module/az.applicationinsights/update-azapplicationinsights)
138-
139-
## Telemetry initializer
140-
141-
If you need a more flexible alternative than `DisableIpMasking`, you can use a [telemetry initializer](./api-filtering-sampling.md#addmodify-properties-itelemetryinitializer) to copy all or part of the IP address to a custom field. The code for this class is the same across .NET versions.
142-
143-
```csharp
144-
using Microsoft.ApplicationInsights.Channel;
145-
using Microsoft.ApplicationInsights.DataContracts;
146-
using Microsoft.ApplicationInsights.Extensibility;
147-
148-
namespace MyWebApp
149-
{
150-
public class CloneIPAddress : ITelemetryInitializer
151-
{
152-
public void Initialize(ITelemetry telemetry)
153-
{
154-
ISupportProperties propTelemetry = telemetry as ISupportProperties;
155-
156-
if (propTelemetry !=null && !propTelemetry.Properties.ContainsKey("client-ip"))
157-
{
158-
string clientIPValue = telemetry.Context.Location.Ip;
159-
propTelemetry.Properties.Add("client-ip", clientIPValue);
160-
}
161-
}
162-
}
163-
}
164-
```
165-
166-
> [!NOTE]
167-
> If you can't access `ISupportProperties`, make sure you're running the latest stable release of the Application Insights SDK. `ISupportProperties` is intended for high cardinality values. `GlobalProperties` is more appropriate for low cardinality values like region name and environment name.
168-
169-
170-
# [.NET 6.0+](#tab/framework)
171-
172-
```csharp
173-
using Microsoft.ApplicationInsights.Extensibility;
174-
using CustomInitializer.Telemetry;
175-
176-
builder.services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();
177-
```
178-
179-
# [.NET 5.0](#tab/dotnet5)
180-
181-
```csharp
182-
using Microsoft.ApplicationInsights.Extensibility;
183-
using CustomInitializer.Telemetry;
184-
185-
public void ConfigureServices(IServiceCollection services)
186-
{
187-
services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();
188-
}
189-
```
190-
191-
# [ASP.NET Framework](#tab/dotnet6)
192-
193-
```csharp
194-
using Microsoft.ApplicationInsights.Extensibility;
195-
196-
namespace MyWebApp
197-
{
198-
public class MvcApplication : System.Web.HttpApplication
199-
{
200-
protected void Application_Start()
201-
{
202-
//Enable your telemetry initializer:
203-
TelemetryConfiguration.Active.TelemetryInitializers.Add(new CloneIPAddress());
204-
}
205-
}
206-
}
207-
208-
```
209-
210-
---
211-
212-
# [Node.js](#tab/nodejs)
213-
214-
### Node.js
215-
216-
```javascript
217-
appInsights.defaultClient.addTelemetryProcessor((envelope) => {
218-
const baseData = envelope.data.baseData;
219-
if (appInsights.Contracts.domainSupportsProperties(baseData)) {
220-
const ipAddress = envelope.tags[appInsights.defaultClient.context.keys.locationIp];
221-
if (ipAddress) {
222-
baseData.properties["client-ip"] = ipAddress;
223-
}
224-
}
225-
});
226-
```
227-
# [Client-side JavaScript](#tab/javascript)
228-
229-
### Client-side JavaScript
230-
231-
Unlike the server-side SDKs, the client-side JavaScript SDK doesn't calculate an IP address. By default, IP address calculation for client-side telemetry occurs at the ingestion endpoint in Azure.
232-
233-
If you want to calculate the IP address directly on the client side, you need to add your own custom logic and use the result to set the `ai.location.ip` tag. When `ai.location.ip` is set, the ingestion endpoint doesn't perform IP address calculation, and the provided IP address is used for the geolocation lookup. In this scenario, the IP address is still zeroed out by default.
234-
235-
To keep the entire IP address calculated from your custom logic, you could use a telemetry initializer that would copy the IP address data that you provided in `ai.location.ip` to a separate custom field. But again, unlike the server-side SDKs, the client-side SDK won't calculate the address for you if it can't rely on third-party libraries or your own custom logic.
236-
237-
```javascript
238-
appInsights.addTelemetryInitializer((item) => {
239-
const ipAddress = item.tags && item.tags["ai.location.ip"];
240-
if (ipAddress) {
241-
item.baseData.properties = {
242-
...item.baseData.properties,
243-
"client-ip": ipAddress
244-
};
245-
}
246-
});
247-
248-
```
249-
250-
If client-side data traverses a proxy before forwarding to the ingestion endpoint, IP address calculation might show the IP address of the proxy and not the client.
251-
252-
---
253-
254-
### View the results of your telemetry initializer
255-
256-
If you send new traffic to your site and wait a few minutes, you can then run a query to confirm that the collection is working:
257-
258-
```kusto
259-
requests
260-
| where timestamp > ago(1h)
261-
| project appName, operation_Name, url, resultCode, client_IP, customDimensions.["client-ip"]
262-
```
263-
264-
Newly collected IP addresses will appear in the `customDimensions_client-ip` column. The default `client-ip` column will still have all four octets zeroed out.
265-
266-
If you're testing from localhost, and the value for `customDimensions_client-ip` is `::1`, this value is expected behavior. The `::1` value represents the loopback address in IPv6. It's equivalent to `127.0.0.1` in IPv4.
267-
268-
## Frequently asked questions
269-
270-
This section provides answers to common questions.
271-
272-
### How is city, country/region, and other geolocation data calculated?
273-
274-
We look up the IP address (IPv4 or IPv6) of the web client:
275-
276-
* Browser telemetry: We collect the sender's IP address.
277-
* Server telemetry: The Application Insights module collects the client IP address. It's not collected if `X-Forwarded-For` is set.
278-
* To learn more about how IP address and geolocation data is collected in Application Insights, see [Geolocation and IP address handling](./ip-collection.md).
279-
280-
You can configure `ClientIpHeaderTelemetryInitializer` to take the IP address from a different header. In some systems, for example, it's moved by a proxy, load balancer, or CDN to `X-Originating-IP`. [Learn more](https://apmtips.com/posts/2016-07-05-client-ip-address/).
281-
282-
You can [use Power BI](../logs/log-powerbi.md) to display your request telemetry on a map if you've [migrated to a workspace-based resource](./convert-classic-resource.md).
135+
For more information on the `Update-AzApplicationInsights` cmdlet, see [Update-AzApplicationInsights](/powershell/module/az.applicationinsights/update-azapplicationinsights)
283136

284137
## Next steps
285138

286-
* Learn more about [personal data collection](../logs/personal-data-mgmt.md) in Application Insights.
287-
* Learn more about how [IP address collection](https://apmtips.com/posts/2016-07-05-client-ip-address/) works in Application Insights. This article is an older external blog post written by one of our engineers. It predates the current default behavior where the IP address is recorded as `0.0.0.0`. The article goes into greater depth on the mechanics of the built-in telemetry initializer.
139+
* Learn more about [personal data collection](../logs/personal-data-mgmt.md) in Azure Monitor.
140+
* Learn how to [set the user IP](opentelemetry-add-modify.md#set-the-user-ip) using OpenTelemetry.

0 commit comments

Comments
 (0)