FaultEvent Class

Definition

Namespace:

Microsoft.VisualStudio.Telemetry

Assembly:

Microsoft.VisualStudio.Telemetry.dll

Package:

Microsoft.VisualStudio.Telemetry v17.11.20

A telemetry event representing a Fault, such as an exception We have 2 back ends to send data: the Telemetry back end and the Watson (back end). Cross platform, (as on Mac, Linux), we can use the same architecture. For example, on Mac, there's Merp, the Max implementation of Windows Error Reporting. FaultEvent inherits from TelemetryEvent User can create an instance of this class directly and can add custom properties directly on the class without using call back. After creating one of these, call Session.PostFault(faultEvent) which will call the callback, post the event to Watson (if sampled) and Post as a normal telemetry event Or you can use TelemetrySession.PostFault() rather than this class directly.

public ref class FaultEvent sealed : Microsoft::VisualStudio::Telemetry::TelemetryEvent, Microsoft::VisualStudio::Telemetry::IFaultUtility

public sealed class FaultEvent : Microsoft.VisualStudio.Telemetry.TelemetryEvent, Microsoft.VisualStudio.Telemetry.IFaultUtility

type FaultEvent = class
    inherit TelemetryEvent
    interface IFaultUtility

Public NotInheritable Class FaultEvent
Inherits TelemetryEvent
Implements IFaultUtility

Inheritance

Object

TelemetryEvent

FaultEvent

Implements

IFaultUtility

Constructors

FaultEvent(String, String, Exception, Func<IFaultUtility,Int32>)	Create an uncategorized severity FaultEvent. The pattern: FEvent = new FaultEvent(...) tsession.PostEvent(FEvent) //posts the event to Watson and AI External users should call the TelemetrySession extension methods "PostFault" (which calls PostEvent) It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
FaultEvent(String, String, FaultSeverity, Exception, Func<IFaultUtility,Int32>)	Create a FaultEvent. The pattern: FEvent = new FaultEvent(...) tsession.PostEvent(FEvent) //posts the event to Watson and AI External users should call the TelemetrySession extension methods "PostFault" (which calls PostEvent) It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.

Fields

BucketFiltersToAddProcessDump	Obsolete. This property is obsolete. Use TelemetrySession.BucketFiltersToAddDumpsToFaults to add process dumps to fault events.
BucketFiltersToDisableWatsonReport	Obsolete. This property is obsolete. Use TelemetrySession.BucketFiltersToEnableWatsonForFaults to enable Watson reports for faults. They are now disabled by default instead of enabled by default.

Properties

Correlation	Gets correlation of this event. It represents this event when correlated with other events. (Inherited from TelemetryEvent)
DataSource	Gets data source. (Inherited from TelemetryEvent)
DumpCollectionType	Gets or sets the type of dump that's created for AddProcessDump and sent to Watson AddProcessDump indicates which processes to dump, and DumpCollectionType determines the kind of dump To get a full heap dump, set this value to WER_DUMP_TYPE.WerDumpTypeHeapDump. e.g. (ev as FaultEvent).DumpCollectionType = WER_DUMP_TYPE.WerDumpTypeHeapDump; Another way to set this property is to add a normal Telemetry Property into the TelemetryEvent Property Bag e.g. faultEvent.Properties["DUMPCOLLECTIONTYPE"] = "werdumptypeheapdump"; //works from native code, uses Enum.Parse case insensitive. The property bag setting (usable from native code) will override the Property setting (which is much more discoverable in intellisense) When calling TelemetrySession.PostEvent(faultEvent), WerReportAddDump is called for each process in AddProcesDump with the DumpCollectionType specified. All processes dumped will have the same DumpCollectionType You can control the type of dump (and even whether to send a dump) via remote settings in your GatherEventDetails callback Very useful for collecting heap dumps for those rare cases that are very difficult to debug. Once the issue is fixed, Remote settings can turn this off. Defaults to WER_DUMP_TYPE.WerDumpTypeMiniDump
EventSchemaVersion	Gets schema version for this event. (Inherited from TelemetryEvent)
EventType	Gets event type for this event (Inherited from TelemetryEvent)
HasProperties	Gets a value indicating whether properties already created. (Inherited from TelemetryEvent)
IsIncludedInWatsonSample	Gets or sets a value indicating whether we sample this event locally. Affects Watson only. If false, will not send to Watson: only sends the telemetry event to AI and doesn't call callback. Changing this will force the event to send to Watson. Be careful because it can have big perf impact. If unchanged, it will be set according to the default sample rate. See Microsoft.VisualStudio.Telemetry.WindowsErrorReporting.WatsonReport.DefaultWatsonSamplePercent
IsOptOutFriendly	Gets or sets a value indicating whether event is friendly for the optOut session. By default it is false. If it is OptOut friendly it passes through with the event specific properties only. This behaviour can be changed by manifest rules. (Inherited from TelemetryEvent)
MaximumWatsonReportsPerSession	Gets or sets the maximum number of fault events that will be reported to Watson during the telemetry session.
MinimumSecondsBetweenWatsonReports	Gets or sets the minimum number of seconds that must elapse after a Watson report is sent for a fault event before another report can be sent.
Name	Gets current event name (Inherited from TelemetryEvent)
Properties	Gets a dictionary of event properties. Properties are dimensions that aggregated data can be sliced by. The key is a property name that is unique, not null and not empty. The value is any object that represents a property value. Telemetry channels must use value.ToString(CultureInfo.InvariantCulture) to send the value to a server as a string. (Inherited from TelemetryEvent)
Severity	Gets or sets a severity level of the event. The level is used for event consumer (e.g., ETW provider, backend reporting) to organize data easier. (Inherited from TelemetryEvent)
SharedPropertyBags	Gets shared property bags (Inherited from TelemetryEvent)
SynchronousDumpCollection	Gets or sets a value indicating whether we capture the dump file synchronously or on the threadpool. If we're collecting a dump due to ThreadPool starvation, we don't want to use the ThreadPool to collect the dump (the Threadpool is starved and by the time the dump code is run, the pool is drained)
WatsonEventType	Gets or sets This must be an event type registered on the Watson back end like "VisualStudioNonFatalErrors2". All "normal" FaultEvents should go to VisualStudioNonFatalErrors2 Various Watson event types behave differently. For example the # and retention policy of collected cabs, the routing of cabs. e.g. "VisualStudioMemWatson" is used to collect a stream of cabs to be processed by the PerfWatson backend. These events can be queried from http://Watson .
WatsonSamplePercent	Gets or sets the sample rate used to calculate whether or not a qualifying fault event will be reported to Watson. A fault event qualifies for reporting to Watson if it is modified in at least one of the following methods is called on it: AddErrorInformation AddFile AddProcessDump

Methods

AddErrorInformation(String)	Each Watson cab includes a text file (ErrrorInformation.txt) with basic information such as Error.ToString, telemetry properties, etc. Call this to add information to the file This does the work of creating a unique temp file name per instance and adding standard information NOTE: Calling this will result in the ErrorInformation.txt being marked for PII, and therefore block the CAB upload unless the users' telemetry settings are Full.
AddFile(String)	add a file to the report sent back to Microsoft
AddProcessDump(Int32)	NOTE: When using FaultEvent from VisualStudio, you are strongly encouraged to not directly call AddProcessDump for the current process, but instead remotely trigger it with a targeted notification. Search for "APPLYING BUCKET FILTERS TO FAULT EVENTS" in the VS repo for details. Add the process id of a process for which to collect a dump Dump collection doese not occur unless the Watson back end requests a dump You can request a heap dump for a particular bucket from the Watson portal: https://watsonportal.microsoft.com/. Dump collection is out of process, to reduce chance of deadlock
Correlate(TelemetryEventCorrelation[])	Correlate this event with other events via TelemetryEventCorrelation. (Inherited from TelemetryEvent)
CorrelateWithDescription(TelemetryEventCorrelation, String)	Correlate this event with other event via TelemetryEventCorrelation with description information. (Inherited from TelemetryEvent)
GetBucketParameter(Int32)	Get the value of a bucket parameter
GetDefaultEventProperties(Int64, Int64, String)	Returns default properties that should be on each TelemetryEvent (Inherited from TelemetryEvent)
SetAppName(String)	Set the bucket parameter attributed to the fault's reported app name as processed in Watson and elsewhere. This is automatically set in most instances. You should only change the reported app name in very special circumstances where the app reporting telemetry isn't also the app experiencing the fault.
SetAppVersion(String)	Set the bucket parameter attributed to the fault's reported app version as processed in Watson and elsewhere. This is automatically set in most instances. You should only change the reported app version in very special circumstances where the app reporting telemetry isn't also the app experiencing the fault.
SetBucketParameter(Int32, String)	Set the bucket parameter for a Watson issue Should not contain any full file paths or PII A unique set of 10 bucket parameters constitues a BucketId, which is considered the same failure. When passing in an Exception Object, the bucket parameters are set by the IClrErrorReportingManager::GetBucketParametersForCurrentException
SetFailureParameters(String, String, String, String, String)	Set the bucket parameters which compose the unique Failure ID for the reported fault as processed in Watson and elsewhere. Failure parameters which are left unspecified or passed a null value will retain their original value set by default. See the DevDiv wiki for additional documentation. This is the recommended API to use for customizing the unique failure identification process for your team's faults.
SetNonFailureParameters(String, String)	Set the bucket parameters which compose the non-failure parameters as processed in Watson and elsewhere. Parameters which are left unspecified or passed a null value will retain their original value set by default.
ToString()	ToString to make debugging easier: show in debug watch window