Geolocalização e processamento de endereços IP

Este artigo explica como a pesquisa de geolocalização e o processamento de endereços IP funcionam no Application Insights, juntamente com como modificar o comportamento predefinido.

Comportamento predefinido

Por predefinição, os endereços IP são recolhidos temporariamente, mas não armazenados no Application Insights. Este processo segue alguns passos básicos.

Quando a telemetria é enviada para o Azure, o Application Insights utiliza o endereço IP para fazer uma pesquisa de geolocalização. O Application Insights utiliza os resultados desta pesquisa para preencher os campos client_City, client_StateOrProvincee client_CountryOrRegion. Em seguida, o endereço é eliminado e 0.0.0.0 é escrito no client_IP campo.

Para remover dados de geolocalização, veja os seguintes artigos:

• Remover o inicializador de IP do cliente
• Utilizar um inicializador personalizado

Os tipos de telemetria são:

• Telemetria do browser: o Application Insights recolhe o endereço IP do remetente. O ponto final de ingestão calcula o endereço IP.
• Telemetria do servidor: o módulo de telemetria do Application Insights recolhe temporariamente o endereço IP do cliente. O endereço IP não é recolhido localmente quando o X-Forwarded-For cabeçalho está definido. Quando a lista de endereços IP recebidos tem mais do que um item, o último endereço IP é utilizado para preencher campos de geolocalização.

Este comportamento é por predefinição para ajudar a evitar a recolha desnecessária de dados pessoais e informações de localização de endereços IP. Sempre que possível, recomendamos que evite a recolha de dados pessoais.

Nota

Embora a predefinição seja não recolher endereços IP, pode substituir este comportamento. Recomendamos que verifique se a coleção não interrompe quaisquer requisitos de conformidade ou regulamentos locais.

Para saber mais sobre como processar dados pessoais no Application Insights, veja Documentação de orientação para dados pessoais.

Quando os endereços IP não são recolhidos, a cidade e outros atributos de geolocalização preenchidos pelo nosso pipeline com o endereço IP também não são recolhidos. Pode mascarar a recolha de IP na origem. Há duas maneiras de fazê-lo. Pode:

• Remova o inicializador de IP do cliente. Para obter mais informações, veja Configuração do Applications Insights.
• Forneça o seu próprio inicializador personalizado. Para obter mais informações, veja um exemplo de filtragem de API.

Armazenamento de dados de endereços IP

Para ativar a recolha e armazenamento de IP, a DisableIpMasking propriedade do componente do Application Insights tem de estar definida como true. Pode definir esta propriedade através do Azure Resource Manager modelos (modelos do ARM) ou ao chamar a API REST.

Modelo ARM

{
       "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/microsoft.insights/components/<resource-name>",
       "name": "<resource-name>",
       "type": "microsoft.insights/components",
       "location": "westcentralus",
       "tags": {
              
       },
       "kind": "web",
       "properties": {
              "Application_Type": "web",
              "Flow_Type": "Redfield",
              "Request_Source": "IbizaAIExtension",
              // ...
              "DisableIpMasking": true
       }
}

Portal

Se precisar de modificar o comportamento apenas para um único recurso do Application Insights, utilize o portal do Azure.

1. Aceda ao recurso do Application Insights e, em seguida, selecioneModelo de Exportação de Automatização>.

2. Selecione Implementar.

   

3. Selecione Editar modelo.

   

   Nota

   Se ocorrer o erro apresentado na captura de ecrã anterior, pode resolvê-lo. Afirma: "O grupo de recursos está numa localização que não é suportada por um ou mais recursos no modelo. Escolha um grupo de recursos diferente." Selecione temporariamente um grupo de recursos diferente na lista pendente e, em seguida, selecione novamente o grupo de recursos original.

4. No modelo JSON, localize properties dentro resourcesde . Adicione uma vírgula ao último campo JSON e, em seguida, adicione a seguinte nova linha: "DisableIpMasking": true. Em seguida, selecione Guardar.

   

5. Selecione Rever + criar>Criar.

   Nota

   Se vir "A implementação falhou", consulte os detalhes de implementação do tipo microsoft.insights/components e verifique o estado. Se esta for bem-sucedida, as alterações efetuadas DisableIpMasking a foram implementadas.

6. Após a conclusão da implementação, serão registados novos dados telemétricos.

   Se selecionar e editar o modelo novamente, verá apenas o modelo predefinido sem a propriedade recentemente adicionada. Se não estiver a ver dados de endereços IP e quiser confirmar que "DisableIpMasking": true está definido, execute os seguintes comandos do PowerShell:

   # Replace `Fabrikam-dev` with the appropriate resource and resource group name.
   # If you aren't using Azure Cloud Shell, you need to connect to your Azure account
   # Connect-AzAccount 
   $AppInsights = Get-AzResource -Name 'Fabrikam-dev' -ResourceType 'microsoft.insights/components' -ResourceGroupName 'Fabrikam-dev'
   $AppInsights.Properties
   

   Como resultado, é devolvida uma lista de propriedades. Uma das propriedades deve ler DisableIpMasking: true. Se executar os comandos do PowerShell antes de implementar a nova propriedade com o Azure Resource Manager, a propriedade não existirá.

API REST

O payload da API REST seguinte faz as mesmas modificações:

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
Host: management.azure.com
Authorization: AUTH_TOKEN
Content-Type: application/json
Content-Length: 54

{
       "location": "<resource location>",
       "kind": "web",
       "properties": {
              "Application_Type": "web",
              "DisableIpMasking": true
       }
}

PowerShell

O cmdlet "Update-AzApplicationInsights" do PoweShell pode desativar a máscara de IP com o DisableIPMasking parâmetro .

Update-AzApplicationInsights -Name "aiName" -ResourceGroupName "rgName" -DisableIPMasking:$true

Para obter mais informações sobre o cmdlet "Update-AzApplicationInsights", consulte Update-AzApplicationInsights

Inicializador de telemetria

Se precisar de uma alternativa mais flexível do que DisableIpMasking, pode utilizar um inicializador de telemetria para copiar a totalidade ou parte do endereço IP para um campo personalizado. O código desta classe é o mesmo em versões .NET.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

namespace MyWebApp
{
    public class CloneIPAddress : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            ISupportProperties propTelemetry = telemetry as ISupportProperties;

            if (propTelemetry !=null && !propTelemetry.Properties.ContainsKey("client-ip"))
            {
                string clientIPValue = telemetry.Context.Location.Ip;
                propTelemetry.Properties.Add("client-ip", clientIPValue);
            }
        }
    } 
}

Nota

Se não conseguir aceder ISupportPropertiesao , certifique-se de que está a executar a versão estável mais recente do SDK do Application Insights. ISupportProperties destina-se a valores de cardinalidade elevados. GlobalProperties é mais adequado para valores de cardinalidade baixos, como o nome da região e o nome do ambiente.

.NET 6.0+

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

builder.services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();

.NET 5.0

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();
}

ASP.NET Framework

using Microsoft.ApplicationInsights.Extensibility;

namespace MyWebApp
{
    public class MvcApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
              //Enable your telemetry initializer:
              TelemetryConfiguration.Active.TelemetryInitializers.Add(new CloneIPAddress());
        }
    }
}

Node.js

Node.js

appInsights.defaultClient.addTelemetryProcessor((envelope) => {
    const baseData = envelope.data.baseData;
    if (appInsights.Contracts.domainSupportsProperties(baseData)) {
        const ipAddress = envelope.tags[appInsights.defaultClient.context.keys.locationIp];
        if (ipAddress) {
            baseData.properties["client-ip"] = ipAddress;
        }
    }
});

JavaScript do lado do cliente

JavaScript do lado do cliente

Ao contrário dos SDKs do lado do servidor, o SDK JavaScript do lado do cliente não calcula um endereço IP. Por predefinição, o cálculo do endereço IP para a telemetria do lado do cliente ocorre no ponto final de ingestão no Azure.

Se quiser calcular o endereço IP diretamente do lado do cliente, tem de adicionar a sua própria lógica personalizada e utilizar o resultado para definir a ai.location.ip etiqueta. Quando ai.location.ip está definido, o ponto final de ingestão não efetua o cálculo do endereço IP e o endereço IP fornecido é utilizado para a pesquisa de geolocalização. Neste cenário, o endereço IP ainda está a zero por predefinição.

Para manter todo o endereço IP calculado a partir da sua lógica personalizada, pode utilizar um inicializador de telemetria que copiaria os dados do endereço IP que forneceu ai.location.ip para um campo personalizado separado. Mas, mais uma vez, ao contrário dos SDKs do lado do servidor, o SDK do lado do cliente não calculará o endereço se não puder depender de bibliotecas de terceiros ou da sua própria lógica personalizada.

appInsights.addTelemetryInitializer((item) => {
    const ipAddress = item.tags && item.tags["ai.location.ip"];
    if (ipAddress) {
        item.baseData.properties = {
            ...item.baseData.properties,
            "client-ip": ipAddress
        };
    }
});

Se os dados do lado do cliente atravessarem um proxy antes de reencaminhar para o ponto final de ingestão, o cálculo do endereço IP poderá mostrar o endereço IP do proxy e não o cliente.

Ver os resultados do inicializador de telemetria

Se enviar tráfego novo para o seu site e aguardar alguns minutos, pode executar uma consulta para confirmar que a coleção está a funcionar:

requests
| where timestamp > ago(1h) 
| project appName, operation_Name, url, resultCode, client_IP, customDimensions.["client-ip"]

Os endereços IP recolhidos recentemente serão apresentados na customDimensions_client-ip coluna. A coluna predefinida client-ip ainda terá os quatro octetos a zero.

Se estiver a testar a partir de localhost e o valor para customDimensions_client-ip for , ::1este valor é o comportamento esperado. O ::1 valor representa o endereço de loopback em IPv6. É equivalente a 127.0.0.1 em IPv4.

Perguntas mais frequentes

Esta secção fornece respostas a perguntas comuns.

Como são calculados os dados de cidade, país/região e outros dados de geolocalização?

Procuramos o endereço IP (IPv4 ou IPv6) do cliente Web:

• Telemetria do browser: recolhemos o endereço IP do remetente.
• Telemetria do servidor: o módulo do Application Insights recolhe o endereço IP do cliente. Não é recolhido se X-Forwarded-For estiver definido.
• Para saber mais sobre como os dados de geolocalização e endereços IP são recolhidos no Application Insights, veja Geolocalização e processamento de endereços IP.

Pode configurar ClientIpHeaderTelemetryInitializer para tirar o endereço IP de um cabeçalho diferente. Em alguns sistemas, por exemplo, é movido por um proxy, balanceador de carga ou CDN para X-Originating-IP. Saiba mais.

Pode utilizar o Power BI para apresentar a telemetria do pedido num mapa se tiver migrado para um recurso baseado na área de trabalho.

Passos seguintes

• Saiba mais sobre a recolha de dados pessoais no Application Insights.
• Saiba mais sobre como funciona a coleção de endereços IP no Application Insights. Este artigo é uma mensagem de blogue externa mais antiga escrita por um dos nossos engenheiros. É anterior ao comportamento predefinido atual em que o endereço IP é registado como 0.0.0.0. O artigo vai para uma maior profundidade sobre a mecânica do inicializador de telemetria incorporado.