// Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. // See the LICENSE file in the project root for more information. using System.Diagnostics.Tracing; // Use the naming convention MS.Internal.Telemetry.<assemblyname> while adding assemblies to the provider #if WINDOWS_BASE namespace MS.Internal.Telemetry.WindowsBase #elif PRESENTATION_CORE namespace MS.Internal.Telemetry.PresentationCore #elif PRESENTATIONFRAMEWORK namespace MS.Internal.Telemetry.PresentationFramework #else #error Attempt to use Telemetry provider in an unexpected assembly. #error To use the provider in this assembly, update TraceLoggingProvider to support it first. namespace MS.Internal.Telemetry #endif { /// <summary> /// <para> /// An Asimov-enabled EventSource. This inherits from EventSource, and is /// exactly the same as EventSource except that it forces Asimov-compatible /// construction (it always enables EtwSelfDescribingEventFormat and joins the /// MicrosoftTelemetry group). It also provides several Asimov-specific /// constants and helpers. /// </para> /// <para> /// Note that this class DOES NOT automatically add any keywords to your events. /// Even when using this class, events will be ignored by UTC unless they include /// one of the telemetry keywords. Each event that you want to send to UTC must /// have one (and only one) of the following keywords set in /// eventSourceOptions.Keywords: TelemetryKeyword, MeasuresKeyword, or /// CriticalDataKeyword. Use the TelemetryOptions(), MeasuresOptions(), or /// CriticalDataOptions() methods to efficiently create an eventSourceOptions /// object with the corresponding keyword set. /// </para> /// For the authoritative source for the keywords and values <see cref="$(MINWIN_PRIV_SDK_INC_PATH)\telemetry\TelemetryEventSource.cs"/> /// </summary> internal class TelemetryEventSource : EventSource { /// <summary> /// Keyword 0x0000100000000000 is reserved for future definition by UTC. Do /// not use keyword 0x0000100000000000 for telemetry-enabled ETW events. /// </summary> internal const EventKeywords Reserved44Keyword = (EventKeywords)0x0000100000000000; /// <summary> /// Add TelemetryKeyword to eventSourceOptions.Keywords to indicate that /// an event is for general-purpose telemetry. /// This keyword should not be combined with MeasuresKeyword or /// CriticalDataKeyword. /// </summary> internal const EventKeywords TelemetryKeyword = (EventKeywords)0x0000200000000000; /// <summary> /// Add MeasuresKeyword to eventSourceOptions.Keywords to indicate that /// an event is for understanding measures and reporting scenarios. /// This keyword should not be combined with TelemetryKeyword or /// CriticalDataKeyword. /// </summary> internal const EventKeywords MeasuresKeyword = (EventKeywords)0x0000400000000000; /// <summary> /// Add CriticalDataKeyword to eventSourceOptions.Keywords to indicate that /// an event powers user experiences or is critical to business intelligence. /// This keyword should not be combined with TelemetryKeyword or /// MeasuresKeyword. /// </summary> internal const EventKeywords CriticalDataKeyword = (EventKeywords)0x0000800000000000; /// <summary> /// Add CoreData to eventSourceOptions.Tags to indicate that an event /// contains high priority "core data". (Core data is defined by the telemetry /// team. If you think your data is "core data", please work with the telemetry /// team to add your event to the "core data" list before adding this flag to /// your event.) /// </summary> internal const EventTags CoreData = (EventTags)0x00080000; /// <summary> /// Add InjectXToken to eventSourceOptions.Tags to indicate that an XBOX /// identity token should be injected into the event before the event is /// uploaded. /// </summary> internal const EventTags InjectXToken = (EventTags)0x00100000; /// <summary> /// Add RealtimeLatency to eventSourceOptions.Tags to indicate that an event /// should be transmitted in real time (via any available connection). /// </summary> internal const EventTags RealtimeLatency = (EventTags)0x0200000; /// <summary> /// Add NormalLatency to eventSourceOptions.Tags to indicate that an event /// should be transmitted via the preferred connection based on device policy. /// </summary> internal const EventTags NormalLatency = (EventTags)0x0400000; /// <summary> /// Add CriticalPersistence to eventSourceOptions.Tags to indicate that an /// event should be deleted last when low on spool space. /// </summary> internal const EventTags CriticalPersistence = (EventTags)0x0800000; /// <summary> /// Add NormalPersistence to eventSourceOptions.Tags to indicate that an event /// should be deleted first when low on spool space. /// </summary> internal const EventTags NormalPersistence = (EventTags)0x1000000; /// <summary> /// Add DropPii to eventSourceOptions.Tags to indicate that an event contains /// PII and should be anonymized by the telemetry client. If this tag is /// present, PartA fields that might allow identification or cross-event /// correlation will be removed from the event. /// </summary> internal const EventTags DropPii = (EventTags)0x02000000; /// <summary> /// Add HashPii to eventSourceOptions.Tags to indicate that an event contains /// PII and should be anonymized by the telemetry client. If this tag is /// present, PartA fields that might allow identification or cross-event /// correlation will be hashed (obfuscated). /// </summary> internal const EventTags HashPii = (EventTags)0x04000000; /// <summary> /// Add MarkPii to eventSourceOptions.Tags to indicate that an event contains /// PII but may be uploaded as-is. If this tag is present, the event will be /// marked so that it will only appear on the Asimov private stream. /// </summary> internal const EventTags MarkPii = (EventTags)0x08000000; /// <summary> /// Add DropPiiField to eventFieldAttribute.Tags to indicate that a field /// contains PII and should be dropped by the telemetry client. /// </summary> internal const EventFieldTags DropPiiField = (EventFieldTags)0x04000000; /// <summary> /// Add HashPiiField to eventFieldAttribute.Tags to indicate that a field /// contains PII and should be hashed (obfuscated) prior to uploading. /// </summary> internal const EventFieldTags HashPiiField = (EventFieldTags)0x08000000; /// <summary> /// Microsoft OSG Telemetry Group GUID /// </summary> private static readonly string[] telemetryTraits = { "ETW_GROUP", "{4f50731a-89cf-4782-b3e0-dce8c90476ba}" }; /// <summary> /// Constructs a new instance of the TelemetryEventSource class with the /// specified name. Sets the EtwSelfDescribingEventFormat option and joins the /// MicrosoftTelemetry group. /// </summary> /// <param name="eventSourceName">The name of the event source.</param> [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Performance", "CA1811", Justification = "Shared class with tiny helper methods - not all constructors/methods are used by all consumers")] internal TelemetryEventSource(string eventSourceName) : base( eventSourceName, EventSourceSettings.EtwSelfDescribingEventFormat, telemetryTraits ) { return; } /// <summary> /// For use by derived classes that set the eventSourceName via EventSourceAttribute. /// Sets the EtwSelfDescribingEventFormat option and joins the /// MicrosoftTelemetry group. /// </summary> [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Performance", "CA1811", Justification = "Shared class with tiny helper methods - not all constructors/methods are used by all consumers")] protected TelemetryEventSource() : base( EventSourceSettings.EtwSelfDescribingEventFormat, telemetryTraits ) { return; } /// <summary> /// Returns an instance of EventSourceOptions with the TelemetryKeyword set. /// </summary> /// <returns>Returns an instance of EventSourceOptions with the TelemetryKeyword set.</returns> [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Performance", "CA1811", Justification = "Shared class with tiny helper methods - not all constructors/methods are used by all consumers")] internal static EventSourceOptions TelemetryOptions() { return new EventSourceOptions { Keywords = TelemetryKeyword }; } /// <summary> /// Returns an instance of EventSourceOptions with the MeasuresKeyword set. /// </summary> /// <returns>Returns an instance of EventSourceOptions with the MeasuresKeyword set.</returns> [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Performance", "CA1811", Justification = "Shared class with tiny helper methods - not all constructors/methods are used by all consumers")] internal static EventSourceOptions MeasuresOptions() { return new EventSourceOptions { Keywords = MeasuresKeyword }; } /// <summary> /// Returns an instance of EventSourceOptions with the CriticalDataKeyword set. /// </summary> /// <returns>Returns an instance of EventSourceOptions with the CriticalDataKeyword set.</returns> [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Performance", "CA1811", Justification = "Shared class with tiny helper methods - not all constructors/methods are used by all consumers")] internal static EventSourceOptions CriticalDataOptions() { return new EventSourceOptions { Keywords = CriticalDataKeyword }; } } } |