Exceções de depuração em aplicativos .NET usando o Depurador de Instantâneo
Com o Depurador de Instantâneo, você pode coletar automaticamente um instantâneo de depuração quando ocorre uma exceção em seu aplicativo .NET ativo. Os instantâneos de depuração coletados mostram o estado do código-fonte e das variáveis no momento em que a exceção foi lançada.
O depurador de instantâneo no Application Insights:
- Monitoriza os registos gerados pelo sistema a partir da sua aplicação Web.
- Coleta instantâneos em suas exceções de lançamento superior.
- 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.
Aplicações e ambientes suportados
Esta seção lista os aplicativos e ambientes suportados.
Aplicações
A coleta de instantâneos está disponível para:
- .NET Framework 4.6.2 e versões mais recentes.
- .NET 6.0 ou posterior no Windows.
Ambientes
Os seguintes ambientes são suportados:
- Serviço de Aplicações do Azure
- Funções do Azure
- Serviços de Nuvem do Azure executando 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 Escala de Máquinas Virtuais do Azure executando o Windows Server 2012 R2 ou posterior
- Máquinas virtuais ou físicas locais que executam o Windows Server 2012 R2 ou posterior ou o Windows 8.1 ou posterior
Nota
Não há suporte para aplicativos cliente (por exemplo, WPF, Windows Forms ou UWP).
Pré-requisitos para usar o Depurador de Instantâneo
Pacotes e configurações
- Inclua o pacote NuGet do Snapshot Collector em seu aplicativo.
- Configure os parâmetros de coleta no
ApplicationInsights.config
.
Permissões
- Verifique se você foi adicionado à função de Depurador de Instantâneo do Application Insights para o Instantâneo do Application Insights de destino.
Como funciona o Depurador de Instantâneo
O Depurador de Instantâneo é implementado como um processador de telemetria do Application Insights. Quando o aplicativo é executado, o processador de telemetria do Depurador de Instantâneo é 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 variáveis e de parâmetros. Os dados de instantâneo são armazenados na mesma região que o recurso do Application Insights.
Processo do depurador de instantâneo
O processo do Depurador de Instantâneo começa e termina com o TrackException
método. Um instantâneo do 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
arquivo .O Depurador de Instantâneo monitora as exceções à medida que elas são lançadas ao assinar o
AppDomain.CurrentDomain.FirstChanceException
evento.Um contador é incrementado para a ID do problema.
- Quando o contador atinge o
ThresholdForSnapshotting
valor, a ID do problema é adicionada a um plano de coleta.
Nota
O
ThresholdForSnapshotting
valor mínimo padrão é 1. Com esse valor, seu aplicativo precisa acionar a mesma exceção duas vezes antes que um instantâneo seja criado.- Quando o contador atinge o
A ID do problema do evento de exceção é calculada e comparada com as IDs do problema no plano de coleta.
Se houver uma correspondência entre IDs de problema, um instantâneo do processo em execução será criado.
- O instantâneo recebe um identificador exclusivo e a exceção é carimbada com esse identificador.
Nota
A taxa de criação de
SnapshotsPerTenMinutesLimit
instantâneos é limitada pela configuração. Por padrão, o limite é de um instantâneo a cada 10 minutos.Depois que o
FirstChanceException
manipulador retorna, a exceção lançada é processada normalmente.A exceção atinge o método novamente e é relatada ao Application Insights, juntamente com o
TrackException
identificador de instantâneo.
Nota
Defina IsEnabledInDeveloperMode
como true
se você deseja gerar instantâneos enquanto depura no Visual Studio.
Processo do Snapshot Uploader
Enquanto o processo do Depurador de Instantâneo continua a ser executado e a fornecer tráfego aos usuários com pouca interrupção, o instantâneo é entregue ao processo do Snapshot Uploader. O carregador de instantâneos:
Cria um minidump.
Carrega o minidump para o Application Insights, juntamente com qualquer arquivo de símbolo (.pdb) relevante.
Nota
Não podem ser carregados mais de 50 instantâneos por dia.
Se você ativou o Depurador de Instantâneos, mas não está vendo instantâneos, consulte o Guia de solução de problemas.
Limitações
Esta seção discute as limitações do Depurador de Instantâneo.
Retenção de dados
Os instantâneos de depuração são armazenados por 15 dias. A política de retenção de dados padrão é definida por aplicativo. Se precisar aumentar esse valor, você pode solicitar um aumento abrindo um caso de suporte no portal do Azure. Para cada instância do Application Insights, um número máximo de 50 snapshots é permitido por dia.
Publicar símbolos
O Depurador de instantâneo 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 versão quando publica no Serviço de Aplicativo.
Em versões anteriores, você deve adicionar a seguinte linha ao seu arquivo de perfil
.pubxml
de publicação para que os símbolos sejam publicados no modo de versão:<ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>
Para o Azure Compute e outros tipos, certifique-se de que os arquivos de símbolo são:
- Na mesma pasta do aplicativo
.dll
principal (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 que você use Completo, Portátil ou Incorporado.
Compilações otimizadas
Em alguns casos, as variáveis locais não podem ser visualizadas em compilações de versão devido a otimizações aplicadas pelo compilador JIT.
No entanto, no Serviço de Aplicativo, o Depurador de Instantâneo pode desotimizar métodos de lançamento que fazem parte de seu plano de coleta.
Gorjeta
Instale a extensão Site do Application Insights em sua instância do Serviço de Aplicativo para obter suporte à desotimização.
Próximos passos
Habilite o depurador de instantâneo do Application Insights para seu aplicativo:
- Serviço de Aplicações do Azure
- Funções do Azure
- Serviços em 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 de versão do Microsoft.ApplicationInsights.SnapshotCollector
Esta seção contém as notas de versão do Microsoft.ApplicationInsights.SnapshotCollector
pacote NuGet para aplicativos .NET, que é usado pelo Depurador de Instantâneo do Application Insights.
Saiba mais sobre o Application Insights Snapshot Debugger para aplicativos .NET.
Para relatórios de bugs e comentários, abra um problema no GitHub.
Nota
A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.
1.4.6
Uma liberação pontual para abordar uma regressão ao usar aplicativos .NET 8.
Correções de erros
- Exceções lançadas de métodos gerados dinamicamente (por exemplo, árvores de expressão compiladas) no .NET 8 não estão sendo rastreadas corretamente. Corrigido.
1.4.5
Uma liberação pontual para resolver um bug relatado pelo usuário.
Correções de erros
- AccessViolationException corrigido ao ler alguns PDBs.
Alterações
- Adicionado um Leiame ao pacote NuGet.
- Atualizado msdia140.dll.
1.4.4
Uma liberação pontual para resolver bugs relatados pelo usuário.
Correções de erros
Alterações
- Mensagens de falha de verificação de PDB reduzidas de Erro para Aviso.
- Atualizado msdia140.dll.
- Evite fazer uma conexão de serviço se o depurador estiver desativado por meio das configurações de extensão de site.
1.4.3
Uma liberação pontual para resolver bugs relatados pelo usuário.
Correções de erros
- Corrigido: Oculte a dependência do IMDS do rastreador de dependência..
- Fixed ArgumentException: telemetryProcessorType não implementa ITelemetryProcessor..
O Snapshot Collector usado via SDK não é suportado quando o recurso de interoperabilidade está habilitado. Consulte Mais cenários não suportados.
1.4.2
Uma liberação pontual para resolver um bug relatado pelo usuário.
Correções de erros
Fixed ArgumentException: Os delegados devem ser do mesmo tipo.
1.4.1
Uma liberação pontual para reverter uma alteração de quebra introduzida na versão 1.4.0.
Correções de erros
Método fixo não encontrado em WebJobs.
1.4.0
Foram abordadas várias melhorias e adicionado suporte para autenticação do Microsoft Entra para ingestão do Application Insights.
Alterações
- Redução do tamanho do pacote do Snapshot Collector em 60%, de 10,34 MB para 4,11 MB.
- Netstandard2.0 direcionado somente no Snapshot Collector.
- Aumentou a dependência do SDK do Application Insights para 2.15.0.
- Adicionado de volta
MinidumpWithThreadInfo
ao escrever dumps. - Adicionado
CompatibilityVersion
para melhorar a sincronização entre o agente do Snapshot Collector e o Snapshot Uploader em alterações de quebra. - Algoritmo de nomenclatura LogFile alterado
SnapshotUploader
para evitar E/S de arquivo excessiva no Serviço de Aplicativo. - Adicionado
pid
,role name
eprocess start time
aos metadados de blob carregados. - Usado
System.Diagnostics.Process
no Snapshot Collector e no Snapshot Uploader.
Novas funcionalidades
Adicionada a autenticação do Microsoft Entra ao 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 liberação pontual para backport de uma correção da versão 1.4.0-pre.
Correções de erros
Corrigido ObjectDisposedException no desligamento.
1.3.7.4
Uma liberação pontual para resolver um problema descoberto no teste do cenário de anexação sem código do Serviço de Aplicativo.
Alterações
A netcoreapp3.0
meta agora depende de Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (anteriormente >= 2.1.2).
1.3.7.3
Uma liberação pontual para resolver alguns problemas de alto impacto.
Correções de erros
- Corrigida a descoberta de PDB na pasta wwwroot/bin, que foi quebrada quando alteramos o algoritmo de pesquisa de símbolos na versão 1.3.6.
- Fixo barulhento
ExtractWasCalledMultipleTimesException
em telemetria.
1.3.7
Alterações
A netcoreapp2.0
meta de SnapshotCollector
depende de Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (novamente). Essa alteração reverte o comportamento para como era antes da 1.3.5. Tentamos atualizá-lo na versão 1.3.6, mas ele quebrou alguns cenários do Serviço de Aplicativo.
Novas funcionalidades
O Snapshot Collector lê e analisa a ConnectionString
variável de ambiente do APPLICATIONINSIGHTS_CONNECTION_STRING ou o TelemetryConfiguration
. Principalmente, ele é usado para definir o ponto de extremidade para se conectar ao serviço de instantâneo. Para obter mais informações, consulte a documentação Cadeias de conexão.
Correções de erros
Mudou para usar HttpClient
para todos os destinos, exceto net45
porque WebRequest
estava falhando em alguns ambientes devido a um incompatível SecurityProtocol
(requer TLS 1.2).
1.3.6
Alterações
SnapshotCollector
agora depende de = 2.5.1 para todas as estruturas deMicrosoft.ApplicationInsights
>destino. Esse requisito pode ser uma alteração significativa se seu aplicativo depender de uma versão mais antiga do SDK do Microsoft.ApplicationInsights.- Removido o suporte para TLS 1.0 e 1.1 no Snapshot Uploader.
- O período de verificações do PDB agora é de 24 horas em vez de 15 minutos. Configurável via
PdbRescanInterval
onSnapshotCollectorConfiguration
. - A verificação do PDB pesquisa apenas pastas de nível superior, em vez de recursiva. Essa alteração pode ser uma alteração de quebra se seus símbolos estiverem em subpastas da pasta binária.
Novas funcionalidades
- Rotação de logs para
SnapshotUploader
evitar encher a pasta de logs com arquivos antigos. - Suporte à desotimização (via ReJIT em anexo) para aplicativos .NET Core 3.0.
- Símbolos adicionados ao pacote NuGet.
- Defina mais metadados ao carregar minidumps.
- Adicionada uma
Initialized
propriedade aSnapshotCollectorTelemetryProcessor
. É umCancellationToken
arquivo , que é cancelado quando o Snapshot Collector é inicializado e conectado ao ponto de extremidade do serviço. - Os instantâneos agora podem ser capturados para exceções em métodos gerados dinamicamente. Um exemplo são as árvores de expressão compiladas geradas por consultas do Entity Framework.
Correções de erros
AmbiguousMatchException
carregando o Snapshot Collector devido ao Status Monitor.GetSnapshotCollector
O método de extensão agora pesquisa todos osTelemetrySinks
arquivos .- Não inicie o Snapshot Uploader em plataformas não suportadas.
- Manipule
InvalidOperationException
quando estiver desotimizando métodos dinâmicos (por exemplo, Entity Framework).
1.3.5
- Adicionado suporte para nuvens soberanas (versões mais antigas não funcionam em nuvens soberanas).
- Adicionar o Snapshot Collector foi facilitado usando
AddSnapshotCollector()
o . Para obter mais informações, consulte Habilitar o depurador de instantâneo 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 não está disponível quando o sistema operacional está definido para o modo compatível com FIPS.
- Ignore quadros do .NET Framework ao desotimizar chamadas de função. Controle esse comportamento com a definição de
DeoptimizeIgnoredModules
configuração. - Adicionada a definição de configuração que permite a
DeoptimizeMethodCount
desotimização de mais de uma chamada de função.
1.3.4
- Teclas de instrumentação estruturadas permitidas.
- Maior robustez do Snapshot Uploader. Continue a inicialização mesmo que os logs antigos do carregador não possam ser movidos.
- Reativado o relatório de mais telemetria quando o SnapshotUploader.exe é encerrado imediatamente (foi desativado na versão 1.3.3).
- Telemetria interna simplificada.
- Recurso experimental: Planos de coleta do Snappoint: Adicionar
snapshotOnFirstOccurence
. Para obter mais informações, consulte este artigo do GitHub.
1.3.3
Corrigido o bug que fazia com que o SnapshotUploader.exe parasse de responder e não carregasse instantâneos para aplicativos .NET Core.
1.3.2
- Recurso experimental: planos de coleta do Snappoint. Para obter mais informações, consulte este artigo do GitHub.
- SnapshotUploader.exe sai quando o tempo de execução descarrega o
AppDomain
do qualSnapshotCollector
é carregado, em vez de aguardar a saída do processo. Essa ação melhora a confiabilidade do coletor quando hospedado no IIS. - Configuração adicionada para permitir que várias
SnapshotCollector
instâncias que estão usando a mesma chave de instrumentação compartilhem o mesmoSnapshotUploader
processo:ShareUploaderProcess
(o padrão étrue
). - Relatado mais telemetria quando SnapshotUploader.exe é encerrado imediatamente.
- Reduzido o número de arquivos de suporte que o SnapshotUploader.exe precisa para gravar no disco.
1.3.1
- Removido o suporte para a coleta de instantâneos com a API RtlCloneUserProcess e suporte apenas à API PssCaptureSnapshots.
- Aumentou de um para três o limite padrão de quantos instantâneos podem ser capturados em 10 minutos.
- Permita que o SnapshotUploader.exe negocie TLS 1.1 e 1.2.
- Relatado mais telemetria quando
SnapshotUploader
registra um aviso ou um erro. - Pare de tirar instantâneos quando o serviço de back-end relatar que a cota diária foi atingida (50 instantâneos por dia).
- Adicionado check-in extra em SnapshotUploader.exe para não permitir que duas instâncias sejam executadas ao mesmo tempo.
1.3.0
Alterações
- Para aplicativos destinados 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 mudança não será um problema para a maioria dos aplicativos. Informe-nos se essa alteração impede que você use o Snapshot Collector mais recente.
- Use atrasos exponenciais de back-off no Snapshot Uploader ao tentar novamente carregamentos com falha.
- Utilizar
ServerTelemetryChannel
(se disponível) para uma comunicação mais fiável da telemetria. - Use
SdkInternalOperationsMonitor
na conexão inicial com o serviço Depurador de Instantâneo para que o controle de dependência o ignore. - Telemetria melhorada em torno da ligação inicial ao Depurador de Instantâneos.
- Relatar mais telemetria para:
- Versão do Serviço de Aplicativo.
- Instâncias de computação do Azure.
- Contentores.
- Aplicativo Azure Functions.
Correções de erros
- Quando o intervalo de redefinição do contador de problemas estiver definido como 24 dias, interprete-o como 24 horas.
- Corrigido um bug em que o Snapshot Uploader parava de processar novos snapshots se houvesse uma exceção ao descartar um snapshot.
1.2.3
Corrigida a assinatura de nome forte com binários do Snapshot Uploader.
1.2.2
Alterações
- Os arquivos necessários para SnapshotUploader(64).exe agora estão incorporados como recursos na DLL principal. Isso significa que a pasta não é mais criada, o que simplifica a compilação e a implantação e reduz a
SnapshotCollectorFiles
desordem no Gerenciador de Soluções. Tenha cuidado ao atualizar para rever as alterações no seu.csproj
ficheiro. OMicrosoft.ApplicationInsights.SnapshotCollector.targets
arquivo não é mais necessário. - A telemetria é registrada no recurso do Application Insights, mesmo que
ProvideAnonymousTelemetry
esteja definida como false. Essa alteração é para que possamos implementar um recurso de verificação de integridade no portal do Azure.ProvideAnonymousTelemetry
afeta apenas a telemetria enviada à Microsoft para suporte e aperfeiçoamento do produto. - Quando
TempFolder
ouShadowCopyFolder
forem redirecionados para variáveis de ambiente, mantenha o coletor ocioso até que essas variáveis de ambiente sejam definidas. - Para aplicativos que se conectam à Internet por meio de um servidor proxy, o Snapshot Collector agora deteta automaticamente todas as configurações de proxy e as passa para o SnapshotUploader.exe.
- Diminua a
SnapshotUploader
prioridade do processo (sempre que possível). Esta prioridade pode ser substituída através daIsLowPrioirtySnapshotUploader
opção. - Adicionado um
GetSnapshotCollector
método de extensão para cenários emTelemetryConfiguration
que você deseja configurar o Snapshot Collector programaticamente. - Defina a versão do SDK do Application Insights (em vez da versão do aplicativo) na telemetria voltada para o cliente.
- Envie o primeiro evento de batimento cardíaco após dois minutos.
Correções de erros
- Corrigido
NullReferenceException
quando as exceções têm dicionários de dados nulos ou imutáveis. - No carregador, tente novamente a correspondência de PDB algumas vezes se obtivermos uma violação de compartilhamento.
- Corrija a telemetria duplicada quando mais de um thread chamar o pipeline de telemetria na inicialização.
1.2.1
Alterações
- Os arquivos de comentário do documento XML agora estão incluídos no pacote NuGet.
- Adicionado um
ExcludeFromSnapshotting
método de extensão para cenários emSystem.Exception
que você sabe que tem uma exceção barulhenta e deseja evitar a criação de instantâneos para ela. - Adicionada uma
IsEnabledWhenProfiling
propriedade de configuração que assume como padrão true. Esta é uma alteração em relação às versões anteriores em que a criação de instantâneos era temporariamente desativada se o Application Insights Profiler estivesse executando uma coleção detalhada. O comportamento antigo pode ser recuperado definindo essa propriedade comofalse
.
Correções de erros
- Assine SnapshotUploader64.exe corretamente.
- Proteja-se contra inicialização dupla do processador de telemetria.
- Evite o registro duplo de telemetria em aplicativos com vários pipelines.
- Corrigido um bug com o tempo de expiração de um plano de coleta, que poderia impedir instantâneos após 24 horas.
1.2.0
A maior mudança nesta versão (daí a mudança para um novo número de versão secundária) é uma reescrita do pipeline de criação e manipulação de snapshots. Em versões anteriores, essa funcionalidade era implementada em código nativo (ProductionBreakpoints.dll* e SnapshotHolder.exe*). A nova implementação é toda gerenciada com P/Invokes.
Para esta primeira versão usando o novo pipeline, não nos afastamos muito do comportamento original. A nova implementação permite uma melhor comunicação de erros e prepara-nos para futuras melhorias.
Outras alterações nesta versão
- MinidumpUploader.exe foi renomeado para SnapshotUploader.exe (ou SnapshotUploader64.exe).
- Telemetria de temporização adicionada para solicitações DeOptimize/ReOptimize.
- Adicionada compactação gzip para uploads minidump.
- Corrigido um problema em que os PDBs estavam bloqueados impedindo a atualização do site.
- Registre o nome da pasta original (SnapshotCollectorFiles) ao copiar sombra.
- Limites de memória ajustados para processos de 64 bits para evitar reinicializações do site devido ao OOM.
- Corrigido um problema em que os instantâneos ainda eram coletados mesmo após a desativação.
- Registre eventos de pulsação no recurso de IA do cliente.
- Velocidade de snapshot melhorada removendo "Source" do ID do problema.
1.1.2
Alterações
- Telemetria de uso aumentada.
- Detete e relate a versão e o sistema operacional .NET.
- Detete e relate 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 número de
TrackException
chamadas) na telemetria Heartbeat.
Correções de erros
- Tratamento correto de
SqlException
onde a exceção interna (Win32Exception) não é lançada. - Espaços à direita cortados em pastas de símbolos, o que causou uma análise incorreta de argumentos de linha de comando para o
MinidumpUploader
. - Impediu a repetição infinita de conexões com falha com o ponto de extremidade do agente do Depurador de Instantâneo.
1.1.0
Alterações
- Adicionada proteção de memória do host. Esse recurso reduz o impacto na memória da máquina host.
- Melhorou a experiência de visualização de instantâneos do portal do Azure.