An interface for managing a collection of crash report files and metadata associated with the crash reports. More...

#include "client/crash_report_database.h"

Inheritance diagram for crashpad::CrashReportDatabase:

Classes
class	NewReport
	A crash report that is in the process of being written. More...

struct	Report
	A crash report record. More...

class	UploadReport
	A crash report that is in the process of being uploaded. More...

Public Types
enum	OperationStatus
	The result code for operations performed on a database. More...

Public Member Functions
	CrashReportDatabase (const CrashReportDatabase &)=delete

CrashReportDatabase &	operator= (const CrashReportDatabase &)=delete

virtual Settings *	GetSettings ()=0
	Returns the Settings object for this database.

virtual OperationStatus	PrepareNewCrashReport (std::unique_ptr< NewReport > *report)=0
	Creates a record of a new crash report.

virtual OperationStatus	FinishedWritingCrashReport (std::unique_ptr< NewReport > report, UUID *uuid)=0
	Informs the database that a crash report has been successfully written.

virtual OperationStatus	LookUpCrashReport (const UUID &uuid, Report *report)=0
	Returns the crash report record for the unique identifier.

virtual OperationStatus	GetPendingReports (std::vector< Report > *reports)=0
	Returns a list of crash report records that have not been uploaded.

virtual OperationStatus	GetCompletedReports (std::vector< Report > *reports)=0
	Returns a list of crash report records that have been completed, either by being uploaded or by skipping upload.

virtual OperationStatus	GetReportForUploading (const UUID &uuid, std::unique_ptr< const UploadReport > *report, bool report_metrics=true)=0
	Obtains and locks a report object for uploading to a collection server. On iOS the file lock is released and mutual-exclusion is kept via a file attribute.

OperationStatus	RecordUploadComplete (std::unique_ptr< const UploadReport > report, const std::string &id)
	Records a successful upload for a report and updates the last upload attempt time as returned by Settings::GetLastUploadAttemptTime().

virtual OperationStatus	SkipReportUpload (const UUID &uuid, Metrics::CrashSkippedReason reason)=0
	Moves a report from the pending state to the completed state, but without the report being uploaded.

virtual OperationStatus	DeleteReport (const UUID &uuid)=0
	Deletes a crash report file and its associated metadata.

virtual OperationStatus	RequestUpload (const UUID &uuid)=0
	Marks a crash report as explicitly requested to be uploaded by the user and moves it to 'pending' state.

virtual int	CleanDatabase (time_t lockfile_ttl)
	Cleans the database of expired lockfiles, metadata without report files, report files without metadata, and attachments without report files.

Static Public Member Functions
static std::unique_ptr< CrashReportDatabase >	Initialize (const base::FilePath &path)
	Opens a database of crash reports, possibly creating it.

static std::unique_ptr< CrashReportDatabase >	InitializeWithoutCreating (const base::FilePath &path)
	Opens an existing database of crash reports.

Protected Member Functions
virtual base::FilePath	DatabasePath ()=0
	The path to the database passed to Initialize.

base::FilePath	AttachmentsRootPath ()
	Build a filepath for the root attachments directory.

base::FilePath	AttachmentsPath (const UUID &uuid)
	Build a filepath for the directory for the report to hold attachments.

void	RemoveAttachmentsByUUID (const UUID &uuid)
	Attempts to remove any attachments associated with the given report UUID. There may not be any, so failing is not an error.

Detailed Description

An interface for managing a collection of crash report files and metadata associated with the crash reports.

All Report objects that are returned by this class are logically const. They are snapshots of the database at the time the query was run, and the data returned is liable to change after the query is executed.

The lifecycle of a crash report has three stages:

New: A crash report is created with PrepareNewCrashReport(), the the client then writes the report, and then calls FinishedWritingCrashReport() to make the report Pending.
Pending: The report has been written but has not been locally processed, or it was has been brought back from 'Completed' state by user request.
Completed: The report has been locally processed, either by uploading it to a collection server and calling RecordUploadComplete(), or by calling SkipReportUpload().

Member Enumeration Documentation

◆ OperationStatus

enum crashpad::CrashReportDatabase::OperationStatus

The result code for operations performed on a database.

Enumerator
kNoError	No error occurred.
kReportNotFound	The report that was requested could not be located. This may occur when the report is present in the database but not in a state appropriate for the requested operation, for example, if GetReportForUploading() is called to obtain report that’s already in the completed state.
kFileSystemError	An error occured while performing a file operation on a crash report. A database is responsible for managing both the metadata about a report and the actual crash report itself. This error is returned when an error occurred when managing the report file. Additional information will be logged.
kDatabaseError	An error occured while recording metadata for a crash report or database-wide settings. A database is responsible for managing both the metadata about a report and the actual crash report itself. This error is returned when an error occurred when managing the metadata about a crash report or database-wide settings. Additional information will be logged.
kBusyError	The operation could not be completed because a concurrent operation affecting the report is occurring.
kCannotRequestUpload	The report cannot be uploaded by user request as it has already been uploaded.

Member Function Documentation

◆ AttachmentsPath()

base::FilePath crashpad::CrashReportDatabase::AttachmentsPath ( const UUID & uuid )

protected

Build a filepath for the directory for the report to hold attachments.

Parameters

[in] uuid The unique identifier for the crash report record.

Returns: The filepath to the report attachments directory.

◆ AttachmentsRootPath()

base::FilePath crashpad::CrashReportDatabase::AttachmentsRootPath ( )

protected

Build a filepath for the root attachments directory.

Returns: The filepath to the attachments directory.

◆ CleanDatabase()

virtual int crashpad::CrashReportDatabase::CleanDatabase ( time_t lockfile_ttl )

inlinevirtual

Cleans the database of expired lockfiles, metadata without report files, report files without metadata, and attachments without report files.

As the macOS implementation does not use lock or metadata files, the cleaning is limited to attachments without report files.

Parameters

[in] lockfile_ttl The number of seconds at which lockfiles or new report files are considered expired.

Returns: The number of reports cleaned.

Reimplemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ DatabasePath()

virtual base::FilePath crashpad::CrashReportDatabase::DatabasePath ( )

protectedpure virtual

The path to the database passed to Initialize.

Returns: The filepath of the database;

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ DeleteReport()

virtual OperationStatus crashpad::CrashReportDatabase::DeleteReport ( const UUID & uuid )

pure virtual

Deletes a crash report file and its associated metadata.

Parameters

[in] uuid The UUID of the report to delete.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ FinishedWritingCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::FinishedWritingCrashReport	(	std::unique_ptr< NewReport >	report,
		UUID *	uuid )

pure virtual

Informs the database that a crash report has been successfully written.

Parameters

[in]	report	A NewReport obtained with PrepareNewCrashReport(). The NewReport object will be invalidated as part of this call.
[out]	uuid	The UUID of this crash report.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ GetCompletedReports()

virtual OperationStatus crashpad::CrashReportDatabase::GetCompletedReports ( std::vector< Report > * reports )

pure virtual

Returns a list of crash report records that have been completed, either by being uploaded or by skipping upload.

Parameters

[out] reports A list of crash report record objects. This must be empty on entry. Only valid if this returns kNoError.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ GetPendingReports()

virtual OperationStatus crashpad::CrashReportDatabase::GetPendingReports ( std::vector< Report > * reports )

pure virtual

Returns a list of crash report records that have not been uploaded.

Parameters

[out] reports A list of crash report record objects. This must be empty on entry. Only valid if this returns kNoError.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ GetReportForUploading()

virtual OperationStatus crashpad::CrashReportDatabase::GetReportForUploading	(	const UUID &	uuid,
		std::unique_ptr< const UploadReport > *	report,
		bool	report_metrics = true )

pure virtual

Obtains and locks a report object for uploading to a collection server. On iOS the file lock is released and mutual-exclusion is kept via a file attribute.

Callers should upload the crash report using the FileReader provided. Callers should then call RecordUploadComplete() to record a successful upload. If RecordUploadComplete() is not called, the upload attempt will be recorded as unsuccessful and the report lock released when report is destroyed.

On iOS, holding a lock during a slow upload can lead to watchdog kills if the app is suspended mid-upload. Instead, if the client can obtain the lock, the database sets a lock-time file attribute and releases the lock. The attribute is cleared when the upload is completed. The lock-time attribute can be used to prevent file access from other processes, or to discard reports that likely were terminated mid-upload.

Parameters

[in]	uuid	The unique identifier for the crash report record.
[out]	report	A crash report record for the report to be uploaded. Only valid if this returns kNoError.
[in]	report_metrics	If `false`, metrics will not be recorded for this upload attempt when RecordUploadComplete() is called or report is destroyed. Metadata for the upload attempt will still be recorded in the database.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ GetSettings()

virtual Settings * crashpad::CrashReportDatabase::GetSettings ( )

pure virtual

Returns the Settings object for this database.

Returns: A weak pointer to the Settings object, which is owned by the database.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ Initialize()

std::unique_ptr< CrashReportDatabase > crashpad::CrashReportDatabase::Initialize ( const base::FilePath & path )

static

Opens a database of crash reports, possibly creating it.

Parameters

[in] path A path to the database to be created or opened. If the database does not yet exist, it will be created if possible. Note that for databases implemented as directory structures, existence refers solely to the outermost directory.

Returns: A database object on success, nullptr on failure with an error logged.

See also: InitializeWithoutCreating

◆ InitializeWithoutCreating()

std::unique_ptr< CrashReportDatabase > crashpad::CrashReportDatabase::InitializeWithoutCreating ( const base::FilePath & path )

static

Opens an existing database of crash reports.

Parameters

[in] path A path to the database to be opened. If the database does not yet exist, it will not be created. Note that for databases implemented as directory structures, existence refers solely to the outermost directory. On such databases, as long as the outermost directory is present, this method will create the inner structure.

Returns: A database object on success, nullptr on failure with an error logged.

See also: Initialize

◆ LookUpCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::LookUpCrashReport	(	const UUID &	uuid,
		Report *	report )

pure virtual

Returns the crash report record for the unique identifier.

Parameters

[in]	uuid	The crash report record unique identifier.
[out]	report	A crash report record. Only valid if this returns kNoError.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ PrepareNewCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::PrepareNewCrashReport ( std::unique_ptr< NewReport > * report )

pure virtual

Creates a record of a new crash report.

Callers should write the crash report using the FileWriter provided. Callers should then call FinishedWritingCrashReport() to complete report creation. If an error is encountered while writing the crash report, no special action needs to be taken. If FinishedWritingCrashReport() is not called, the report will be removed from the database when report is destroyed.

Parameters

[out] report A NewReport object containing a FileWriter with which to write the report data. Only valid if this returns kNoError.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ RecordUploadComplete()

CrashReportDatabase::OperationStatus crashpad::CrashReportDatabase::RecordUploadComplete	(	std::unique_ptr< const UploadReport >	report,
		const std::string &	id )

Records a successful upload for a report and updates the last upload attempt time as returned by Settings::GetLastUploadAttemptTime().

Parameters

[in]	report	A UploadReport object obtained from GetReportForUploading(). The UploadReport object will be invalidated and the report unlocked as part of this call.
[in]	id	The possibly empty identifier assigned to this crash report by the collection server.

Returns: The operation status code.

◆ RemoveAttachmentsByUUID()

void crashpad::CrashReportDatabase::RemoveAttachmentsByUUID ( const UUID & uuid )

protected

Attempts to remove any attachments associated with the given report UUID. There may not be any, so failing is not an error.

Parameters

[in] uuid The unique identifier for the crash report record.

◆ RequestUpload()

virtual OperationStatus crashpad::CrashReportDatabase::RequestUpload ( const UUID & uuid )

pure virtual

Marks a crash report as explicitly requested to be uploaded by the user and moves it to 'pending' state.

Parameters

[in] uuid The unique identifier for the crash report record.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

◆ SkipReportUpload()

virtual OperationStatus crashpad::CrashReportDatabase::SkipReportUpload	(	const UUID &	uuid,
		Metrics::CrashSkippedReason	reason )

pure virtual

Moves a report from the pending state to the completed state, but without the report being uploaded.

This can be used if the user has disabled crash report collection, but crash generation is still enabled in the product.

Parameters

[in]	uuid	The unique identifier for the crash report record.
[in]	reason	The reason the report upload is being skipped for metrics tracking purposes.

Returns: The operation status code.

Implemented in crashpad::CrashReportDatabaseGeneric, crashpad::CrashReportDatabaseMac, and crashpad::CrashReportDatabaseWin.

The documentation for this class was generated from the following files:

client/crash_report_database.h
client/crash_report_database.cc
client/crash_report_database_generic.cc
client/crash_report_database_mac.mm
client/crash_report_database_win.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ OperationStatus

Member Function Documentation

◆ AttachmentsPath()

◆ AttachmentsRootPath()

◆ CleanDatabase()

◆ DatabasePath()

◆ DeleteReport()

◆ FinishedWritingCrashReport()

◆ GetCompletedReports()

◆ GetPendingReports()

◆ GetReportForUploading()

◆ GetSettings()

◆ Initialize()

◆ InitializeWithoutCreating()

◆ LookUpCrashReport()

◆ PrepareNewCrashReport()

◆ RecordUploadComplete()

◆ RemoveAttachmentsByUUID()

◆ RequestUpload()

◆ SkipReportUpload()