bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/dean-debug/samples/custom-telemetry.md

@@ -0,0 +1,516 @@
+# Custom Telemetry Implementation - AL Code Examples
+
+## Basic Session.LogMessage() Implementation
+
+```al
+// Basic telemetry logging with Session.LogMessage()
+codeunit 50300 "Basic Telemetry Examples"
+{
+    procedure LogBasicEvent()
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // Simple event logging without custom dimensions
+        Session.LogMessage('0001', 'User accessed customer list', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher, '');
+
+        // Event logging with basic custom dimensions
+        CustomDimensions.Add('FeatureName', 'CustomerManagement');
+        CustomDimensions.Add('ActionType', 'ViewList');
+
+        Session.LogMessage('0002', 'Customer list accessed with filters', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+    end;
+}
+```
+
+## Privacy-Compliant Telemetry Patterns
+
+```al
+// Privacy-compliant telemetry implementation
+codeunit 50301 "Privacy Safe Telemetry"
+{
+    procedure LogUserActionSafely(CustomerNo: Code[20]; ActionPerformed: Text)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+        HashedCustomerNo: Text;
+    begin
+        // CORRECT: Hash or anonymize sensitive data
+        HashedCustomerNo := CreateGuid(); // Simplified example - use proper hashing in production
+
+        CustomDimensions.Add('CustomerHash', HashedCustomerNo);
+        CustomDimensions.Add('ActionType', ActionPerformed);
+        CustomDimensions.Add('CompanySize', GetCompanySizeCategory());
+        CustomDimensions.Add('UserRole', GetUserRoleCategory());
+
+        Session.LogMessage('0010', 'Customer action performed', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+    end;
+
+    procedure LogSalesDocumentEvent(DocumentType: Enum "Sales Document Type"; LineCount: Integer)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // CORRECT: Log aggregated, non-sensitive data
+        CustomDimensions.Add('DocumentType', Format(DocumentType));
+        CustomDimensions.Add('LineCountRange', GetLineCountRange(LineCount));
+        CustomDimensions.Add('ProcessingTime', Format(CurrentDateTime - StartTime));
+
+        Session.LogMessage('0011', 'Sales document processed', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+    end;
+
+    local procedure GetCompanySizeCategory(): Text
+    var
+        CustomerCount: Integer;
+        Customer: Record Customer;
+    begin
+        // Categorize without exposing exact counts
+        CustomerCount := Customer.Count();
+
+        case CustomerCount of
+            0..50: exit('Small');
+            51..500: exit('Medium');
+            else exit('Large');
+        end;
+    end;
+
+    local procedure GetLineCountRange(LineCount: Integer): Text
+    begin
+        // Return ranges instead of exact counts for privacy
+        case LineCount of
+            0..5: exit('1-5');
+            6..20: exit('6-20');
+            21..50: exit('21-50');
+            else exit('50+');
+        end;
+    end;
+}
+```
+
+## Error Handling and Performance Monitoring
+
+```al
+// Error handling and performance telemetry
+codeunit 50302 "Error and Performance Telemetry"
+{
+    procedure ProcessWithTelemetry()
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+        StartTime: DateTime;
+        ProcessingDuration: Duration;
+        IsSuccess: Boolean;
+    begin
+        StartTime := CurrentDateTime;
+
+        // Log process start
+        CustomDimensions.Add('ProcessName', 'DataImport');
+        CustomDimensions.Add('StartTime', Format(StartTime));
+
+        Session.LogMessage('0020', 'Data import process started', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+
+        // Perform the actual work with error handling
+        IsSuccess := TryExecuteProcess();
+        ProcessingDuration := CurrentDateTime - StartTime;
+
+        // Log completion with performance metrics
+        Clear(CustomDimensions);
+        CustomDimensions.Add('ProcessName', 'DataImport');
+        CustomDimensions.Add('Duration', Format(ProcessingDuration));
+        CustomDimensions.Add('Success', Format(IsSuccess));
+        CustomDimensions.Add('PerformanceCategory', GetPerformanceCategory(ProcessingDuration));
+
+        if IsSuccess then begin
+            Session.LogMessage('0021', 'Data import completed successfully', Verbosity::Normal,
+                              DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                              CustomDimensions);
+        end else begin
+            // Add error context without exposing sensitive data
+            CustomDimensions.Add('ErrorCategory', GetLastErrorCategory());
+            Session.LogMessage('0022', 'Data import failed', Verbosity::Error,
+                              DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                              CustomDimensions);
+        end;
+    end;
+
+    [TryFunction]
+    local procedure TryExecuteProcess()
+    begin
+        // Simulate work that might fail
+        if Random(10) > 7 then
+            Error('Simulated processing error');
+    end;
+
+    local procedure GetPerformanceCategory(Duration: Duration): Text
+    begin
+        // Categorize performance for analysis
+        if Duration < 1000 then exit('Fast');
+        if Duration < 5000 then exit('Normal');
+        if Duration < 15000 then exit('Slow');
+        exit('VerySlow');
+    end;
+
+    local procedure GetLastErrorCategory(): Text
+    var
+        ErrorText: Text;
+    begin
+        ErrorText := GetLastErrorText();
+
+        // Categorize errors without exposing sensitive details
+        if StrPos(ErrorText, 'permission') > 0 then exit('Permission');
+        if StrPos(ErrorText, 'network') > 0 then exit('Network');
+        if StrPos(ErrorText, 'database') > 0 then exit('Database');
+        if StrPos(ErrorText, 'timeout') > 0 then exit('Timeout');
+        exit('General');
+    end;
+}
+```
+
+## API Usage Telemetry
+
+```al
+// API performance and usage tracking
+codeunit 50303 "API Usage Telemetry"
+{
+    procedure LogAPICall(APIEndpoint: Text; ResponseTime: Duration; Success: Boolean)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // Track API performance and usage patterns
+        CustomDimensions.Add('APIEndpoint', APIEndpoint);
+        CustomDimensions.Add('ResponseTime', Format(ResponseTime));
+        CustomDimensions.Add('Success', Format(Success));
+        CustomDimensions.Add('PerformanceTier', GetAPIPerformanceTier(ResponseTime));
+        CustomDimensions.Add('TimeOfDay', GetTimeCategory());
+
+        Session.LogMessage('0030', 'API call completed', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+    end;
+
+    procedure LogFeatureUsage(FeatureName: Text; FeatureVersion: Text; UsageContext: Text)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // Track feature adoption and usage patterns
+        CustomDimensions.Add('FeatureName', FeatureName);
+        CustomDimensions.Add('FeatureVersion', FeatureVersion);
+        CustomDimensions.Add('UsageContext', UsageContext);
+        CustomDimensions.Add('UserCategory', GetAnonymousUserCategory());
+        CustomDimensions.Add('SessionId', GetSessionHash());
+
+        Session.LogMessage('0031', 'Feature used', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+    end;
+
+    local procedure GetAPIPerformanceTier(ResponseTime: Duration): Text
+    begin
+        if ResponseTime < 500 then exit('Excellent');
+        if ResponseTime < 2000 then exit('Good');
+        if ResponseTime < 5000 then exit('Acceptable');
+        exit('Poor');
+    end;
+
+    local procedure GetTimeCategory(): Text
+    var
+        CurrentTime: Time;
+    begin
+        CurrentTime := Time;
+        if CurrentTime < 090000T then exit('EarlyMorning');
+        if CurrentTime < 120000T then exit('Morning');
+        if CurrentTime < 140000T then exit('Midday');
+        if CurrentTime < 170000T then exit('Afternoon');
+        exit('Evening');
+    end;
+
+    local procedure GetAnonymousUserCategory(): Text
+    var
+        UserSetup: Record "User Setup";
+    begin
+        // Categorize users without identifying them
+        if UserSetup.Get(UserId) then begin
+            if UserSetup."Sales Resp. Ctr. Filter" <> '' then exit('SalesUser');
+            if UserSetup."Purchase Resp. Ctr. Filter" <> '' then exit('PurchaseUser');
+        end;
+        exit('GeneralUser');
+    end;
+
+    local procedure GetSessionHash(): Text
+    begin
+        // Create session identifier without exposing user identity
+        exit(CopyStr(CreateGuid(), 1, 8));
+    end;
+}
+```
+
+## Anti-Pattern Examples (What NOT to Do)
+
+```al
+// ANTI-PATTERNS: Examples of incorrect telemetry implementation
+codeunit 50304 "Telemetry Anti-Patterns"
+{
+    // ❌ WRONG: Logging sensitive customer data
+    procedure BadExample_SensitiveData(CustomerNo: Code[20]; CustomerName: Text)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // ❌ NEVER log personal or sensitive business data
+        CustomDimensions.Add('CustomerNo', CustomerNo);        // Exposes customer identity
+        CustomDimensions.Add('CustomerName', CustomerName);    // Exposes personal data
+        CustomDimensions.Add('CreditLimit', '50000');          // Exposes business sensitive data
+
+        // This violates privacy regulations and security best practices
+        Session.LogMessage('9001', 'Customer accessed - BAD EXAMPLE', Verbosity::Normal,
+                          DataClassification::CustomerContent,  // Wrong classification
+                          TelemetryScope::ExtensionPublisher, CustomDimensions);
+    end;
+
+    // ❌ WRONG: Excessive logging that impacts performance
+    procedure BadExample_ExcessiveLogging()
+    var
+        Customer: Record Customer;
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // ❌ NEVER log inside tight loops without consideration
+        Customer.FindSet();
+        repeat
+            CustomDimensions.Add('CustomerProcessed', Customer."No.");  // Also privacy violation
+            // This will create thousands of telemetry events and impact performance
+            Session.LogMessage('9002', 'Processing customer', Verbosity::Verbose,
+                              DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                              CustomDimensions);
+        until Customer.Next() = 0;
+    end;
+
+    // ❌ WRONG: Poor error logging without context
+    procedure BadExample_PoorErrorLogging()
+    begin
+        // ❌ Logging error without useful context for debugging
+        Session.LogMessage('9003', 'An error occurred', Verbosity::Error,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher, '');
+
+        // Missing: Error category, operation context, environmental factors
+    end;
+
+    // ❌ WRONG: Using wrong telemetry scope and classification
+    procedure BadExample_WrongScope()
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        CustomDimensions.Add('InternalProcessId', CreateGuid());
+
+        // ❌ Wrong scope - should be ExtensionPublisher for app-specific events
+        // ❌ Wrong classification - internal process data shouldn't be CustomerContent
+        Session.LogMessage('9004', 'Internal process', Verbosity::Normal,
+                          DataClassification::CustomerContent,        // Wrong classification
+                          TelemetryScope::All,                        // Wrong scope
+                          CustomDimensions);
+    end;
+}
+```
+
+## Performance-Conscious Telemetry
+
+```al
+// Performance-aware telemetry implementation
+codeunit 50305 "Performance Aware Telemetry"
+{
+    var
+        SamplingRate: Integer;
+        EventCounter: Integer;
+
+    procedure InitializeTelemetry()
+    begin
+        SamplingRate := 5; // 5% sampling for high-frequency events
+        EventCounter := 0;
+    end;
+
+    procedure LogHighFrequencyEvent(EventType: Text)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        EventCounter += 1;
+
+        // Use sampling to reduce telemetry volume
+        if (EventCounter mod (100 div SamplingRate)) = 0 then begin
+            CustomDimensions.Add('EventType', EventType);
+            CustomDimensions.Add('SamplingRate', Format(SamplingRate) + '%');
+            CustomDimensions.Add('EventsSinceLastLog', Format(100 div SamplingRate));
+
+            Session.LogMessage('PERF001', 'Sampled high-frequency event', Verbosity::Normal,
+                              DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                              CustomDimensions);
+        end;
+    end;
+
+    procedure LogBatchOperation(OperationType: Text; RecordCount: Integer; Duration: Duration)
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        // Aggregate telemetry for batch operations
+        CustomDimensions.Add('OperationType', OperationType);
+        CustomDimensions.Add('RecordCountRange', GetRecordCountRange(RecordCount));
+        CustomDimensions.Add('DurationCategory', GetDurationCategory(Duration));
+        CustomDimensions.Add('ThroughputCategory', GetThroughputCategory(RecordCount, Duration));
+
+        Session.LogMessage('PERF002', 'Batch operation completed', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+    end;
+
+    local procedure GetRecordCountRange(RecordCount: Integer): Text
+    begin
+        case RecordCount of
+            0..100: exit('1-100');
+            101..1000: exit('101-1000');
+            1001..10000: exit('1001-10000');
+            else exit('10000+');
+        end;
+    end;
+
+    local procedure GetDurationCategory(Duration: Duration): Text
+    begin
+        if Duration < 1000 then exit('Fast');
+        if Duration < 5000 then exit('Normal');
+        if Duration < 30000 then exit('Slow');
+        exit('VerySlow');
+    end;
+
+    local procedure GetThroughputCategory(RecordCount: Integer; Duration: Duration): Text
+    var
+        RecordsPerSecond: Decimal;
+    begin
+        if Duration = 0 then exit('Instant');
+
+        RecordsPerSecond := RecordCount / (Duration / 1000);
+
+        if RecordsPerSecond > 1000 then exit('High');
+        if RecordsPerSecond > 100 then exit('Medium');
+        exit('Low');
+    end;
+}
+```
+
+## Best Practices Implementation
+
+```al
+// Comprehensive best practices example
+codeunit 50306 "Telemetry Best Practices"
+{
+    procedure ImplementCorrectTelemetry()
+    var
+        CustomDimensions: Dictionary of [Text, Text];
+        StartTime: DateTime;
+        ProcessSuccess: Boolean;
+    begin
+        StartTime := CurrentDateTime;
+
+        // ✅ CORRECT: Use meaningful event IDs and structured messages
+        // ✅ CORRECT: Use appropriate verbosity levels
+        // ✅ CORRECT: Use SystemMetadata classification for telemetry
+        // ✅ CORRECT: Use ExtensionPublisher scope for app events
+
+        CustomDimensions.Add('ProcessType', 'CustomerDataSync');      // Business context
+        CustomDimensions.Add('UserCategory', GetUserCategory());      // Anonymized user info
+        CustomDimensions.Add('CompanySize', GetCompanyCategory());    // Environmental context
+        CustomDimensions.Add('FeatureVersion', '2.1.0');            // Version tracking
+
+        Session.LogMessage('BP001', 'Customer data sync initiated', Verbosity::Normal,
+                          DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                          CustomDimensions);
+
+        // Execute process with proper error handling
+        ProcessSuccess := TryExecuteSync();
+
+        // Log completion with comprehensive context
+        Clear(CustomDimensions);
+        CustomDimensions.Add('ProcessType', 'CustomerDataSync');
+        CustomDimensions.Add('Duration', GetDurationCategory(CurrentDateTime - StartTime));
+        CustomDimensions.Add('Success', Format(ProcessSuccess));
+
+        if ProcessSuccess then begin
+            CustomDimensions.Add('Outcome', 'Success');
+            Session.LogMessage('BP002', 'Customer data sync completed successfully', Verbosity::Normal,
+                              DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                              CustomDimensions);
+        end else begin
+            CustomDimensions.Add('Outcome', 'Failed');
+            CustomDimensions.Add('ErrorCategory', GetErrorCategory());
+            Session.LogMessage('BP003', 'Customer data sync failed', Verbosity::Error,
+                              DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher,
+                              CustomDimensions);
+        end;
+    end;
+
+    [TryFunction]
+    local procedure TryExecuteSync()
+    begin
+        // Simulate sync operation that might fail
+        Sleep(Random(5000));
+        if Random(10) > 8 then
+            Error('Simulated sync failure');
+    end;
+
+    local procedure GetUserCategory(): Text
+    begin
+        // Return user role category without identifying specific user
+        exit('Administrator'); // Simplified - implement actual role detection
+    end;
+
+    local procedure GetCompanyCategory(): Text
+    begin
+        // Return company size category for environmental context
+        exit('Medium'); // Simplified - implement actual size detection
+    end;
+
+    local procedure GetDurationCategory(Duration: Duration): Text
+    begin
+        if Duration < 2000 then exit('Fast');
+        if Duration < 10000 then exit('Normal');
+        exit('Slow');
+    end;
+
+    local procedure GetErrorCategory(): Text
+    var
+        ErrorText: Text;
+    begin
+        ErrorText := LowerCase(GetLastErrorText());
+
+        if StrPos(ErrorText, 'permission') > 0 then exit('Permission');
+        if StrPos(ErrorText, 'network') > 0 then exit('Network');
+        if StrPos(ErrorText, 'timeout') > 0 then exit('Timeout');
+        exit('General');
+    end;
+}
+```
+
+## Key Implementation Guidelines
+
+### Event ID Strategy
+- Use consistent prefixes for different functional areas
+- Keep IDs unique and sequential within your extension
+- Document ID meanings for long-term maintenance
+
+### Custom Dimensions Best Practices
+- Use descriptive, PascalCase key names
+- Keep values concise but meaningful
+- Limit dimensions per event (5-10 recommended)
+- Use categorical values instead of exact numbers
+
+### Privacy Compliance Checklist
+- Never log customer names, addresses, or identifiable information
+- Use hashing or anonymization for sensitive identifiers
+- Categorize numerical data instead of exact values
+- Review all telemetry for privacy violations before deployment
+
+### Performance Considerations
+- Avoid telemetry in tight loops
+- Use sampling for high-frequency events
+- Aggregate data for batch operations
+- Monitor telemetry impact on application performance