Depurar exceções em aplicativos .NET usando o Depurador de Instantâneos
Com o Depurador de Instantâneos, você pode coletar automaticamente um instantâneo de depuração quando ocorrer uma exceção em seu aplicativo .NET dinâmico. Os instantâneos de depuração coletados mostram o estado do código-fonte e as variáveis no momento em que a exceção foi gerada.
O Depurador de Instantâneos no Application Insights:
- Monitora os logs gerados pelo sistema do aplicativo Web.
- Coleta instantâneos das exceções mais geradas.
- Fornece as informações necessárias para diagnosticar problemas na produção.
Saiba mais sobre os processos do Depurador de Instantâneos e do Carregador de Instantâneos.
Aplicativos e ambientes compatíveis
Esta seção lista os aplicativos e os ambientes com suporte.
Aplicativos
Coleta de instantâneo está disponível para:
- .NET Framework 4.6.2 e versões mais recentes.
- .NET 6.0 ou posterior no Windows.
Ambientes
Os ambientes a seguir são suportados:
- Serviço de Aplicativo do Azure
- Azure Functions
- Serviços de Nuvem do Azure com a família de SO 4 ou posterior
- Azure Service Fabric em execução no Windows Server 2012 R2 ou posterior
- Máquinas Virtuais do Azure e Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure que executam o Windows Server 2012 R2 ou posterior
- Máquinas locais virtuais ou físicas executando Windows Server 2012 R2 ou posterior; ou Windows 8.1 ou posterior
Observação
Não há suporte para aplicativos cliente (por exemplo, WPF, Windows Forms ou UWP).
Pré-requisitos para usar o Depurador de Instantâneos
Pacotes e configurações
- Incluir o pacote NuGet Snapshot Collector em seu aplicativo.
- Configurar os parâmetros de coleta em
ApplicationInsights.config
.
Permissões
- Verifique se você foi adicionado à função de Depurador de Instantâneos do Application Insights para o Instantâneo do Application Insights de destino.
Como funciona o Depurador de Instantâneos
O Depurador de Instantâneos é implementado como um Processador de telemetria do Application Insights. Quando o aplicativo é executado, o processador de telemetria do Depurador de Instantâneos é adicionado ao pipeline de logs gerados pelo sistema do aplicativo.
Importante
Os instantâneos podem conter dados pessoais ou outras informações confidenciais em valores de variável e parâmetro. Os dados de instantâneo são armazenados na mesma região que o recurso do Application Insights.
Processo do Depurador de Instantâneos
O processo do Depurador de Instantâneos começa e termina com o método TrackException
. Um instantâneo de processo é um clone suspenso do processo em execução, para que os usuários experimentem pouca ou nenhuma interrupção.
Seu aplicativo lança o
TrackException
.O Depurador de Instantâneos monitora as exceções conforme elas são geradas assinando o evento
AppDomain.CurrentDomain.FirstChanceException
.Um contador é incrementado para a ID do problema.
- Quando o contador alcançar o valor
ThresholdForSnapshotting
, a ID do problema será adicionada a um plano de coleta.
Observação
O valor mínimo padrão de
ThresholdForSnapshotting
é 1. Com esse valor, seu aplicativo precisa disparar a mesma exceção duas vezes antes que um instantâneo seja criado.- Quando o contador alcançar o valor
A ID do problema do evento de exceção é computada e comparada com as IDs de problema no plano de coleção.
Se houver uma correspondência entre as IDs do problema, será criado um instantâneo do processo em execução.
- O instantâneo será atribuído a um identificador exclusivo e a exceção será marcada com esse identificador.
Observação
A taxa de criação de instantâneos é limitada pela configuração
SnapshotsPerTenMinutesLimit
. Por padrão, o limite é um instantâneo a cada 10 minutos.Depois que o manipulador
FirstChanceException
é retornado, a exceção gerada é processada normalmente.A exceção atinge o método
TrackException
novamente e é relatada ao Application Insights, juntamente com o identificador do instantâneo.
Observação
Defina IsEnabledInDeveloperMode
como true
se desejar gerar instantâneos durante a depuração no Visual Studio.
Processo do Carregador de Instantâneos
Enquanto o processo do Depurador de Instantâneos continua a ser executado e atende o tráfego aos usuários com pouca interrupção, o instantâneo é entregue ao processo do Carregador de Instantâneos. O Carregador de Instantâneos:
Cria um minidespejo.
Carrega o minidespejo no Application Insights, juntamente com qualquer arquivo de símbolo relevante (.pdb).
Observação
Não é possível carregar mais de 50 instantâneos por dia.
Se você habilitou o Depurador de Instantâneos, mas não está vendo os instantâneos, confira o Guia de solução de problemas.
Limitações
Esta seção discute as limitações do Depurador de Instantâneos.
Retenção de dados
Instantâneos aprimorados são armazenados por 15 dias. Essa política de retenção de dados padrão é definida para cada aplicativo. Se for necessário aumentar esse valor, você poderá solicitar o aumento abrindo um caso de suporte no portal do Azure. Para cada instância do Application Insights, um número máximo de 50 instantâneos é permitido por dia.
Publicar símbolos
O Depurador de Instantâneos requer arquivos de símbolo no servidor de produção para:
- Decodificar variáveis
- Fornecer uma experiência de depuração no Visual Studio
Por padrão, o Visual Studio 2017 versões 15.2+ publica símbolos para compilações de lançamento ao publicar no Serviço de Aplicativo.
Nas versões anteriores, você deve adicionar a seguinte linha ao arquivo
.pubxml
de seu perfil de publicação para que os símbolos sejam publicados no modo de versão:<ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>
Para a Computação do Azure e outros tipos, verifique se os arquivos de símbolo são:
- Na mesma pasta do aplicativo principal
.dll
(normalmente,wwwroot/bin
) ou - Disponível no caminho atual.
Para obter mais informações sobre as diferentes opções de símbolo disponíveis, consulte a documentação do Visual Studio. Para obter melhores resultados, recomendamos usar Completo, Portátil ou Inserido.
Builds otimizados
Em alguns casos, as variáveis locais não podem ser exibidas em builds de versão devido a otimizações aplicadas pelo compilador JIT.
No entanto, no Serviço de Aplicativo, o Depurador de Instantâneos pode cancelar a otimização dos métodos de lançamento que fazem parte de seu plano de coleta.
Dica
Instale a extensão de site do Application Insights em sua instância do Serviço de Aplicativo para obter suporte de cancelamento de otimização.
Próximas etapas
Habilite o Depurador de Instantâneos do Application Insights em seu aplicativo:
- Serviço de Aplicativo do Azure
- Azure Functions
- Serviços de Nuvem do Azure
- Azure Service Fabric
- Máquinas Virtuais do Azure e Conjuntos de Dimensionamento de Máquinas Virtuais
- Máquinas virtuais ou físicas locais
Notas sobre a versão do Microsoft.ApplicationInsights.SnapshotCollector
Este seção contém as notas sobre a versão do pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector
para aplicativos .NET, que é usado pelo Depurador de Instantâneos do Application Insights.
Saiba mais sobre o Depurador de Instantâneos do Application Insights para aplicativos .NET.
Para obter relatórios de bugs e comentários, abra um problema no GitHub.
Observação
Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.
1.4.6
Uma versão pontual para abordar uma regressão ao usar aplicativos .NET 8.
Correções de bug
- As exceções lançadas a partir de métodos gerados dinamicamente (por exemplo, árvores de expressão compiladas) no .NET 8 não estão sendo rastreadas corretamente. Fixo.
1.4.5
Uma versão de ponto para resolver um bug relatado pelo usuário.
Correções de bug
- Foi corrigido o AccessViolationException durante a leitura de alguns PDBs.
Alterações
- Adicionado um ReadMe ao pacote NuGet.
- Atualização msdia140.dll.
1.4.4
Uma versão de ponto para resolver um bug relatado pelo usuário.
Correções de bug
Alterações
- Mensagens de falha de verificação do PDB reduzidas de Erro para Aviso.
- Atualização msdia140.dll.
- Evite fazer uma conexão de serviço se o depurador estiver desabilitado por meio das configurações de extensão do site.
1.4.3
Uma versão de ponto para resolver um bug relatado pelo usuário.
Correções de bug
- Corrigido Ocultar a dependência do IDMS do rastreador de dependência..
- Corrigido ArgumentException: telemetryProcessorTypedoes não implementa ITelemetryProcessor..
O Snapshot Collector usado por meio do SDK não tem suporte quando o recurso Interop está habilitado. Confira Mais cenários sem suporte.
1.4.2
Uma versão de ponto para resolver um bug relatado pelo usuário.
Correções de bug
Corrigido ArgumentException: os delegados devem ser do mesmo tipo.
1.4.1
Uma versão de ponto para reverter uma alteração interruptiva introduzida na versão 1.4.0.
Correções de bug
Corrigido Método não encontrado no WebJobs.
1.4.0
Abordou várias melhorias e adicionou suporte para a autenticação do Microsoft Entra para ingestão do Application Insights.
Alterações
- Tamanho do pacote do Snapshot Collector reduzido em 60%, de 10,34 MB para 4,11 MB.
- Netstandard2.0 direcionado apenas no Snapshot Collector.
- Dependência do SDK do Application Insights aumentada para 2.15.0.
- Adicionado de volta
MinidumpWithThreadInfo
ao gravar despejos. - Adicionado
CompatibilityVersion
para melhorar a sincronização entre o agente do Snapshot Collector e o Snapshot Uploader em alterações de última hora. - Algoritmo de nomenclatura de LogFile
SnapshotUploader
alterado para evitar E/S excessiva de arquivo no Serviço de Aplicativo. - Adicionados
pid
,role name
eprocess start time
aos metadados de blob carregados. - Uso de
System.Diagnostics.Process
no Snapshot Collector e no Snapshot Uploader.
Novos recursos
Adição da autenticação do Microsoft Entra para SnapshotCollector
. Para saber mais sobre a autenticação do Microsoft Entra no Application Insights, consulte Autenticação do Microsoft Entra para Application Insights.
1.3.7.5
Uma versão pontual para fazer o backport de uma correção do 1.4.0-pre.
Correções de bug
Corrigido ObjectDisposedException no desligamento.
1.3.7.4
Uma versão pontual para resolver um problema descoberto em testes de cenário de anexação sem código do Serviço de Aplicativo.
Alterações
O destino netcoreapp3.0
agora depende de Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (anteriormente >= 2.1.2).
1.3.7.3
Uma versão pontual para resolver alguns problemas de alto impacto.
Correções de bug
- Corrigida a descoberta de PDB na pasta wwwroot/bin, que estava quebrada quando alteramos o algoritmo de pesquisa de símbolos na versão 1.3.6.
- Corrigido ruído
ExtractWasCalledMultipleTimesException
na telemetria.
1.3.7
Alterações
O destino netcoreapp2.0
do SnapshotCollector
depende de Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (novamente). Essa alteração reverte o comportamento anterior à versão 1.3.5. Tentamos atualizar isso na versão 1.3.6, mas a atualização interrompeu alguns cenários do Serviço de Aplicativo.
Novos recursos
O Snapshot Collector lê e analisa o ConnectionString
da variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING ou da TelemetryConfiguration
. Basicamente, isso é usado para definir o ponto de extremidade para conexão com o serviço de Instantâneo. Para obter mais informações, confira a Documentação de cadeias de conexão.
Correções de bug
Alterado para uso HttpClient
em todos os destinos, exceto net45
porque WebRequest
estava falhando em alguns ambientes devido a um SecurityProtocol
incompatível (requer TLS 1.2).
1.3.6
Alterações
SnapshotCollector
agora depende deMicrosoft.ApplicationInsights
>= 2.5.1 para todas as estruturas de destino. Esse requisito pode ser uma alteração interruptiva se seu aplicativo depender de uma versão mais antiga do SDK Microsoft.ApplicationInsights.- Removido o suporte para TLS 1.0 e 1.1 no Snapshot Uploader.
- O período padrão de exames de PDB agora é 24 horas em vez de 15 minutos. Configurável por meio de
PdbRescanInterval
emSnapshotCollectorConfiguration
. - O exame de PDB pesquisa somente pastas de nível superior, em vez de recursivas. Essa pode ser uma alteração interruptiva se os símbolos estiverem em subpastas da pasta binária.
Novos recursos
- Rotação de log no
SnapshotUploader
para evitar o preenchimento da pasta de logs com arquivos antigos. - Suporte à desotimização (por meio do ReJIT em anexo) para aplicativos .NET Core 3.0.
- Símbolos adicionados ao pacote NuGet.
- Defina mais metadados ao carregar minidespejos.
- Adicionada uma propriedade
Initialized
aSnapshotCollectorTelemetryProcessor
. Trata-se de umCancellationToken
, que será cancelado quando o Snapshot Collector estiver inicializado e conectado ao ponto de extremidade de serviço. - Captura de instantâneos para exceções em métodos gerados dinamicamente. Um exemplo são as árvores de expressão compiladas geradas pelas consultas do Entity Framework.
Correções de bug
AmbiguousMatchException
carregando o Snapshot Collector devido ao Status Monitor.- O método de extensão
GetSnapshotCollector
agora pesquisa todos osTelemetrySinks
. - O Carregador de Instantâneos não é iniciado em plataformas sem suporte.
- Manuseie
InvalidOperationException
ao cancelar a otimização de métodos dinâmicos (por exemplo, o Entity Framework).
1.3.5
- Adicionado suporte para nuvens soberanas (versões mais antigas não funcionam em nuvens soberanas).
- A adição do Snapshot Collector facilitou o uso de
AddSnapshotCollector()
. Para obter mais informações, confira Habilitar o Depurador de Instantâneos para aplicativos .NET no Serviço de Aplicativo do Azure. - Use a configuração FISMA MD5 para verificar blocos de blob. Essa configuração evita o algoritmo de criptografia .NET MD5 padrão, que fica indisponível quando o sistema operacional está definido para o modo compatível com FIPS.
- Ignora os quadros do .NET Framework ao desotimizar as chamadas de função. Controle esse comportamento com a definição de configuração
DeoptimizeIgnoredModules
. - Adicionada a definição de configuração
DeoptimizeMethodCount
, que permite o cancelamento de otimização de mais de uma chamada de função.
1.3.4
- Chaves de instrumentação estruturadas permitidas.
- Maior robustez do Snapshot Uploader. Continue a inicialização mesmo se os logs antigos do carregador não puderem ser movidos.
- Reabilita o relatório de telemetria adicional quando SnapshotUploader.exe sai imediatamente (foi desabilitado em 1.3.3).
- Telemetria interna simplificada.
- Recurso experimental: planos de coleta do Snappoint. Adicione
snapshotOnFirstOccurence
. Para obter mais informações, confira este artigo do GitHub.
1.3.3
Corrigido o bug que estava fazendo o SnapshotUploader.exe parar de responder e não carregar instantâneos de aplicativos do .NET Core.
1.3.2
- Recurso experimental: planos de coleta do Snappoint. Para obter mais informações, confira este artigo do GitHub.
- O SnapshotUploader.exe sai quando o runtime descarrega o
AppDomain
do qualSnapshotCollector
é carregado, em vez de aguardar a saída do processo. Essa ação aprimora a confiabilidade do coletor hospedado no IIS. - Configuração adicionada para permitir que várias instâncias
SnapshotCollector
que usam a mesma chave de instrumentação compartilhem o mesmo processoSnapshotUploader
:ShareUploaderProcess
(o padrão étrue
). - Mais telemetria relatada quando SnapshotUploader.exe é encerrado imediatamente.
- Reduzido o número de arquivos de suporte necessários para o SnapshotUploader.exe gravar no disco.
1.3.1
- Suporte removido para coletar instantâneos com a API do RtlCloneUserProcess e dá suporte apenas à API do PssCaptureSnapshots.
- Aumentado o limite padrão da quantidade de instantâneos que podem ser capturados em 10 minutos de um para três.
- Permite que o SnapshotUploader.exe negocie o TLS 1.1 e 1.2.
- Mais telemetria relatada quando
SnapshotUploader
registra um aviso ou um erro. - Para de fazer instantâneos quando o serviço de back-end relata que a cota diária foi atingida (50 instantâneos por dia).
- Adicionada verificação extra em SnapshotUploader.exe para não permitir que duas instâncias sejam executadas ao mesmo tempo.
1.3.0
Alterações
- Para os aplicativos direcionados ao .NET Framework, o Snapshot Collector agora depende do Microsoft.ApplicationInsights versão 2.3.0 ou posterior. Costumava ser 2.2.0 ou posterior. Acreditamos que essa alteração não será um problema para a maioria dos aplicativos. Informe-nos se essa alteração o impedir de usar o Snapshot Collector mais recente.
- Uso de atrasos de retirada exponencial no Carregador de Instantâneos ao repetir carregamentos com falha.
- Use
ServerTelemetryChannel
(se disponível) para relatórios de telemetria mais confiáveis. - Use
SdkInternalOperationsMonitor
na conexão inicial com o serviço de Depurador de Instantâneos para que o acompanhamento de dependência o ignore. - Telemetria aprimorada em torno da conexão inicial com o Depurador de Instantâneos.
- Relatar mais telemetria para:
- Versão do Serviço de Aplicativo.
- Instâncias de Computação do Azure.
- Contêineres.
- Aplicativo Azure Functions.
Correções de bug
- Quando o intervalo de redefinição do contador de problemas for definido como 24 dias, vai ser interpretado como 24 horas.
- Corrigido o bug que fazia o Carregador de Instantâneos interromper o processamento de novos instantâneos caso houvesse uma exceção ao descartar um instantâneo.
1.2.3
Corrigido a assinatura de nome forte com binários do Snapshot Uploader.
1.2.2
Alterações
- Os arquivos necessários para o SnapshotUploader(64).exe agora estão inseridos como recursos na DLL principal. Isso significa que a pasta
SnapshotCollectorFiles
não foi mais criada, o que simplifica a criação e a implantação e reduz a confusão no Gerenciador de Soluções. Cuidado ao atualizar para revisar as alterações em seu arquivo.csproj
. O arquivoMicrosoft.ApplicationInsights.SnapshotCollector.targets
não é mais necessário. - A telemetria será registrada no recurso do Application Insights mesmo se
ProvideAnonymousTelemetry
estiver definido como false. Essa alteração serve para implementar um recurso de verificação de integridade no portal do Azure. OProvideAnonymousTelemetry
afeta apenas a telemetria enviada à Microsoft para suporte e aperfeiçoamento do produto. - Quando o
TempFolder
ouShadowCopyFolder
forem redirecionados para as variáveis de ambiente, mantenha o coletor ocioso até que essas variáveis sejam definidas. - Para aplicativos que se conectam à Internet por meio de um servidor proxy, o Snapshot Collector agora detecta automaticamente quaisquer configurações de proxy e as passa para SnapshotUploader.exe.
- Diminua a prioridade do processo
SnapshotUploader
(quando possível). Essa prioridade pode ser substituída por meio da opçãoIsLowPrioirtySnapshotUploader
. - Adicionado um método de extensão
GetSnapshotCollector
emTelemetryConfiguration
para cenários em que você deseja configurar o Snapshot Collector de maneira programática. - Definição da versão do SDK do Application Insights (em vez da versão do aplicativo) na telemetria voltada para o cliente.
- Envio do primeiro evento de pulsação após dois minutos.
Correções de bug
- Corrigido
NullReferenceException
quando as exceções tiverem dicionários de dados nulos ou imutáveis. - No carregador, tente a correspondência de PDB algumas vezes se for obtida uma violação de compartilhamento.
- Corrige a telemetria duplicada quando mais de um thread chama o pipeline de telemetria na inicialização.
1.2.1
Alterações
- Os arquivos de comentário da documentação XML agora estão incluídos no pacote NuGet.
- Adicionado o método de extensão
ExcludeFromSnapshotting
noSystem.Exception
para cenários onde há uma exceção ruidosa e deseja-se evitar a criação de instantâneos para ela. - Adicionada uma propriedade de configuração
IsEnabledWhenProfiling
cujo padrão é true. Essa é uma alteração de versões anteriores em que a criação de instantâneo seria temporariamente desabilitada se o Application Insights Profiler estivesse executando uma coleção detalhada. O comportamento antigo pode ser recuperado definindo essa propriedade comofalse
.
Correções de bug
- Assine SnapshotUploader64.exe corretamente.
- Protege contra a inicialização dupla do processador de telemetria.
- Impede o registro em log duplo de telemetria em aplicativos com vários pipelines.
- Corrigido um bug do tempo de expiração de um plano de coleta que poderia impedir a criação de instantâneos após 24 horas.
1.2.0
A maior alteração nessa versão (por isso, a mudança para um novo número de versão secundária) é uma regeneração do pipeline de criação e manipulação de instantâneos. Em versões anteriores, essa funcionalidade foi implementada em código nativo (ProductionBreakpoints.dll* e SnapshotHolder.exe*). A nova implementação é inteira de código gerenciado com P/Invokes.
Essa primeira versão usando o novo pipeline não é muito diferente do comportamento original. A nova implementação permite um melhor de erros melhor e prepara para aprimoramentos futuros.
Outras alterações nessa versão
- O MinidumpUploader.exe foi renomeado como SnapshotUploader.exe (ou SnapshotUploader64.exe).
- A telemetria de tempo foi adicionada para as solicitações de desotimização/reotimização.
- A compactação Gzip foi adicionada para os carregamentos de minidespejo.
- Foi corrigido um problema que fazia com que os PDBs fossem bloqueados impedindo a atualização do site.
- Foi feito o registro do nome da pasta original (SnapshotCollectorFiles) ao copiar a sombra.
- Foram ajustados os limites de memória para processos de 64 bits para evitar reinicializações de site devido a OOM.
- Corrigido um problema que fazia com que os instantâneos continuassem sendo coletados mesmo após a desabilitação.
- Foi feito o registro de eventos de pulsação no recurso de IA do cliente.
- Velocidade de snapshot aprimorada removendo "Source" do ID do problema.
1.1.2
Alterações
- Telemetria de uso aumentada.
- Detecção e relatório do sistema operacional e versão do .NET.
- Detectar e relatar mais ambientes do Azure (Serviços de Nuvem do Azure, Azure Service Fabric).
- Registre e relate métricas de exceção (número de exceções de primeira chance e o número de chamadas
TrackException
) na telemetria de pulsação.
Correções de bug
- Tratamento correto do
SqlException
em que a exceção interna (Win32Exception) não é lançada. - Espaços à direita cortados em pastas de símbolos, o que causava uma análise incorreta dos argumentos de linha de comando para o arquivo
MinidumpUploader
. - Impediu a repetição infinita de conexões com falha para o ponto de extremidade do agente do Depurador de Instantâneos.
1.1.0
Alterações
- Adicionada a proteção de memória do host. Esse recurso reduz o impacto na memória do computador host.
- Melhorada a experiência de visualização do instantâneo do portal do Azure.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de