Profiler de Script

Profiler de Script é uma ferramenta dentro do Console do Desenvolvedor que permite gravar sessões de profiling de todos os scripts em execução e visualizar seus custos de tempo de CPU com configurações de gravação e exibição personalizadas. Ele pode gravar todos os tipos de chamadas de função, incluindo funções Luau, chamadas de método e acessos a propriedades. Esta ferramenta é útil para identificar scripts que consomem mais recursos de CPU e diminuem o desempenho.

Gravar sessões de profiling

Antes de gravar, você precisa selecionar o ambiente de gravação a partir de:

• Cliente (Padrão) — Grava scripts do lado do cliente, incluindo LocalScripts e Scripts com RunContext definido como Client.
• Servidor — Grava scripts do lado do servidor, incluindo Scripts com RunContext definido como Server ou Legacy. O Profiler de Script limpa todos os dados coletados do lado do servidor no final de cada sessão.

Você também pode definir as seguintes opções de gravação:

Para gravar uma nova sessão de profiling:

1. Abra o Console do Desenvolvedor.

2. Expanda o menu suspenso de ferramentas para selecionar ScriptProfiler.

   

3. Expanda o menu suspenso de cliente-servidor para selecionar Cliente ou Servidor.

   

4. (Opcional) Marque a caixa Ao Vivo para habilitar o comportamento de polling em tempo real.

5. (Opcional) Selecione Frequência e Tempo para escolher a frequência de gravação e a duração da sessão, se você não quiser usar os valores padrão.

6. Clique em Iniciar para começar a sessão de profiling. Se você definir uma duração, o Profiler de Script exibirá um cronômetro de contagem regressiva com o tempo restante na sessão.

7. Clique em Parar ou espere até que a gravação termine para exibir os dados de profiling.

Ler dados de profiling

Após o término de uma sessão, o Profiler de Script gera uma tabela mostrando quanto tempo cada chamada de função consome em tempo de CPU. A tabela classifica as chamadas de função do maior tempo gasto para o menor tempo gasto e permite que você busque funções específicas pelo nome. Ela oferece as seguintes duas visualizações:

• Callgraph (Padrão): categoriza e exibe chamadas de função em uma estrutura de árvore com base nas tarefas de quadro. Esta visualização exibe cada categoria de tarefa como nós sob a mesma raiz e permite que você as expanda para ver as funções. Você também pode passar o mouse sobre qualquer nó na árvore para visualizar as informações de arquivo e linha. Por exemplo, Stepped/CameraInput/<anonimus> pode revelar Players.[LocalPlayer].PlayerScripts.PlayerModule.CameraModule.CameraInput:125.
• Funções: lista todas as funções sem categorizá-las por tarefas.

Você também pode selecionar entre as seguintes opções de exibição para personalizar suas necessidades de depuração:

Exportar dados de profiling

O Profiler de Script permite que você exporte dados de profiling gravados como um arquivo JSON. Para exportar dados gravados após uma sessão de profiling:

1. Na janela do Profiler de Script, clique em Exportar.

2. Na janela de exportação, selecione a sessão de profiling que você deseja exportar. Renomeie o nome do arquivo padrão se quiser definir um nome personalizado.

3. Clique em Exportar para salvar o arquivo JSON.

   

O arquivo JSON exportado inclui os seguintes campos:

• Versão: O número da versão.
• SessionStartTime: Um timestamp em milissegundos que registra o horário de início da sessão.
• SessionEndTime: Um timestamp em milissegundos que registra o horário de término da sessão.
• Categorias: Um array de categorias de tarefas de quadro registradas na sessão de profiling. Cada entrada inclui:

  • Nome: O nome de cada categoria de tarefa de quadro.
  • NodeId: O identificador único de uma categoria de tarefa (nó). É um índice baseado em 1 no array Nodes. Por exemplo, você pode procurar o nó com o NodeId de 123 recuperando o 123º elemento em Nodes.
• Nodes: Um array de nós registrados na sessão de profiling. Cada entrada inclui:

  • TotalDuration: A quantidade de tempo que o nó custa em tempo de CPU em microssegundos.
  • FunctionIds: Um array de identificadores únicos de funções.
  • NodeIds: Um array de IDs de nó.
• Funções: Um array de funções registradas na sessão de profiling.

  • TotalDuration: A quantidade de tempo que a função custa em tempo de CPU em microssegundos.
  • Nome: O nome da função, se disponível.
  • Source: A origem da função, se disponível.
  • Linha: O número da linha da função, se disponível.
  • Flags: Um campo de bits que indica qualquer ambiente de execução de função específico. Atualmente pode ter os seguintes valores:

    • 0: O 0º bit representa IsNative para execução sob Native CodeGen.
    • 1: O 1º bit representa IsPlugin para execução como parte de um plugin.

Exemplo de Dados de Profiling Exportados
{
  "Version":2,
  "SessionStartTime":1704850750514,
  "SessionEndTime":1704850751198,
  "Categories":
  [
    {"Name":"Parallel Luau","NodeId":4},
    {"Name":"Heartbeat","NodeId":1}
  ],
  "Nodes":
  [
      {"TotalDuration":2530,"FunctionIds":[1],"NodeIds":[2]},
      {"TotalDuration":2530,"FunctionIds":[2,5],"NodeIds":[3,7]},
      {"TotalDuration":1267},
      {"TotalDuration":7746,"FunctionIds":[3],"NodeIds":[5]},
      {"TotalDuration":7746,"FunctionIds":[4],"NodeIds":[6]},
      {"TotalDuration":7746},
      {"TotalDuration":1263,"FunctionIds":[6],"NodeIds":[8]},
      {"TotalDuration":1263,"FunctionIds":[7],"NodeIds":[9]},
      {"TotalDuration":1263,"FunctionIds":[8],"NodeIds":[10]},
      {"TotalDuration":1263}
  ],
  "Functions":
  [
    {"Name":"main","TotalDuration":2530},
    {"Source":"builtin_ManageCollaborators.rbxm.ManageCollaborators.Packages._Index.roblox_rodux-3.0.0.rodux.Store","Line":81,"TotalDuration":1267},
    {"Name":"Script","TotalDuration":7746},
    {"Source":"Workspace.Actor.Script","Line":1,"TotalDuration":7746},
    {"Source":"builtin_DeveloperInspector.rbxm.DeveloperInspector.Packages._Index.DeveloperFramework.DeveloperFramework.UI.Components.Grid","Line":221,"TotalDuration":1263},
    {"Source":"builtin_DeveloperInspector.rbxm.DeveloperInspector.Packages._Index.DeveloperFramework.DeveloperFramework.UI.Components.Grid","Name":"_update","Line":236,"TotalDuration":1263},
    {"Source":"builtin_DeveloperInspector.rbxm.DeveloperInspector.Packages._Index.DeveloperFramework.DeveloperFramework.UI.Components.Grid","Name":"_getRange","Line":277,"TotalDuration":1263},
    {"Source":"[C]","Name":"ScrollingFrame.CanvasPosition","TotalDuration":1263}
  ]
}