bc-code-intelligence-mcp 1.3.3 → 1.3.4

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

@@ -1,516 +0,0 @@
-# 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