bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/dean-debug/bc24-no-series-conversion-guide.md

@@ -0,0 +1,295 @@
+---
+title: "BC24 No. Series Conversion Guide"
+domain: "dean-debug"
+difficulty: "advanced"
+bc_versions: "24+"
+tags: ["bc24-migration", "no-series-conversion", "legacy-modernization", "breaking-changes", "conversion-guide"]
+prerequisites: ["no-series-implementation-patterns", "no-series-module-patterns-bc24", "business-foundation-architecture"]
+samples: "samples/bc24-no-series-conversion.md"
+related_topics: ["no-series-module-patterns-bc24", "no-series-validation-module-bc24", "no-series-implementation-patterns"]
+---
+
+# BC24 No. Series Conversion Guide
+
+## Overview
+
+This guide provides comprehensive step-by-step instructions for converting legacy No. Series implementations (BC14-23) to the new Business Foundation module architecture (BC24+). It addresses Microsoft's official obsoletions and provides practical conversion strategies.
+
+**Critical Timeline**: NoSeriesManagement (Codeunit 396) is obsolete in BC24.0 - immediate conversion required for compatibility.
+
+## Conversion Overview
+
+### What Changed in BC24
+- **NoSeriesManagement (Codeunit 396)**: Completely obsolete
+- **New Architecture**: Business Foundation modular design
+- **New Codeunits**: No. Series (310), NoSeriesBatch
+- **Table Changes**: Sales/Purchase series tables merged into generic No. Series Line
+- **Method Changes**: Simplified parameter structures and clearer method names
+
+### Conversion Scope Assessment
+Before starting conversion, inventory your codebase:
+
+1. **Search Patterns**: `NoSeriesMgt`, `NoSeriesManagement`
+2. **Method Usage**: `InitSeries`, `GetNextNo`, `TestManual`, `SelectSeries`
+3. **Event Subscriptions**: Any events on obsolete codeunit
+4. **Custom Extensions**: Extensions of NoSeriesManagement
+5. **Table References**: Direct access to No. Series tables
+
+## Step-by-Step Conversion Process
+
+### Step 1: Inventory and Planning
+
+#### Code Discovery
+```al
+// Search your codebase for these patterns:
+// 1. Variable declarations
+var NoSeriesMgt: Codeunit NoSeriesManagement;
+
+// 2. Method calls
+NoSeriesMgt.InitSeries(...)
+NoSeriesMgt.GetNextNo(...)
+NoSeriesMgt.TestManual(...)
+NoSeriesMgt.SelectSeries(...)
+
+// 3. Event subscriptions
+[EventSubscriber(ObjectType::Codeunit, Codeunit::NoSeriesManagement, 'OnBeforeGetNextNo', '', true, true)]
+```
+
+#### Create Conversion Matrix
+| Legacy Method | New Method | Conversion Notes |
+|---------------|------------|------------------|
+| `InitSeries()` | `GetNextNo()` | Simplified parameters |
+| `GetNextNo()` | `GetNextNo()` or `PeekNextNo()` | Choose based on intent |
+| `TestManual()` | `TestManual()` | Same name, new codeunit |
+| `SelectSeries()` | `LookupRelatedNoSeries()` | Different parameter structure |
+
+### Step 2: Core Method Conversions
+
+#### InitSeries Conversion
+**Before (BC14-23)**:
+```al
+var
+    NoSeriesMgt: Codeunit NoSeriesManagement;
+begin
+    NoSeriesMgt.InitSeries(GetNoSeriesCode(), xRec."No. Series", 0D, "No.", "No. Series");
+end;
+```
+
+**After (BC24+)**:
+```al
+var
+    NoSeries: Codeunit "No. Series";
+begin
+    if "No." = '' then
+        "No." := NoSeries.GetNextNo("No. Series", WorkDate());
+end;
+```
+
+#### GetNextNo Conversion
+**Before**:
+```al
+NextNo := NoSeriesMgt.GetNextNo("No. Series", WorkDate(), false); // Peek only
+ActualNo := NoSeriesMgt.GetNextNo("No. Series", WorkDate(), true); // Allocate
+```
+
+**After**:
+```al
+NextNo := NoSeries.PeekNextNo("No. Series", WorkDate()); // Peek only
+ActualNo := NoSeries.GetNextNo("No. Series", WorkDate()); // Allocate
+```
+
+#### Manual Testing Conversion
+**Before**:
+```al
+NoSeriesMgt.TestManual("No. Series");
+if NoSeriesMgt.ManualNoAllowed("No. Series") then
+    AllowManual := true;
+```
+
+**After**:
+```al
+NoSeries.TestManual("No. Series"); // Built-in error handling
+// ManualNoAllowed is replaced by TestManual with automatic error
+```
+
+#### Series Selection Conversion
+**Before**:
+```al
+NoSeriesMgt.SelectSeries("No. Series", xRec."No. Series", "No. Series");
+```
+
+**After**:
+```al
+NoSeries.LookupRelatedNoSeries("No. Series", "No. Series");
+```
+
+### Step 3: Advanced Pattern Conversions
+
+#### Batch Operations
+**New Capability (BC24+)**:
+```al
+var
+    NoSeriesBatch: Codeunit "No. Series - Batch";
+    NumberList: List of [Code[20]];
+begin
+    NumberList := NoSeriesBatch.GetNextNos("No. Series", WorkDate(), BatchSize);
+end;
+```
+
+#### Series Relationship Handling
+**New Pattern (BC24+)**:
+```al
+if NoSeries.AreRelated("Primary Series", "Secondary Series") then
+    // Handle related series logic
+    ProcessRelatedSeries();
+```
+
+### Step 4: Event Migration Strategy
+
+#### Obsolete Events (No Direct Replacement)
+These events are removed in BC24 without direct replacement:
+```al
+// OBSOLETE - Remove these event subscriptions
+[EventSubscriber(ObjectType::Codeunit, Codeunit::NoSeriesManagement, 'OnBeforeGetNextNo', '', true, true)]
+[EventSubscriber(ObjectType::Codeunit, Codeunit::NoSeriesManagement, 'OnAfterGetNextNo', '', true, true)]
+```
+
+#### Alternative Approaches
+```al
+// Replace event-driven logic with direct method calls
+procedure CustomGetNextNo(SeriesCode: Code[20]): Code[20]
+var
+    NoSeries: Codeunit "No. Series";
+    NextNo: Code[20];
+begin
+    // Pre-processing logic (replaces OnBeforeGetNextNo)
+    PreProcessNumberGeneration(SeriesCode);
+
+    // Get number
+    NextNo := NoSeries.GetNextNo(SeriesCode, WorkDate());
+
+    // Post-processing logic (replaces OnAfterGetNextNo)
+    PostProcessNumberGeneration(SeriesCode, NextNo);
+
+    exit(NextNo);
+end;
+```
+
+### Step 5: Error Handling Migration
+
+#### Enhanced Error Messages
+**Before**:
+```al
+if not NoSeriesMgt.TestSeries("No. Series") then
+    Error('Series validation failed');
+```
+
+**After**:
+```al
+// Built-in descriptive error messages
+NoSeries.GetNextNo("No. Series", WorkDate()); // Automatic detailed errors
+```
+
+#### Try-Method Pattern
+**New Approach (BC24+)**:
+```al
+if NoSeries.TryGetNextNo(NextNo, "No. Series", WorkDate()) then
+    ProcessSuccessfulGeneration(NextNo)
+else
+    HandleGenerationFailure("No. Series");
+```
+
+### Step 6: Performance Optimization
+
+#### Reduced Object Coupling
+**Before**: Complex dependencies with NoSeriesManagement
+**After**: Clean dependencies on focused No. Series module
+
+#### Optimized Database Access
+The new module provides better performance through:
+- Reduced database queries
+- Improved caching mechanisms
+- Better concurrency handling
+
+### Step 7: Testing Strategy
+
+#### Functional Testing Checklist
+- [ ] All number generation scenarios work correctly
+- [ ] Manual number entry functions properly
+- [ ] Series relationships are maintained
+- [ ] Date-based generation works as expected
+- [ ] Error handling provides appropriate messages
+
+#### Performance Testing
+- [ ] Number generation performance meets or exceeds legacy performance
+- [ ] High-concurrency scenarios perform adequately
+- [ ] Batch operations show expected performance improvements
+
+#### Regression Testing
+- [ ] Existing number sequences continue to work
+- [ ] No gaps or duplicates in number generation
+- [ ] Business process integration remains functional
+
+## Common Conversion Challenges
+
+### Challenge 1: Event Dependencies
+**Problem**: Code relies on obsolete events
+**Solution**: Redesign logic using direct method calls and procedure composition
+
+### Challenge 2: Parameter Mapping
+**Problem**: New methods have different parameter structures
+**Solution**: Create wrapper procedures during transition period
+
+### Challenge 3: Custom Extensions
+**Problem**: Extensions of NoSeriesManagement no longer work
+**Solution**: Implement custom logic using the new module's extensibility points
+
+### Challenge 4: Complex Validation Logic
+**Problem**: Custom validation tied to obsolete methods
+**Solution**: Leverage new module's built-in validation capabilities
+
+## Conversion Validation
+
+### Pre-Conversion Checklist
+- [ ] Complete inventory of NoSeriesManagement usage
+- [ ] Backup of current implementation
+- [ ] Test plan for all affected scenarios
+- [ ] Rollback strategy prepared
+
+### Post-Conversion Checklist
+- [ ] All obsolete references removed
+- [ ] New module methods properly implemented
+- [ ] Error handling provides appropriate feedback
+- [ ] Performance meets expectations
+- [ ] Documentation updated
+
+### Production Deployment Checklist
+- [ ] Comprehensive testing in sandbox environment
+- [ ] User acceptance testing completed
+- [ ] Deployment runbook prepared
+- [ ] Rollback procedures tested
+
+## Best Practices
+
+### During Conversion
+- Convert one method at a time to minimize risk
+- Test thoroughly after each conversion step
+- Maintain parallel implementations during transition if needed
+- Document all changes for team knowledge transfer
+
+### Post-Conversion
+- Leverage new module capabilities for enhanced functionality
+- Simplify validation logic using built-in methods
+- Monitor performance improvements
+- Plan for future module enhancements
+
+### Team Coordination
+- Establish conversion standards across development team
+- Create shared conversion utilities and wrapper procedures
+- Coordinate timing of conversion across related projects
+- Share lessons learned and best practices
+
+*Complete conversion examples: samples/bc24-no-series-conversion.md*
+*BC24+ implementation patterns: no-series-module-patterns-bc24.md*
+*BC24+ validation patterns: no-series-validation-module-bc24.md*
+*Legacy patterns (reference): no-series-implementation-patterns.md*

package/embedded-knowledge/domains/dean-debug/case-statement-performance-best-practices.md

@@ -0,0 +1,86 @@
+---
+title: "Case Statement Performance and Best Practices"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["case", "performance", "optimization", "control-flow"]
+prerequisites: ["case-statement-syntax", "performance-fundamentals"]
+samples: "samples/case-performance-optimization.md"
+---
+# Case Statement Performance and Best Practices
+
+## Overview
+
+Case statements provide better performance than cascaded IF statements for multiple value comparisons, but optimization strategies can significantly improve execution efficiency. Understanding performance characteristics enables optimal control flow design for high-volume BC operations.
+
+**Performance Principle**: Case statements evaluate expressions once and use efficient jump tables, making them faster than IF chains for multiple conditions.
+
+## Performance Characteristics
+
+### Execution Efficiency
+Case statements compile to efficient jump tables that directly branch to matching code without sequential condition evaluation. This provides O(1) performance compared to IF chains with O(n) sequential evaluation.
+
+### Branch Prediction Benefits
+Modern processors optimize case statements through branch prediction algorithms that learn common execution paths, improving performance for frequently accessed branches.
+
+### Memory Access Patterns
+Well-structured case statements improve cache locality by grouping related operations and reducing memory access overhead during branch execution.
+
+## Optimization Strategies
+
+### Branch Frequency Ordering
+Order case branches by execution frequency, placing most common cases first. This minimizes average execution time by reducing branch traversal for typical scenarios.
+
+### Expression Simplification
+Use simple expressions that evaluate to basic types. Complex expressions in case evaluation create overhead that negates performance benefits.
+
+### Early Exit Patterns
+Structure case logic to enable early exit from processing when possible, avoiding unnecessary computation in less common branches.
+
+## High-Performance Patterns
+
+### Lookup Table Alternative
+For very large case statements, consider lookup tables or dictionary structures that provide constant-time access without case statement overhead.
+
+### Range Optimization
+Use range cases efficiently by grouping consecutive values. Range evaluation is optimized in AL compilers for better performance than individual value matching.
+
+### Resource Management
+Place resource-intensive operations in less frequently executed branches, keeping common cases lightweight and fast-executing.
+
+## Anti-Patterns to Avoid
+
+### Complex Case Expressions
+Avoid complex calculations or method calls in case expressions. Pre-calculate values before case evaluation for optimal performance.
+
+### Nested Case Statements
+Deep case nesting creates performance overhead and reduces code maintainability. Use helper procedures or alternative structures for complex branching logic.
+
+### Resource-Heavy Common Branches
+Avoid placing expensive operations in frequently executed branches. Profile actual usage patterns to optimize for real-world performance.
+
+## Performance Testing
+
+### Benchmarking Approaches
+Compare case statements against IF chains and lookup tables using realistic data volumes and execution patterns. Measure actual performance in production-like scenarios.
+
+### Profiling Integration
+Use BC performance profiling tools to identify case statement bottlenecks and validate optimization effectiveness in real applications.
+
+### Load Testing
+Test case statement performance under high-volume conditions to ensure optimization strategies remain effective at scale.
+
+## Best Practices Summary
+
+### Design Guidelines
+- Order branches by frequency for optimal average performance
+- Keep case expressions simple and avoid complex calculations
+- Use ranges efficiently for consecutive value matching
+- Consider lookup alternatives for very large case statements
+
+### Implementation Standards
+- Profile performance in realistic usage scenarios
+- Avoid deep nesting that reduces performance benefits
+- Place expensive operations in infrequent branches
+- Test optimization effectiveness under load conditions
+

package/embedded-knowledge/domains/dean-debug/compound-statements-debugging.md

@@ -0,0 +1,96 @@
+---
+title: "AL Compound Statements for Enhanced Debugging"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["debugging", "compound-statements", "breakpoints", "code-analysis"]
+prerequisites: ["compound-statement-readability", "al-debugging-basics"]
+samples: "samples/compound-statements-debugging.md"
+---
+# AL Compound Statements for Enhanced Debugging
+
+## Overview
+
+Compound statements significantly enhance AL debugging capabilities by providing explicit breakpoint locations, clear execution boundaries, and structured code organization that simplifies debugging workflows. The begin-end block structure creates natural debugging checkpoints that help developers isolate issues and trace execution flow.
+
+Modern AL debugging environments leverage compound statement structure to provide more precise breakpoint placement and clearer execution visualization. The explicit boundaries created by compound blocks enable debuggers to provide better context information and more accurate step-through debugging experiences.
+
+The debugging benefits of compound statements extend beyond simple breakpoint placement to include improved variable scope visibility, clearer call stack information, and more intuitive debugging navigation through complex business logic implementations.
+
+## Debugging Enhancement Mechanisms
+
+### Breakpoint Precision
+
+Compound statements provide explicit locations for breakpoint placement that correspond to logical execution boundaries rather than arbitrary line positions. Each begin statement offers a natural entry point for debugging that aligns with developer mental models of code execution.
+
+The structured nature of compound blocks allows debuggers to provide more meaningful context when execution stops at breakpoints. Developers can immediately understand the logical scope and purpose of the code being debugged without parsing surrounding syntax.
+
+Breakpoint placement within compound statements creates predictable debugging experiences where execution stops align with logical operations rather than syntactic constructs. This alignment reduces confusion during debugging sessions and improves issue isolation efficiency.
+
+### Execution Flow Visualization
+
+Compound statements create visual boundaries that help debuggers display execution flow more clearly through syntax highlighting and scope indication. The nested structure provides hierarchical context that makes complex execution paths easier to follow during debugging.
+
+When stepping through compound statement blocks, debuggers can provide clearer indication of scope transitions and logical boundary crossings. This enhanced visualization reduces cognitive load during debugging and helps developers maintain context awareness.
+
+The explicit structure enables debugging tools to offer enhanced navigation features like scope-aware stepping that respects logical boundaries rather than purely syntactic line progression.
+
+### Variable Scope Clarity
+
+Compound statements create explicit variable scoping boundaries that debugging environments can leverage to provide more accurate variable visibility and inspection capabilities. Local variables declared within compound blocks have clear lifetime boundaries that debuggers can represent accurately.
+
+The structured scoping enables better watch variable organization where developers can understand variable context and lifetime more intuitively during debugging sessions. Variable inspection becomes more logical when aligned with compound statement structure.
+
+Debugging environments can use compound statement boundaries to provide more accurate variable state tracking and modification detection throughout code execution.
+
+## Debugging Workflow Integration
+
+### Strategic Breakpoint Placement
+
+Use compound statement begin keywords as primary breakpoint locations to ensure execution stops at logical operation boundaries. This approach provides maximum context for debugging while minimizing confusion about execution state.
+
+Place breakpoints at compound statement boundaries to debug conditional logic flow and loop iteration boundaries. These locations provide clear context about decision points and iteration state without requiring mental parsing of surrounding code.
+
+Leverage compound statement structure to create debugging checkpoints that correspond to business logic phases rather than arbitrary code locations. This business-logic alignment improves debugging efficiency and issue isolation accuracy.
+
+### Step-Through Enhancement
+
+Configure debugging environments to respect compound statement boundaries during step-through operations, providing more intuitive navigation through complex code structures. Step-into operations should target logical blocks rather than individual statements when possible.
+
+Use compound statement structure to guide step-over operations that skip entire logical blocks when the internal implementation details aren't relevant to the current debugging focus. This capability reduces debugging time for complex procedures.
+
+Leverage scope-aware stepping that moves between compound statement levels to provide both detailed and overview-level debugging perspectives as needed for different types of issues.
+
+### Exception Context Improvement
+
+Compound statements provide better exception context by creating explicit boundaries around operations that might fail. Exception handlers can reference specific compound blocks that caused errors rather than ambiguous line references.
+
+When exceptions occur within compound statement blocks, debugging environments can provide clearer context about the logical operation that failed and the scope of variables that might be relevant to the error condition.
+
+Use compound statement structure to implement more granular exception handling that provides specific context for different types of failures within complex procedures.
+
+## Advanced Debugging Patterns
+
+### Conditional Debugging
+
+Implement conditional breakpoints within compound statement blocks to debug specific scenarios without stopping execution for every iteration or condition evaluation. The compound structure provides clear logical boundaries for conditional debugging logic.
+
+Use compound statements to create debugging hooks that can be enabled or disabled based on runtime conditions without affecting normal execution flow. These hooks provide detailed debugging information only when specific conditions occur.
+
+Structure compound blocks to support debugging modes where additional logging or state tracking can be enabled within specific logical boundaries without impacting production performance.
+
+### Multi-Level Tracing
+
+Leverage compound statement nesting to implement hierarchical tracing that provides different levels of detail based on debugging needs. Each compound level can provide appropriate tracing granularity for its logical scope.
+
+Use compound statement boundaries to implement trace correlation that helps track related operations across different logical blocks and procedure calls. This correlation improves debugging of complex business processes.
+
+Implement structured logging within compound blocks that provides context-aware debug information aligned with logical operation boundaries rather than arbitrary code locations.
+
+### Performance Debugging
+
+Use compound statement boundaries as natural performance measurement points to identify bottlenecks and optimization opportunities during debugging sessions. The logical boundaries provide meaningful measurement contexts.
+
+Implement performance counters within compound blocks to track execution time and resource usage at logical operation levels rather than individual statement granularity. This approach provides actionable performance debugging information.
+
+Leverage compound statement structure to implement performance debugging that can isolate specific logical operations for detailed analysis without affecting overall procedure performance characteristics.

package/embedded-knowledge/domains/dean-debug/custom-dimensions-best-practices.md

@@ -0,0 +1,70 @@
+---
+title: "Custom Dimensions Best Practices"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["telemetry", "dimensions", "analytics", "monitoring"]
+prerequisites: ["bc-session-logmessage-methods"]
+samples: "samples/custom-dimensions.md"
+---
+# Custom Dimensions Best Practices
+
+## Overview
+
+Custom dimensions transform basic telemetry events into rich, queryable data that enables sophisticated analysis and monitoring. Proper custom dimension design balances diagnostic capability with performance impact and storage efficiency.
+
+Custom dimensions appear as structured fields in Application Insights and other monitoring solutions, enabling filtering, grouping, and correlation analysis. Well-designed dimensions enhance troubleshooting capabilities and business intelligence extraction from telemetry data.
+
+## Dimension Design Principles
+
+### Consistency and Standardization
+Establish consistent naming conventions across all telemetry events. Use standardized dimension names for common concepts like user identification, operation context, and business entity references.
+
+Consistent dimension naming enables effective cross-component analysis and simplifies dashboard creation. Consider creating a telemetry dimension registry to maintain naming standards across development teams.
+
+### Cardinality Management
+Avoid high-cardinality dimensions that create excessive unique value combinations. High cardinality impacts query performance, storage efficiency, and aggregation capabilities in monitoring systems.
+
+Examples of high-cardinality dimensions include timestamps, GUIDs, or detailed error messages. Instead, categorize high-cardinality values or use separate correlation mechanisms for detailed tracking.
+
+### Business Context Integration
+Include dimensions that align with business processes and operational concerns. Business-relevant dimensions enable telemetry analysis that directly supports troubleshooting and process optimization.
+
+Consider dimensions for customer identification, transaction types, document numbers, and business process stages. These dimensions link technical telemetry to business impact analysis.
+
+## Implementation Strategies
+
+### Dimension Categories
+Organize custom dimensions into logical categories: technical context (component, operation), business context (customer, document), and correlation context (session, trace identifiers).
+
+Technical dimensions support system troubleshooting, business dimensions enable process analysis, and correlation dimensions link related events across system boundaries.
+
+### Performance Optimization
+Minimize custom dimension processing overhead by pre-formatting dimension values and reusing dimension collections where appropriate. Avoid complex calculations or expensive operations within dimension value generation.
+
+Consider dimension value caching for frequently-used values and lazy evaluation for expensive dimension calculations that may not be needed in all scenarios.
+
+### Data Classification Alignment
+Ensure custom dimension content aligns with Business Central data classification requirements. Avoid including sensitive data in telemetry dimensions without appropriate classification and protection measures.
+
+## Common Anti-Patterns
+
+### Excessive Dimensions
+Including too many custom dimensions per telemetry event creates storage bloat and complicates analysis. Focus on dimensions that provide actual analytical value rather than comprehensive data capture.
+
+### Dynamic Dimension Names
+Creating dimension names dynamically based on runtime values prevents effective querying and analysis. Use consistent dimension names with variable values rather than variable dimension names.
+
+### Sensitive Data Inclusion
+Including customer data, financial information, or other sensitive content in custom dimensions violates data protection principles and may create compliance issues.
+
+## Analysis and Querying
+
+### Dashboard Design
+Structure custom dimensions to support effective dashboard creation and alerting rules. Consider how dimensions will be used in aggregation queries and filtering operations.
+
+### Correlation Patterns
+Design custom dimensions to enable effective event correlation across different system components. Include consistent correlation identifiers that link related business processes.
+
+### Time-Series Analysis
+Include dimensions that support time-series analysis of business processes and system performance. Consider dimensions for business cycles, operational periods, and performance trends.

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

@@ -0,0 +1,84 @@
+---
+title: "Custom Telemetry Implementation in AL"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["telemetry", "session-logmessage", "privacy", "diagnostics", "monitoring"]
+samples: "samples/custom-telemetry.md"
+type: "implementation-pattern"
+category: "diagnostics"
+pattern_type: "good"
+severity: "medium"
+impact_level: "high"
+improvement_suggestion: "Implement custom telemetry for actionable monitoring and diagnostics"
+implementation_steps: ["design-telemetry-schema", "implement-session-logmessage", "validate-privacy-compliance"]
+validation_criteria: ["privacy-compliant", "actionable-data", "performance-neutral"]
+technical_areas: ["al-code", "monitoring"]
+---
+
+# Custom Telemetry Implementation in AL
+
+## Overview
+
+Custom telemetry in AL enables developers to emit structured diagnostic data through Session.LogMessage() for Application Insights integration. This observability foundation supports proactive monitoring, performance analysis, and troubleshooting while maintaining strict privacy compliance.
+
+**Critical Principle**: Treat telemetry as an API - documented, versioned, discoverable, and non-breaking for downstream analytics consumers.
+
+## Strategic Framework
+
+### Telemetry Design Philosophy
+- **Actionable Data Only**: Emit signals customers can act upon, avoiding noise from non-actionable metrics
+- **Privacy by Design**: Never log PII, customer data, or sensitive business information
+- **Cost Consciousness**: Balance diagnostic value with data ingestion costs through intelligent sampling
+- **Schema Consistency**: Use standardized naming conventions and structured dimensions
+
+### When to Implement Custom Telemetry
+- **Error Deflection**: Authentication failures, permission issues, configuration problems
+- **Performance Monitoring**: Long-running operations, resource bottlenecks, timeout scenarios
+- **Feature Adoption**: Usage patterns, workflow completion rates, feature discovery
+- **Integration Health**: External service calls, API responses, data synchronization status
+
+## Architecture Focus
+
+### Session.LogMessage() Implementation Pattern
+Structure telemetry calls with consistent event IDs, descriptive messages following "Object ActionInPastTense" pattern, and appropriate verbosity levels. Use custom dimensions dictionary for structured data while maintaining PascalCasing conventions.
+
+### Privacy-Compliant Data Classification
+Always use DataClassification::SystemMetadata for telemetry events. Review all LogMessage calls for potential privacy violations before production deployment. Focus on operational metadata rather than business data.
+
+### Telemetry Scope Strategy
+Default to TelemetryScope::ExtensionPublisher to control costs. Use TelemetryScope::All only when customers can directly act on the telemetry data for their business operations.
+
+## Best Practices
+
+### Implementation Guidelines
+- **Object-Level Emission**: Call Session.LogMessage() from within objects causing situations requiring telemetry
+- **Structured Dimensions**: Use Dictionary of [Text,Text] for custom dimensions with meaningful prefixes
+- **Message Consistency**: Always include human-readable "message" field expressing event purpose
+- **Correlation Support**: Include identifiers enabling distributed tracing across system boundaries
+
+### Performance Considerations
+- **Non-Blocking**: Ensure telemetry calls never impact user experience or application performance
+- **Minimal Processing**: Avoid complex calculations within telemetry emission paths
+- **Sampling Strategy**: Implement intelligent sampling for high-frequency events
+
+### Analytics Integration
+Design telemetry for Application Insights consumption with KQL-friendly field names, consistent schemas across related events, and dimensions supporting common analytical queries.
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Privacy Violations**: Logging customer data, PII, or sensitive business information
+- **Telemetry Flooding**: Excessive volume without considering customer ingestion costs
+- **Functional Dependencies**: Using telemetry data for application logic rather than pure observability
+- **Inconsistent Schemas**: Different naming patterns across related telemetry events
+
+### Common Implementation Mistakes
+- Missing privacy review before production deployment
+- Using special characters or spaces in custom dimension keys
+- Emitting telemetry from central objects rather than originating sources
+- Failing to provide actionable information for intended telemetry consumers
+
+*Implementation examples: see samples/custom-telemetry.md*
+*Privacy guidelines: see privacy-compliance-patterns.md*
+*Related patterns: monitoring-strategy.md, error-handling-patterns.md*