Codeunit 8703 Feature Telemetry

System Application, System.Telemetry

src/System Application/App/Telemetry/src/Feature Telemetry/FeatureTelemetry.Codeunit.al286 lines, Copyright (c) Microsoft Corporation. MIT

// ------------------------------------------------------------------------------------------------// Copyright (c) Microsoft Corporation. All rights reserved.// Licensed under the MIT License. See License.txt in the project root for license information.// ------------------------------------------------------------------------------------------------namespace System.Telemetry;/// <summary>/// Provides functionality for emitting telemetry in a universal format. Only system metadata is to be emitted through this codeunit./// </summary>/// <remarks>/// Every publisher needs to have an implementation of the "Telemetry Logger" interface and a subscriber/// to "Telemetry Loggers".OnRegisterTelemetryLogger event in one of their apps in order for this codeunit/// to work as expected (see "System Telemetry Logger" codeunit)./// </remarks>codeunit 8703 "Feature Telemetry"{    Access = Public;    InherentEntitlements = X;    InherentPermissions = X;    var        FeatureTelemetryImpl: Codeunit "Feature Telemetry Impl.";    /// <summary>    /// Sends telemetry about feature usage.    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <example>FeatureTelemetry.LogUsage('0000XYZ', 'Emailing', 'Email sent');</example>    procedure LogUsage(EventId: Text; FeatureName: Text; EventName: Text)    var        CallerModuleInfo: ModuleInfo;        CustomDimensions: Dictionary of [Text, Text];    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogUsage(EventId, FeatureName, EventName, CustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about feature usage.    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <param name="CustomDimensions">A dictionary containing additional information about the event.</param>    /// <remarks>Custom dimensions often contain information translated in different languages. It is a common practice to send telemetry in the default language (see example).</remarks>    /// <example>    /// TranslationHelper.SetGlobalLanguageToDefault();    /// CustomDimensions.Add('JobQueueObjectType', Format(JobQueueEntry."Object Type to Run"));    /// CustomDimensions.Add('JobQueueObjectId', Format(JobQueueEntry."Object ID to Run"));    /// FeatureTelemetry.LogUsage('0000XYZ', 'Job Queue', 'Job executed', CustomDimensions);    /// TranslationHelper.RestoreGlobalLanguage();    /// </example>    procedure LogUsage(EventId: Text; FeatureName: Text; EventName: Text; CustomDimensions: Dictionary of [Text, Text])    var        CallerModuleInfo: ModuleInfo;    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogUsage(EventId, FeatureName, EventName, CustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about feature usage (with the capability to send to ISVs).    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <param name="ALTelemetryScope">The telemetry scope of the message.</param>    /// <param name="CustomDimensions">A dictionary containing additional information about the event.</param>    /// <remarks>Custom dimensions often contain information translated in different languages. It is a common practice to send telemetry in the default language (see example).</remarks>    /// <example>    /// TranslationHelper.SetGlobalLanguageToDefault();    /// CustomDimensions.Add('JobQueueObjectType', Format(JobQueueEntry."Object Type to Run"));    /// CustomDimensions.Add('JobQueueObjectId', Format(JobQueueEntry."Object ID to Run"));    /// FeatureTelemetry.LogUsage('0000XYZ', 'Job Queue', 'Job executed', CustomDimensions);    /// TranslationHelper.RestoreGlobalLanguage();    /// </example>    internal procedure LogUsage(EventId: Text; FeatureName: Text; EventName: Text; ALTelemetryScope: Enum "AL Telemetry Scope"; CustomDimensions: Dictionary of [Text, Text])    var        CallerModuleInfo: ModuleInfo;        CallerCallStackModuleInfos: List of [ModuleInfo];    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        case ALTelemetryScope of            Enum::"AL Telemetry Scope"::All:                begin                    CallerCallStackModuleInfos := NavApp.GetCallerCallstackModuleInfos();                    FeatureTelemetryImpl.LogUsage(EventId, FeatureName, EventName, CustomDimensions, CallerModuleInfo, CallerCallStackModuleInfos);                end;            else                FeatureTelemetryImpl.LogUsage(EventId, FeatureName, EventName, CustomDimensions, CallerModuleInfo);        end;    end;    /// <summary>    /// Sends telemetry about errors happening during feature usage.    /// </summary>    /// <param name="EventId">A unique ID of the error.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <param name="ErrorText">The text of the error.</param>    /// <example>    /// if not Success then    ///     FeatureTelemetry.LogError('0000XYZ', 'Retention policies', 'Applying a policy', GetLastErrorText(true));    /// </example>    procedure LogError(EventId: Text; FeatureName: Text; EventName: Text; ErrorText: Text)    var        CallerModuleInfo: ModuleInfo;        DummyCustomDimensions: Dictionary of [Text, Text];        DummyErrorCallStack: Text;    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogError(EventId, FeatureName, EventName, ErrorText, DummyErrorCallStack, DummyCustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about errors happening during feature usage.    /// </summary>    /// <param name="EventId">A unique ID of the error.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <param name="ErrorText">The text of the error.</param>    /// <param name="ErrorCallStack">The error call stack.</param>    /// <example>    /// if not Success then    ///     FeatureTelemetry.LogError('0000XYZ', 'Configuration packages', 'Importing a package', GetLastErrorText(true), GetLastErrorCallStack());    /// </example>    procedure LogError(EventId: Text; FeatureName: Text; EventName: Text; ErrorText: Text; ErrorCallStack: Text)    var        CallerModuleInfo: ModuleInfo;        DummyCustomDimensions: Dictionary of [Text, Text];    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogError(EventId, FeatureName, EventName, ErrorText, ErrorCallStack, DummyCustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about errors happening during feature usage.    /// </summary>    /// <param name="EventId">A unique ID of the error.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <param name="ErrorText">The text of the error.</param>    /// <param name="ErrorCallStack">The error call stack.</param>    /// <param name="CustomDimensions">A dictionary containing additional information about the error.</param>    /// <remarks>Custom dimensions often contain infromation translated in different languages. It is a common practice to send telemetry in the default language (see example).</remarks>    /// <example>    /// if not Success then begin    ///     TranslationHelper.SetGlobalLanguageToDefault();    ///     CustomDimensions.Add('UpdateEntity', Format(AzureADUserUpdateBuffer."Update Entity"));    ///     FeatureTelemetry.LogError('0000XYZ', 'User management', 'Syncing users with M365', GetLastErrorText(true), GetLastErrorCallStack(), CustomDimensions);    ///     TranslationHelper.RestoreGlobalLanguage();    /// end;    /// </example>    procedure LogError(EventId: Text; FeatureName: Text; EventName: Text; ErrorText: Text; ErrorCallStack: Text; CustomDimensions: Dictionary of [Text, Text])    var        CallerModuleInfo: ModuleInfo;    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogError(EventId, FeatureName, EventName, ErrorText, ErrorCallStack, CustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about errors happening during feature usage (with the capability to send to ISVs).    /// </summary>    /// <param name="EventId">A unique ID of the error.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="EventName">The name of the event.</param>    /// <param name="ErrorText">The text of the error.</param>    /// <param name="ErrorCallStack">The error call stack.</param>    /// <param name="ALTelemetryScope">The telemetry scope of the message.</param>    /// <param name="CustomDimensions">A dictionary containing additional information about the error.</param>    /// <remarks>Custom dimensions often contain information translated in different languages. It is a common practice to send telemetry in the default language (see example).</remarks>    /// <example>    /// if not Success then begin    ///     TranslationHelper.SetGlobalLanguageToDefault();    ///     CustomDimensions.Add('UpdateEntity', Format(AzureADUserUpdateBuffer."Update Entity"));    ///     FeatureTelemetry.LogError('0000XYZ', 'User management', 'Syncing users with M365', GetLastErrorText(true), GetLastErrorCallStack(), CustomDimensions);    ///     TranslationHelper.RestoreGlobalLanguage();    /// end;    /// </example>    internal procedure LogError(EventId: Text; FeatureName: Text; EventName: Text; ErrorText: Text; ErrorCallStack: Text; ALTelemetryScope: Enum "AL Telemetry Scope"; CustomDimensions: Dictionary of [Text, Text])    var        CallerModuleInfo: ModuleInfo;        CallerCallStackModuleInfos: List of [ModuleInfo];    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        case ALTelemetryScope of            Enum::"AL Telemetry Scope"::All:                begin                    CallerCallStackModuleInfos := NavApp.GetCallerCallstackModuleInfos();                    FeatureTelemetryImpl.LogError(EventId, FeatureName, EventName, ErrorText, ErrorCallStack, CustomDimensions, CallerModuleInfo, CallerCallStackModuleInfos);                end;            else                FeatureTelemetryImpl.LogError(EventId, FeatureName, EventName, ErrorText, ErrorCallStack, CustomDimensions, CallerModuleInfo);        end;    end;    /// <summary>    /// Sends telemetry about feature uptake.    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="FeatureUptakeStatus">The new status of the feature uptake.</param>    /// <remarks>    /// Expected feature uptake transitions:    /// "Discovered" -> "Set up" -> "Used" (and only in this order; for example, if for a given feature the first status was logged as "Set up", no telemetry will be emitted)    /// *Any state* -> "Undiscovered" (to reset the feature uptake status)    /// </remarks>    procedure LogUptake(EventId: Text; FeatureName: Text; FeatureUptakeStatus: Enum "Feature Uptake Status")    var        CallerModuleInfo: ModuleInfo;        DummyCustomDimensions: Dictionary of [Text, Text];    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogUptake(EventId, FeatureName, FeatureUptakeStatus, false, DummyCustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about feature uptake.    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="FeatureUptakeStatus">The new status of the feature uptake.</param>    /// <param name="CustomDimensions">A dictionary containing additional information about the event.</param>    /// <remarks>    /// Expected feature uptake transitions:    /// "Discovered" -> "Set up" -> "Used" (and only in this order; for example, if for a given feature the first status was logged as "Set up", no telemetry will be emitted)    /// *Any state* -> "Undiscovered" (to reset the feature uptake status)    /// </remarks>    procedure LogUptake(EventId: Text; FeatureName: Text; FeatureUptakeStatus: Enum "Feature Uptake Status"; CustomDimensions: Dictionary of [Text, Text])    var        CallerModuleInfo: ModuleInfo;    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogUptake(EventId, FeatureName, FeatureUptakeStatus, false, CustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about feature uptake.    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="FeatureUptakeStatus">The new status of the feature uptake.</param>    /// <param name="IsPerUser">Specifies if the feature is targeted to be uptaken once for the tenant or uptaken individually by different users.</param>    /// <remarks>    /// Expected feature uptake transitions:    /// "Discovered" -> "Set up" -> "Used" (and only in this order; for example, if for a given feature the first status was logged as "Set up", no telemetry will be emitted)    /// *Any state* -> "Undiscovered" (to reset the feature uptake status)    /// </remarks>    procedure LogUptake(EventId: Text; FeatureName: Text; FeatureUptakeStatus: Enum "Feature Uptake Status"; IsPerUser: Boolean)    var        CallerModuleInfo: ModuleInfo;        DummyCustomDimensions: Dictionary of [Text, Text];    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogUptake(EventId, FeatureName, FeatureUptakeStatus, IsPerUser, DummyCustomDimensions, CallerModuleInfo);    end;    /// <summary>    /// Sends telemetry about feature uptake.    /// </summary>    /// <param name="EventId">A unique ID of the event.</param>    /// <param name="FeatureName">The name of the feature.</param>    /// <param name="FeatureUptakeStatus">The new status of the feature uptake.</param>    /// <param name="IsPerUser">Specifies if the feature is targeted to be uptaken once for the tenant or uptaken individually by different users.</param>    /// <param name="CustomDimensions">A dictionary containing additional information about the event.</param>    /// <remarks>    /// Expected feature uptake transitions:    /// "Discovered" -> "Set up" -> "Used" (and only in this order; for example, if for a given feature the first status was logged as "Set up", no telemetry will be emitted)    /// *Any state* -> "Undiscovered" (to reset the feature uptake status)    /// </remarks>    procedure LogUptake(EventId: Text; FeatureName: Text; FeatureUptakeStatus: Enum "Feature Uptake Status"; IsPerUser: Boolean; CustomDimensions: Dictionary of [Text, Text])    var        CallerModuleInfo: ModuleInfo;    begin        NavApp.GetCallerModuleInfo(CallerModuleInfo);        FeatureTelemetryImpl.LogUptake(EventId, FeatureName, FeatureUptakeStatus, IsPerUser, CustomDimensions, CallerModuleInfo);    end;}