Trace é um framework de registro estruturado para rastrear eventos de instrumentação de um processo em execução. Os módulos TraceLog e TraceAnalysis são os principais módulos que compõem o framework. O Unreal Trace Server é executado em segundo plano como uma única instância de servidor e pode ser compartilhado entre vários projetos ou ramificações. É um programa otimizado com impacto mínimo no desempenho e não inclui uma interface de usuário.
O Trace Server é inicializado automaticamente por um processo de servidor separado, UnrealTraceServer.exe, localizado na pasta do diretório Engine/Binaries/Win64.
O Trace Server tem dois componentes:
O Trace Recorder monitora conexões de entrada de rastreamentos na porta 1981 e grava o fluxo de rastreamento em tempo real.
O Armazenamento do Trace armazena os rastreamentos gravados como arquivos em uma pasta. Ele monitora essa pasta em busca de alterações e expõe a lista de rastreamentos disponíveis à interface do Unreal Insights.
Um exemplo do caminho para a pasta de rastreamentos é:
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/Unreal Trace Server
As versões do Unreal Editor inicializam automaticamente o UnrealTraceServer.exe quando você faz uma conexão pelo navegador da sessão do Unreal Trace. O servidor Unreal Trace é executado em segundo plano como uma única instância de servidor e pode ser compartilhado entre vários projetos e ramificações.
Para encerrar o Unreal Trace Server, acesse o Gerenciador de Tarefas do sistema e vá até a aba Processos.
O Unreal Trace Server é executado em segundo plano como uma instância única que não precisa ser encerrada para inicializar uma nova versão. Ele pode receber e registrar dados de várias fontes ao mesmo tempo.
No momento, só oferecemos suporte ao Unreal Trace Server para um usuário por máquina. Se vários usuários estiverem logados simultaneamente, os rastreamentos serão armazenados no diretório de rastreamento do primeiro usuário, deixando-os inacessíveis a outros usuários.
Widget Trace Insights
O widget Trace Insights permite controlar e gerenciar dados do Trace usando uma interface do Editor. Para acessar o widget Trace Insights pelo Editor, vá até a barra de ferramentas inferior e clique no botão Trace.
Os segmentos a seguir descrevem as configurações em cada categoria do menu Trace.
Dados de rastreamento
A categoria Dados do Trace contém configurações para canais de dados, marcadores de rastreamentos, capturas de tela de rastreamentos e muito mais.
Canais
O Trace é capaz de registrar grandes volumes de dados. Você pode escolher o tipo de dados que gravar usando Canais do Trace.
Os canais controlam a taxa de dados durante o rastreamento. Cada tipo de evento está vinculado a um ou mais canais. Se os canais necessários não estiverem habilitados, o evento não será emitido para o fluxo de rastreamento.
As predefinições de canal agrupam canais para fornecer pontos de entrada baseados em cenário.
| Channel | Description |
|---|---|
Animation | Animation Insights Plugin. |
AssetLoadTime | Contains named CPU timers for |
AssetMetadata | Asset Names and Class Names as metadata for memory allocations. Requires Metadata channel. Used by Memalloc channel. |
Audio | Audio Insights Plugin. |
AudioMixer | AudioMixer Insights Plugin. |
Bookmark | Low-frequency markers to signify important transitions. Bookmarks provide a quick overview of features such as level loading or engine boot phases. |
Callstack | Callstack descriptions. Allows allocations to be associated with callstacks. |
ContextSwitch | Trace context switch events. On Windows, game or editor runtime should be run as administrator. |
Cook | Displays named CPU timers specific to cooking. This requires the CPU channel to be enabled. Cook will add the both the |
Counters | Generic counters. Traces float and integer values over time. Counters Trace API. It enables the CSV Profiler Trace. |
Cpu | Named CPU timers. Additional timers can be added by enabling the Stat Named Events channel from the Insights Widget or using the |
File | File I/O trace channel that contains Open, ReOpen, Read, Write, Close events. |
Frame | Game and Rendering frames. |
Gpu | Named GPU timers. Based on GpuProfiler data. |
LoadTime | Asset Loading Insights trace channel. Only works for runtime loading from the pak/iostore. |
Log | Logs Messages. |
MemAlloc | Memory allocations. Uses Module and Callstack. |
MemTag | Memory tag statistics. Traces snapshots of memory usage per tag at regular rate. Relies on LLM subsystem for tracing. Implies "-llm". Available after |
Messaging | UDP Messaging plugin. |
Metadata | Support for generic metadata scopes. |
Module | Module loading information. |
Net | Networking trace channel. |
Niagara | Niagara Plugin. |
Object | GameplayInsights/RewindDebugger plugin. |
Physics | |
RDG | RDG Insights Plugin. |
RHICommands | CPU or GPU named timers for RHI commands. |
RenderCommands | CPU or GPU named timers for commands executed on the rendering thread. |
SaveTime | Named CPU timers specific to package saving. |
Screenshot | Captures screenshots triggered with |
Slate | Slate Insights Plugin. |
StackSampling | Trace stack sampling events based on Event Tracing for Windows (ETW). |
Stats | Stats counters. Based on the Stats system. |
Task | Task Graph trace channel. |
VisualLogger | Visual Logger starts recording to file. |
Os seguintes canais estão ativados por padrão:
Favorito
CPU
Quadro
GPU
Log
Região
Captura de tela
Os canais MemAlloc, MemTag e Módulo estão cinzas porque devem ser executados no prompt de comando. Confira A partir do prompt de comando
Você pode definir suas próprias predefinições usando arquivos de configuração adicionados à categoria [Trace.ChannelPresets]. Consulte o Guia do desenvolvedor do Trace para acessar a documentação.
Captura de tela do Trace
A Captura de tela do Trace captura uma imagem da janela de visualização do projeto durante esse quadro e a envia ao Trace. Por padrão, a opção "Captura de tela do Trace" está habilitada no painel de canais.
Você pode fazer uma captura de tela de rastreamento de duas maneiras:
Na barra de ferramentas inferior, clique em Trace > Captura de tela do Trace.
No console, insira o comando
trace.screenshot.
Ao usar a captura de tela de rastreamento, a linha do tempo "Timing Insights" exibe uma linha vertical contendo um nome gerado com base no carimbo de data/hora atual, usando a data e a hora da captura de tela.
Favorito do Trace
O Favorito do Trace emite um evento TRACE_BOOKMARK() com o nome da string fornecida. Quando usados no editor, os eventos de captura de tela e de favorito gerarão um nome com base no carimbo de data/hora atual usando o formato de data e hora.
Você pode definir um Favorito do Trace de duas maneiras:
Na barra de ferramentas inferior, clique em Trace > Favorito do Trace.
No console, insira o comando
trace.bookmark.
Favoritos e capturas de tela ficam visíveis na aba Timing Insights. Você pode encontrá-los na faixa de marcadores fixada na barra de ferramentas superior, abaixo da faixa da régua. Os marcadores estão disponíveis na visualização de Log.
Eventos nomeados de atributos
Eventos nomeados de atributos fornecem métricas de análise adicionais. Você pode habilitá-los ou desabilitá-los clicando na caixa de seleção Eventos nomeados de atributos.
Destino do Trace
Na categoria Destino do Trace, você pode escolher onde armazenar os dados de rastreamento.
| Opção | Descrição |
|---|---|
Armazenamento do Trace | Grava os dados de rastreamento em um arquivo no diretório gerenciado de armazenamento de rastreamento. |
Arquivo | Grava dados de rastreamento diretamente no arquivo especificado. |
Rastreamento
A categoria Rastreamento contém configurações para iniciar e parar uma gravação e salvar instantâneos de rastreamento.
Iniciar e parar gravação
| Opção | Descrição |
|---|---|
Iniciar rastreamento | Inicia um rastreamento para o destino de rastreamento selecionado. Você pode iniciar um rastreamento pelo widget Trace Insights clicando no botão Iniciar rastreamento. |
Interromper rastreamento | Quando um rastreamento é iniciado, o ícone da IU de "Iniciar rastreamento" é exibido em vermelho. Você pode interromper a gravação do traçado clicando no botão Interromper rastreamento. |
Salvar instantâneo de rastreamento
Há duas maneiras de salvar um instantâneo de rastreamento:
Na barra de ferramentas inferior, clique no botão Salvar instantâneo de rastreamento.
Na barra de ferramentas inferior, clique em Trace > Salvar instantâneo de rastreamento.
Opções
A categoria Opçõescontrola a automação, como a abertura automática do Unreal Insights ou de pastas de destino.
| Opção | Descrição |
|---|---|
Abrir sessão ao vivo no início do rastreamento | Quando o rastreamento é iniciado, a sessão ao vivo é aberta automaticamente no Unreal Insights. Esta opção só se aplica ao rastrear no Armazenamento do Trace. |
Abrir Insights após o rastreamento | Quando o rastreamento é interrompido ou um instantâneo é salvo, a sessão gravada é aberta automaticamente no Unreal Insights. |
Exibido no Explorer após o rastreamento | Quando o rastreamento é interrompido ou um instantâneo é salvo, a pasta que contém a sessão gravada é aberta automaticamente. |
Locais
A categoria Locais controla onde os rastreamentos (salvos em arquivo e no Trace Server) são armazenados.
| Opção | Descrição |
|---|---|
Abrir diretório de armazenamento do Trace | O local onde os rastreamentos salvos no Trace Server são armazenados. |
Abrir diretório de perfilamento | Abre o diretório de perfilamento do projeto atual. Este é o local onde os rastreamentos para o arquivo são armazenados. |
Insights
A categoria Insights contém configurações que abrem o Unreal Insights, sessões ao vivo e arquivos gravados.
| Opção | Descrição |
|---|---|
Unreal Insights(navegador de sessão) | Inicializa o navegador de sessão do Unreal Insights. |
Abrir sessão ao vivo | Abre a sessão ao vivo atual. Isso só é possível ao rastrear para o armazenamento. |
Rastreamentos recentes | Abre os rastreamentos mais recentes gravados no Armazenamento do Trace ou como um arquivo. |
Status de rastreamento
Para conferir as informações sobre conexões, memória usada, cache de eventos importantes, dados enviados e canais de rastreamento habilitados e disponíveis, use o comando do console Trace.Status.
Como executar o Insights pelo prompt de comando
Para executar o Unreal Insights pelo prompt de comando, siga estas etapas:
Navegue até a pasta
Engine\Binaries\Win64e clique duas vezes emUnrealInsights.exe.Inicialize o Prompt de Comando do seu sistema operacional e execute seu projeto. No exemplo a seguir, substitua o caminho de instalação e o nome do projeto pelos seus próprios:
C++cd C:\[MyEngineInstallLocation]\ Samples\Games\Binaries\Win64\[YourProject].exe
Rastreamento de cauda
O rastreamento de cauda monitora eventos nos últimos segundos (dependendo do tamanho do buffer). Portanto, qualquer máquina que possa exibir uma preparação.
O tamanho padrão do buffer é 4 MB. No entanto, se você quiser modificá-lo ou desativá-lo, insira o comando de console -tracetailmb=X.
Definir X como 0 MB o desativará, e outros valores alterarão o tamanho do buffer.
Conexão tardia
Eventos importantes são armazenados em cache no lado do cliente da Unreal Engine e enviados às máquinas com conexão tardia durante a conexão. Portanto, eventos únicos (eventos importantes) não serão perdidos antes que você possa fazer uma conexão.
O Insights pode instruir instâncias remotas da Unreal Engine em execução a se conectarem aos servidores de rastreamento remoto a partir de sua instância de IU local, sem precisar envolver a máquina local.
A conexão tardia pode ser iniciada navegando até Unreal Insights > Conectar ou pelo console do editor inserindo qualquer um dos seguintes comandos ou argumentos:
"trace.send [ip]" / "trace.start [nomedoarquivo]"-trace.start [arquivo] [channelSet] -tracehost=[ip]-tracefile = [caminho do arquivo]
O Unreal Insights tem um sistema de cache baseado em arquivo que possibilita ao candidatura anexar informações adicionais a um traçado. Isso pode ser usado para recuperar resultados calculados anteriormente mais rapidamente ou armazenar dados que seriam perdidos, como símbolos. O cache é armazenado em um arquivo .ucache ao lado do arquivo de rastreamento.
Guia do usuário do Trace
Você pode usar diferentes fluxos de trabalho para executar rastreamentos no Unreal Insights. Consulte o Guia do usuário do Trace para acessar a documentação.
Guia do desenvolvedor do Trace
Você pode desenvolver seus próprios rastreamentos no Unreal Insights. Consulte o Guia do desenvolvedor do Trace para acessar a documentação.