bLogJobCompletionTimes

bLogJobCompletionTimes

#Overview

name: bLogJobCompletionTimes

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bLogJobCompletionTimes is to enable logging of shader compilation job completion times. This setting is primarily used for debugging and performance analysis of the shader compilation process in Unreal Engine 5.

This setting variable is primarily used by the shader compilation subsystem within Unreal Engine. Specifically, it is utilized in the ShaderCompiler module, which is responsible for managing and executing shader compilation tasks.

The value of this variable is set in the engine configuration file (GEngineIni) under the “DevOptions.Shaders” section. It is read during the initialization of the FShaderCompilingManager class.

bLogJobCompletionTimes interacts with other variables and systems related to shader compilation, such as:

  1. WorkerInfos: Information about shader compilation worker threads.
  2. ElapsedTime: The time taken for shader compilation jobs.
  3. QueuedJobs: The list of shader compilation jobs in the queue.

Developers should be aware of the following when using this variable:

  1. Enabling this option may impact performance due to additional logging overhead.
  2. It’s primarily intended for debugging and optimization purposes, not for use in production builds.
  3. The logs produced can be verbose, especially for projects with many shaders.

Best practices when using this variable include:

  1. Use it temporarily for debugging shader compilation issues or performance bottlenecks.
  2. Disable it in production builds to avoid unnecessary overhead.
  3. Combine it with other shader compilation logging options for comprehensive debugging.
  4. Be prepared to handle and analyze potentially large log files when this option is enabled.
  5. Consider using it in conjunction with profiling tools to get a complete picture of shader compilation performance.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1965, section: [DevOptions.Shaders]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:3640

Scope (from outer to inner):

file
function     int32 FShaderCompileThreadRunnable::PullTasksFromQueue

Source code excerpt:

							const double WorkerIdleTime = CurrentWorkerInfo.StartTime - CurrentWorkerInfo.FinishTime;
							GShaderCompilerStats->RegisterLocalWorkerIdleTime(WorkerIdleTime);
							if (Manager->bLogJobCompletionTimes)
							{
								UE_LOG(LogShaderCompilers, Display, TEXT("  Worker (%d/%d) started working after being idle for %fs"), WorkerIndex + 1, WorkerInfos.Num(), WorkerIdleTime);
							}
						}
					}
				}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:3699

Scope (from outer to inner):

file
function     void FShaderCompileThreadRunnable::PushCompletedJobsToManager

Source code excerpt:


			// Log if requested or if there was an exceptionally slow batch, to see the offender easily
			if (Manager->bLogJobCompletionTimes || ElapsedTime > 60.0f)
			{
				TArray<FShaderCommonCompileJobPtr> SortedJobs = CurrentWorkerInfo.QueuedJobs;
				SortedJobs.Sort([](const FShaderCommonCompileJobPtr& JobA, const FShaderCommonCompileJobPtr& JobB)
					{
						const FShaderCompileJob* SingleJobA = JobA->GetSingleShaderJob();
						const FShaderCompileJob* SingleJobB = JobB->GetSingleShaderJob();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:3720

Scope (from outer to inner):

file
function     void FShaderCompileThreadRunnable::PushCompletedJobsToManager

Source code excerpt:

					if (const FShaderCompileJob* SingleJob = Job.GetSingleShaderJob())
					{
						const TCHAR* JobName = Manager->bLogJobCompletionTimes ? *SingleJob->Input.DebugGroupName : SingleJob->Key.ShaderType->GetName();
						JobNames += FString::Printf(TEXT("%s [WorkerTime=%.3fs]"), JobName, SingleJob->Output.CompileTime);
					}
					else
					{
						const FShaderPipelineCompileJob* PipelineJob = Job.GetShaderPipelineJob();
						JobNames += FString(PipelineJob->Key.ShaderPipeline->GetName());

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:5631

Scope (from outer to inner):

file
function     FShaderCompilingManager::FShaderCompilingManager

Source code excerpt:

	verify(GConfig->GetBool( TEXT("DevOptions.Shaders"), TEXT("bPromptToRetryFailedShaderCompiles"), bPromptToRetryFailedShaderCompiles, GEngineIni ));
	verify(GConfig->GetBool(TEXT("DevOptions.Shaders"), TEXT("bDebugBreakOnPromptToRetryShaderCompile"), bDebugBreakOnPromptToRetryShaderCompile, GEngineIni));
	verify(GConfig->GetBool( TEXT("DevOptions.Shaders"), TEXT("bLogJobCompletionTimes"), bLogJobCompletionTimes, GEngineIni ));
	GConfig->GetFloat(TEXT("DevOptions.Shaders"), TEXT("WorkerTimeToLive"), GRegularWorkerTimeToLive, GEngineIni);
	GConfig->GetFloat(TEXT("DevOptions.Shaders"), TEXT("BuildWorkerTimeToLive"), GBuildWorkerTimeToLive, GEngineIni);

	verify(GConfig->GetFloat( TEXT("DevOptions.Shaders"), TEXT("ProcessGameThreadTargetTime"), ProcessGameThreadTargetTime, GEngineIni ));

#if UE_BUILD_DEBUG

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShaderCompiler.h:720

Scope (from outer to inner):

file
class        class FShaderCompilingManager : IAssetCompilingManager

Source code excerpt:

	bool bDebugBreakOnPromptToRetryShaderCompile = false;
	/** Whether to log out shader job completion times on the worker thread.  Useful for tracking down which global shader is taking a long time. */
	bool bLogJobCompletionTimes;
	/** Target execution time for ProcessAsyncResults.  Larger values speed up async shader map processing but cause more hitchiness while async compiling is happening. */
	float ProcessGameThreadTargetTime;
	/** Base directory where temporary files are written out during multi core shader compiling. */
	FString ShaderBaseWorkingDirectory;
	/** Absolute version of ShaderBaseWorkingDirectory. */
	FString AbsoluteShaderBaseWorkingDirectory;