Geolocalização e manipulação de endereço IP

Este artigo explica como a pesquisa de localização geográfica e o tratamento de endereços IP funcionam em Application Insights juntamente com como modificar o comportamento padrão.

Comportamento padrão

Por padrão, os endereços IP são coletados temporariamente, mas não são armazenados em Application Insights. Esse processo segue algumas etapas básicas.

Quando a telemetria é enviada ao Azure, o Application Insights usa o endereço IP para fazer uma pesquisa de localização geográfica. O Application Insights usa os resultados dessa pesquisa para preencher os campos client_City, client_StateOrProvince e client_CountryOrRegion. Em seguida, o endereço é descartado e 0.0.0.0 gravado no campo client_IP.

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

• Remover o inicializador IP do cliente
• Usar um inicializador personalizado

Os tipos de telemetria são:

• Telemetria do navegador: o Application Insights coleta o endereço IP do remetente. O ponto de extremidade de ingestão calcula o endereço IP.
• Telemetria do servidor: o módulo Application Insights coleta o endereço IP do cliente. O endereço IP não é coletado localmente quando o X-Forwarded-For cabeçalho está definido. Quando a lista de endereço IP de entrada tiver mais de um item, o último endereço IP será usado para preencher os campos de geolocalização.

Esse comportamento é por design para ajudar a evitar a coleta desnecessária de dados pessoais e informações de localização de endereço IP. Sempre que possível, é recomendável evitar a coleta de dados pessoais.

Observação

Embora o padrão seja não coletar endereços IP, você pode substituir esse comportamento. Recomendamos verificar se a coleção não interrompe quaisquer requisitos de conformidade ou regulamentos locais.

Para saber mais sobre o tratamento de dados pessoais no Application Insights, veja Diretrizes para dados pessoais.

Quando os endereços IP não são coletados, a cidade e outros atributos de geolocalização preenchidos pelo pipeline usando o endereço IP também não são coletados. Você pode mascarar a coleção de IP na origem. Há duas maneiras de fazer isso. Você pode:

• Remover o inicializador IP do cliente. Para obter mais informações, confira Definição com a Configuração do Application Insights.
• Forneça seu inicializador personalizado. Para obter mais informações, confira Exemplo de filtragem de API.

Armazenamento de dados de endereço IP

Para habilitar a coleta e o armazenamento de IP, a DisableIpMasking Propriedade do componente Application insights deve ser definida como true. Você pode definir essa propriedade por meio de modelos do ARM (Azure Resource Manager) ou chamando a API REST.

Modelo de 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 você precisa modificar o comportamento de um só único recurso de Application Insights, use o portal do Azure.

1. Acesse o recurso Application Insights e, em seguida, selecione Automação>Exportar modelo.

2. Selecione Implantar.

   

3. Selecione Editar modelo.

   

   Observação

   Se você enfrentar o erro mostrado na captura de tela anterior, poderá resolvê-lo. Ele informa: "O grupo de recursos está em um local sem suporte por um ou mais recursos no modelo. Escolha um grupo de recursos diferente." Selecione temporariamente um grupo de recursos diferente na lista suspensa e, em seguida, selecione mais uma vez o grupo de recursos original.

4. No modelo JSON, localize properties dentro de resources. Adicione uma vírgula ao último campo JSON e, em seguida, adicione a seguinte nova linha: "DisableIpMasking": true. Selecione Salvar.

   

5. Selecione Examinar + criar>Criar.

   Observação

   Se você vir "Sua implantação falhou", verifique os detalhes da implantação para aquela com o tipo microsoft.insights/components e verifique o status. Se essa for bem-sucedida, as alterações feitas em DisableIpMasking foram implantadas.

6. Depois que a implantação for concluída, novos dados de telemetria serão registrados.

   Se você selecionar e editar o modelo novamente, só verá o modelo padrão sem a propriedade recém-adicionada. Se você não estiver vendo dados de endereço 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
   

   Uma lista de propriedades é retornada como resultado. Uma das propriedades deve ler DisableIpMasking: true. Se você executar os comandos do PowerShell antes de implantar a nova propriedade com Azure Resource Manager, a propriedade não existirá.

API REST

O conteúdo da API REST a seguir 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 Powershell pode desabilitar a máscara de IP com o parâmetro DisableIPMasking.

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

Para obter mais informações sobre o cmdlet 'Update-AzApplicationInsights', confira Update-AzApplicationInsights

Inicializador de telemetria

Se você precisar de uma alternativa mais flexível do que DisableIpMasking, poderá usar um inicializador de telemetria para copiar todo ou parte do endereço IP para um campo personalizado. O código dessa classe é o mesmo em versões do .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);
            }
        }
    } 
}

Observação

Se não conseguir acessar o ISupportProperties, verifique se você está executando a versão estável mais recente do SDK Application Insights. ISupportProperties é destinado a valores de alta cardinalidade. GlobalProperties é mais apropriado para valores de cardinalidade baixa, como nome da região e 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 do JavaScript do lado do cliente não calcula um endereço IP. Por padrão, o cálculo do endereço IP para a telemetria do lado do cliente ocorre no ponto de extremidade de ingestão no Azure.

Se você quiser calcular o endereço IP diretamente no lado do cliente, precisará adicionar sua própria lógica personalizada e usar o resultado para definir a ai.location.ip marca. Quando ai.location.ip é definido, o ponto de extremidade de ingestão não executa o cálculo de endereço IP e o endereço IP fornecido é usado para a pesquisa de localização geográfica. Nesse cenário, o endereço IP ainda é zerado por padrão.

Para manter todo o endereço IP calculado de sua lógica personalizada, você pode usar um inicializador de telemetria que copiaria os dados de endereço IP que você forneceu em ai.location.ip um campo personalizado separado. Mas, novamente, ao contrário dos SDKs do lado do servidor, o SDK do lado do cliente não calculará o endereço para você se não puder depender de bibliotecas de terceiros ou da sua própria lógica de 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 percorrerem um proxy antes de encaminhar para o ponto de extremidade de ingestão, o cálculo do endereço IP poderá mostrar o endereço IP do proxy e não o cliente.

Exibir os resultados do inicializador de telemetria

Se você enviar o novo tráfego para seu site e aguardar alguns minutos, você poderá executar uma consulta para confirmar se a coleção está funcionando:

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

Os endereços IP recentemente coletados aparecerão na customDimensions_client-ip coluna. A coluna client-ip padrão ainda terá os quatro octetos zerados.

Se você estiver testando do localhost e o valor para customDimensions_client-ip for ::1, esse valor será um comportamento esperado. O valor ::1 representa o endereço de loopback no IPv6. É equivalente a 127.0.0.1 no IPv4.

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

Como os dados de cidade, país/região e outros dados de localização geográfica são calculados?

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

• Telemetria do navegador: Coletamos o endereço IP do remetente.
• Telemetria do servidor: O módulo Application Insights coleta o endereço IP do cliente. Ele não será coletado se X-Forwarded-For estiver configurado.
• Para saber mais sobre como o endereço IP e os dados de localização geográfica são coletados no Application Insights, confira Manuseio de Geolocalização e endereço IP.

É possível configurar o ClientIpHeaderTelemetryInitializer para coletar o endereço IP de um cabeçalho diferente. Em alguns sistemas, por exemplo, ele é movido por um proxy, balanceador de carga ou CDN para X-Originating-IP. Saiba mais.

Você pode usar o Power BI para exibir sua telemetria de solicitação em um mapa se tiver migrado para um recurso baseado em workspace.

Próximas etapas

• Saiba mais sobre a coleta de dados pessoais no Application insights.
• Saiba mais sobre como funciona a coleta de endereços IP no Application Insights. Este artigo é uma postagem de blog externa mais antiga escrita por um de nossos engenheiros. Ele é anterior ao comportamento padrão atual em que o endereço IP é registrado como 0.0.0.0. O artigo aborda com mais detalhes a mecânica do inicializador de telemetria interno.