Diagnostics maintain an always-on, in-memory log of recent diagnostic messages that can be written out to help investigate bugs and troubleshoot issues. More...

#include <Diagnostics.h>

Classes
struct	ArtifactProviderEntry
struct	Attachments
	The bundle directory and the files written into it, recorded as each one is created so a file that could not be written is simply absent. More...
struct	Report
	The state a triager needs to make sense of a bug report. More...

Public Types
using	ArtifactProvider = std::function<std::string()>
	Supplies an artifact's contents on demand.
using	ArtifactProviderID = uint64_t

Public Member Functions
	Diagnostics ()
	~Diagnostics ()
llvm::Error	Create (const FileSpec &dir)
	Write the in-memory diagnostic log into the given directory.
llvm::Expected< Report >	Collect (Debugger &debugger, const ExecutionContext &exe_ctx, const FileSpec &dir)
	Collect a full diagnostics bundle into `dir` and return its report.
void	Record (llvm::StringRef message)
	Record a diagnostic message into the always-on, in-memory log.
ArtifactProviderID	AddArtifactProvider (std::string name, ArtifactProvider provider)
	Register `provider` to contribute file `name`.
void	RemoveArtifactProvider (ArtifactProviderID id)
	Unregister a provider. Thread-safe.

bool	Dump (llvm::raw_ostream &stream)
	Write the diagnostic log into a directory and print a message to the given output stream.
bool	Dump (llvm::raw_ostream &stream, const FileSpec &dir)

Static Public Member Functions
static Diagnostics &	Instance ()
static DiagnosticsProperties &	GetGlobalProperties ()
static bool	Enabled ()
static void	Initialize ()
static void	Terminate ()
static llvm::Expected< FileSpec >	CreateUniqueDirectory ()
	Create a unique diagnostic directory.

Private Member Functions
llvm::Error	DumpDiangosticsLog (const FileSpec &dir) const

Static Private Member Functions
static std::optional< Diagnostics > &	InstanceImpl ()

static std::string	GetHostDescription (const ExecutionContext &exe_ctx)
	Scalars carried in the report rather than written as files.
static std::string	GetInvocation ()

Private Attributes
RotatingLogHandler	m_log_handler

ArtifactProviderID	m_next_artifact_provider_id = 0
	Registered artifact providers, guarded by the mutex.
std::vector< ArtifactProviderEntry >	m_artifact_providers
std::mutex	m_artifact_providers_mutex
static void	CollectStatistics (Debugger &debugger, const ExecutionContext &exe_ctx, const FileSpec &dir, std::vector< std::string > &files)
static void	CollectCommands (Debugger &debugger, const ExecutionContext &exe_ctx, const FileSpec &dir, std::vector< std::string > &files)
static void	CollectBinaries (const ExecutionContext &exe_ctx, const FileSpec &dir, std::vector< std::string > &files)
void	CollectLogs (Debugger &debugger, const FileSpec &dir, std::vector< std::string > &files)
	Collect the individual parts of the bundle into `dir`, appending the name of each file to `files` as it is written.
void	CollectArtifactProviders (const FileSpec &dir, std::vector< std::string > &files)

Detailed Description

Diagnostics maintain an always-on, in-memory log of recent diagnostic messages that can be written out to help investigate bugs and troubleshoot issues.

Definition at line 49 of file Diagnostics.h.

Member Typedef Documentation

◆ ArtifactProvider

using lldb_private::Diagnostics::ArtifactProvider = std::function<std::string()>

Supplies an artifact's contents on demand.

Subsystems register a provider so Core need not depend on them. Each runs when a bundle is collected.

Definition at line 99 of file Diagnostics.h.

◆ ArtifactProviderID

using lldb_private::Diagnostics::ArtifactProviderID = uint64_t

Definition at line 100 of file Diagnostics.h.

Constructor & Destructor Documentation

◆ Diagnostics()

Diagnostics::Diagnostics ( )

Definition at line 103 of file Diagnostics.cpp.

References g_num_log_messages, and m_log_handler.

Referenced by Instance().

◆ ~Diagnostics()

Diagnostics::~Diagnostics ( )

Definition at line 105 of file Diagnostics.cpp.

Member Function Documentation

◆ AddArtifactProvider()

Diagnostics::ArtifactProviderID Diagnostics::AddArtifactProvider	(	std::string	name,
		ArtifactProvider	provider )

Register provider to contribute file name.

Returns an id for RemoveArtifactProvider. Thread-safe.

Definition at line 161 of file Diagnostics.cpp.

References m_artifact_providers, m_artifact_providers_mutex, and m_next_artifact_provider_id.

Referenced by lldb_private::process_gdb_remote::ProcessGDBRemote::ProcessGDBRemote().

◆ Collect()

llvm::Expected< Diagnostics::Report > Diagnostics::Collect	(	Debugger &	debugger,
		const ExecutionContext &	exe_ctx,
		const FileSpec &	dir )

Collect a full diagnostics bundle into dir and return its report.

Writes the always-on log, the debugger's file-backed logs, statistics, and a snapshot of the commands a triager runs first. When the collect-binaries setting is enabled it also copies the executable, its symbol file, and the core file. Collection is best-effort: a failure to produce one artifact never aborts the rest, so a partial bundle is always better than none.

Definition at line 264 of file Diagnostics.cpp.

References lldb_private::Diagnostics::Report::attachments, CollectArtifactProviders(), CollectBinaries(), CollectCommands(), CollectLogs(), CollectStatistics(), lldb_private::Diagnostics::Attachments::directory, lldb_private::Diagnostics::Attachments::files, GetGlobalProperties(), GetHostDescription(), GetInvocation(), lldb_private::FileSpec::GetPath(), lldb_private::Language::GetVersionWithLanguageInfo(), lldb_private::Diagnostics::Report::invocation, lldb_private::Diagnostics::Report::os, and lldb_private::Diagnostics::Report::version.

Referenced by CommandObjectDiagnosticsDump::DoExecute(), and CommandObjectDiagnosticsReport::DoExecute().

◆ CollectArtifactProviders()

void Diagnostics::CollectArtifactProviders	(	const FileSpec &	dir,
		std::vector< std::string > &	files )

private

Definition at line 344 of file Diagnostics.cpp.

References m_artifact_providers, m_artifact_providers_mutex, and WriteArtifact().

Referenced by Collect().

◆ CollectBinaries()

void Diagnostics::CollectBinaries	(	const ExecutionContext &	exe_ctx,
		const FileSpec &	dir,
		std::vector< std::string > &	files )

staticprivate

Definition at line 328 of file Diagnostics.cpp.

References CopyBinary(), lldb_private::ExecutionContext::GetProcessPtr(), and lldb_private::ExecutionContext::GetTargetPtr().

Referenced by Collect().

◆ CollectCommands()

void Diagnostics::CollectCommands	(	Debugger &	debugger,
		const ExecutionContext &	exe_ctx,
		const FileSpec &	dir,
		std::vector< std::string > &	files )

staticprivate

Definition at line 313 of file Diagnostics.cpp.

References Available(), CaptureCommand(), g_triage_commands, and WriteArtifact().

Referenced by Collect().

◆ CollectLogs()

void Diagnostics::CollectLogs	(	Debugger &	debugger,
		const FileSpec &	dir,
		std::vector< std::string > &	files )

private

Collect the individual parts of the bundle into dir, appending the name of each file to files as it is written.

Definition at line 287 of file Diagnostics.cpp.

References lldb_private::Debugger::CopyLogFilesToDirectory(), Create(), and error().

Referenced by Collect().

◆ CollectStatistics()

void Diagnostics::CollectStatistics	(	Debugger &	debugger,
		const ExecutionContext &	exe_ctx,
		const FileSpec &	dir,
		std::vector< std::string > &	files )