@salesforce/mcp-provider-lwc-experts 0.6.3 → 0.6.4

package/knowledge/o11y/activityApi.md

@@ -0,0 +1,64 @@
+## o11y Activity API Usage Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper usage of the o11y activity APIs (`startActivity()` and `activity.stop()`) for measuring operation duration. I focus on verifying correct API usage, error handling, and appropriate use cases.
+
+### What I Look For
+
+- **Missing activity tracking for async operations**: Async operations (API calls, data fetching, complex workflows) should use activities
+- **Incorrect activity.start() usage**: `startActivity()` should be called on the instrumentation instance
+- **Missing activity.stop() calls**: Every `startActivity()` must have a corresponding `activity.stop()` call
+- **Activity not stopped in finally block**: Activities should be stopped in a `finally` block to ensure they're always stopped, even on errors
+- **Missing error handling in activities**: When errors occur during activities, use `activity.error()` before stopping
+- **Missing schema in activity.stop()**: When stopping an activity, provide a schema and payload for structured data
+- **Activities not used for duration measurements**: Operations that need duration tracking should use activities (creates percentile metrics)
+
+### What I Ignore
+
+- Synchronous operations that complete immediately
+- Simple operations that don't need duration tracking
+- Components that already properly use activity APIs
+- Test files and mock implementations
+
+### Analysis Framework
+
+**Activity API Pattern**
+
+```javascript
+const activity = instrumentation.startActivity('operationName');
+try {
+  await someAsyncOperation();
+} catch (err) {
+  activity.error(err, errorSchema, errorPayload);
+} finally {
+  activity.stop(activitySchema, payload);
+}
+```
+
+**Use Cases for Activities**
+
+- Async operations (API calls, data fetching)
+- Complex workflows with multiple steps
+- Operations that need duration/performance tracking
+- Operations that should generate percentile metrics
+
+**Activity Lifecycle**
+
+- `startActivity(name)`: Starts an activity, returns Activity object
+- `activity.error(err, schema, data)`: Logs error during activity
+- `activity.stop(schema, data)`: Stops activity and logs completion
+
+**Error Handling**
+
+- Always wrap activity operations in try/catch
+- Use `activity.error()` when errors occur
+- Always stop activity in `finally` block
+
+**Schema Usage**
+
+- `activity.stop()` should receive a schema and payload
+- Schema provides structure for the activity completion data
+- Payload should match schema field definitions
+
+**Important**: If activity APIs are used correctly for appropriate operations, I return an empty list.

package/knowledge/o11y/bestPractices.md

@@ -0,0 +1,106 @@
+# Observability (o11y) Instrumentation Best Practices for LWC
+
+This expert analyzes Lightning Web Components to ensure proper observability instrumentation using the o11y client, schemas, and APIs.
+
+## Core Principles
+
+1. **Use o11y Client, Not Lightning Logger**
+
+   - Always use `getInstrumentation` from 'o11y/client'
+   - Never use `createLogger` from 'lightning/logger'
+   - Initialize instrumentation once in the constructor
+
+2. **Schema-Based Instrumentation**
+
+   - Always import schemas from 'o11y_schema' directories
+   - Use schemas for structured logging with `log()` API
+   - Schemas provide type safety and automatic metric generation
+
+3. **Proper API Usage**
+
+   - `log()`: For significant events with structured data (creates counter metrics)
+   - `startActivity()` / `activity.stop()`: For measuring operation duration (creates percentile metrics)
+   - `error()`: For error tracking (use with activities when possible)
+   - `incrementCounter()`: For discrete events/actions
+   - `trackValue()`: For numeric measurements
+
+4. **Lifecycle Instrumentation**
+
+   - Instrument component lifecycle hooks (connectedCallback, renderedCallback)
+   - Track page loads, user interactions, and async operations
+   - Measure performance-critical operations
+
+5. **Error Handling**
+   - Always catch errors in async operations
+   - Use `activity.error()` when errors occur during activities
+   - Log errors with appropriate context
+
+## Automatically Collected Fields
+
+Do NOT duplicate these fields in schemas or instrumentation:
+
+- Activity: id, name, duration, stopReason, isRoot, preRootId, errorCount
+- Error: name, message, stack, activityId, logType
+- Request: requestId, rootRequestId, parentRequestId
+- Context: organizationId, userId, clientSessionId, schemaSequence
+- Application: appName, appVersion, deviceId, browserName, osName
+- Page: pageUrl, pageEntityType, pageContext, pageEntityId
+
+## Common Patterns
+
+### Initialization Pattern
+
+```javascript
+import { getInstrumentation } from 'o11y/client';
+
+constructor() {
+    super();
+    this.instrumentation = getInstrumentation('logger-name');
+}
+```
+
+### Logging Pattern
+
+```javascript
+import { eventSchema } from 'o11y_schema/sf/team-folder/schema-name';
+
+instrumentation.log(eventSchema, {
+  taskName: 'userAction',
+  // ... other schema fields
+});
+```
+
+### Activity Pattern
+
+```javascript
+const activity = instrumentation.startActivity('operationName');
+try {
+  await someAsyncOperation();
+} catch (err) {
+  activity.error(err, errorSchema, errorPayload);
+} finally {
+  activity.stop(activitySchema, payload);
+}
+```
+
+### Counter Pattern
+
+```javascript
+instrumentation.incrementCounter('BUTTON_CLICKED', 1, false, { buttonId: 'submit-button' });
+```
+
+## What to Instrument
+
+- User interactions (clicks, form submissions)
+- Page/component loads
+- Async operations (API calls, data fetching)
+- Error conditions
+- Performance-critical operations
+- Feature usage and toggles
+
+## What NOT to Instrument
+
+- Don't over-instrument (avoid logging every single event)
+- Don't use lightning/logger
+- Don't duplicate automatically collected fields
+- Don't instrument trivial operations

package/knowledge/o11y/counterMetrics.md

@@ -0,0 +1,61 @@
+## o11y Counter Metrics Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper usage of the o11y \`incrementCounter()\` API for tracking discrete events or actions. I focus on verifying correct API usage and appropriate use cases.
+
+### What I Look For
+
+- **Missing counter tracking for user actions**: Button clicks, form submissions, and other discrete user actions should use \`incrementCounter()\`
+- **Incorrect incrementCounter() usage**: API should be called with operation name, increment value, error flag, and optional tags
+- **Missing counter for high-frequency events**: Events that occur frequently should use counters instead of \`log()\`
+- **Incorrect counter names**: Counter names should be descriptive, UPPER_SNAKE_CASE, and clearly identify the event
+- **Missing tags for filtering**: Counters should include relevant tags for filtering and analysis
+- **Using log() instead of incrementCounter()**: High-frequency discrete events should use counters, not \`log()\`
+
+### What I Ignore
+
+- Components that don't have discrete events to track
+- Components that already properly use \`incrementCounter()\`
+- Test files and mock implementations
+- Events that are better tracked with \`log()\` (significant events with context)
+
+### Analysis Framework
+
+**Counter API Signature**
+\`\`\`javascript
+incrementCounter(
+operation: string, // Counter name (UPPER_SNAKE_CASE)
+increment?: number, // Increment value (default: 1)
+hasError?: boolean, // Error flag (default: false)
+tags?: MetricsTags // Optional tags for filtering
+): void
+\`\`\`
+
+**Use Cases for incrementCounter()**
+
+- Button clicks
+- Form submissions
+- Navigation events
+- Feature usage
+- High-frequency discrete events
+- Events that need simple counting
+
+**Counter Naming**
+
+- Use UPPER_SNAKE_CASE: \`BUTTON_CLICKED\`, \`FORM_SUBMITTED\`
+- Be descriptive: \`SUBMIT_BUTTON_CLICKED\` not \`CLICK\`
+- Include context: \`THUMBS_UP_BUTTON_CLICKED\` not \`BUTTON\`
+
+**Tags Usage**
+
+- Include relevant tags for filtering: \`{ buttonId: 'submit-button', featureId: 'feature-123' }\`
+- Only use bounded values for tags (low cardinality)
+- Tags help with analysis and filtering
+
+**When to Use incrementCounter() vs log()**
+
+- \`incrementCounter()\`: Simple counting of discrete events, high-frequency events
+- \`log()\`: Significant events with structured context data, events that need detailed information
+
+**Important**: If counter metrics are used correctly for appropriate events, I return an empty list.

package/knowledge/o11y/errorTracking.md

@@ -0,0 +1,70 @@
+## o11y Error Tracking Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper error tracking using the o11y \`error()\` API. I focus on verifying that errors are caught, logged with appropriate context, and integrated with activities when applicable.
+
+### What I Look For
+
+- **Unhandled errors in async operations**: Async operations (API calls, promises) should have try/catch blocks with error logging
+- **Missing error() calls**: Errors should be logged using \`instrumentation.error()\` or \`activity.error()\`
+- **Errors not logged with activities**: When errors occur during activities, use \`activity.error()\` instead of standalone \`error()\`
+- **Missing error context**: Errors should be logged with schemas and context data when available
+- **Errors swallowed without logging**: Catch blocks that don't log errors or re-throw them appropriately
+- **Missing error tracking in wire service**: Wire service error handlers should log errors
+
+### What I Ignore
+
+- Expected errors that are handled gracefully without logging
+- Test files and mock implementations
+- Components that already properly track errors
+- Errors that are re-thrown for upstream handling (if appropriate)
+
+### Analysis Framework
+
+**Error API Patterns**
+
+**Standalone Error Logging**
+\`\`\`javascript
+try {
+await someOperation();
+} catch (err) {
+instrumentation.error(err, errorSchema, errorPayload);
+}
+\`\`\`
+
+**Error with Activity**
+\`\`\`javascript
+const activity = instrumentation.startActivity('operation');
+try {
+await someOperation();
+} catch (err) {
+activity.error(err, errorSchema, errorPayload);
+} finally {
+activity.stop(activitySchema, payload);
+}
+\`\`\`
+
+**Error API Signature**
+
+- \`error(error: unknown, userSchemaOrText?: Schema | string, userData?: SchematizedData, options?: ApiOptions)\`
+- First argument: the error object
+- Second argument: schema (preferred) or error text string
+- Third argument: error data matching schema fields
+
+**Use Cases for Error Tracking**
+
+- API call failures
+- Data validation errors
+- Async operation failures
+- Wire service errors
+- User action errors
+
+**Best Practices**
+
+- Use \`activity.error()\` when errors occur during activities
+- Provide error schemas for structured error data
+- Include context data (operation name, user action, etc.)
+- Don't swallow errors without logging
+
+**Important**: If errors are properly tracked with appropriate context, I return an empty list.

package/knowledge/o11y/initialization.md

@@ -0,0 +1,46 @@
+## o11y Initialization Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper initialization of the o11y instrumentation client. I focus on verifying that \`getInstrumentation\` is imported correctly, called exactly once in the constructor, and that the instrumentation instance is properly stored.
+
+### What I Look For
+
+- **Missing getInstrumentation import**: Code that should use o11y but doesn't import \`getInstrumentation\` from 'o11y/client'
+- **Multiple getInstrumentation calls**: \`getInstrumentation\` should be called ONCE AND ONLY ONCE, typically in the constructor
+- **Incorrect initialization location**: \`getInstrumentation\` should be called in the constructor, not in lifecycle hooks or methods
+- **Missing instrumentation property**: The result of \`getInstrumentation\` should be stored in a class property (e.g., \`this.instrumentation\`)
+- **Using lightning/logger instead**: Code that imports or uses \`createLogger\` from 'lightning/logger' instead of o11y
+- **Instrumentation not stored**: Result of \`getInstrumentation\` is not assigned to a property for later use
+
+### What I Ignore
+
+- Components that don't need instrumentation (very simple, static components)
+- Standard Lightning base components (they handle their own instrumentation)
+- Test files and mock implementations
+- Components that already have proper o11y initialization
+
+### Analysis Framework
+
+**Import Check**
+
+- Verify \`getInstrumentation\` is imported from 'o11y/client'
+- Check that the import statement is correct and not using 'lightning/logger'
+
+**Initialization Check**
+
+- \`getInstrumentation\` must be called exactly once
+- Should be called in the constructor, not in connectedCallback, renderedCallback, or other methods
+- The call should pass a logger name string as the argument
+
+**Storage Check**
+
+- Result should be stored in a class property (typically \`this.instrumentation\`)
+- Property should be accessible throughout the component lifecycle
+
+**Lightning Logger Detection**
+
+- Flag any imports from 'lightning/logger'
+- Flag any usage of \`createLogger\` function
+
+**Important**: If the component has proper o11y initialization (single call in constructor, stored in property), I return an empty list.

package/knowledge/o11y/lifecycleInstrumentation.md

@@ -0,0 +1,91 @@
+## o11y Lifecycle Instrumentation Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper instrumentation of component lifecycle hooks. I focus on verifying that lifecycle events (connectedCallback, renderedCallback, disconnectedCallback) are appropriately instrumented.
+
+### What I Look For
+
+- **Missing page load instrumentation**: \`renderedCallback\` should log page/component load events when appropriate
+- **Missing lifecycle tracking**: Components with significant initialization or cleanup should instrument lifecycle hooks
+- **Incorrect lifecycle instrumentation**: Lifecycle hooks should use appropriate o11y APIs (\`log()\` for events, activities for async operations)
+- **Missing connectedCallback instrumentation**: Components that perform initialization should track connection events
+- **Missing disconnectedCallback instrumentation**: Components with cleanup logic should track disconnection events
+- **Lifecycle hooks without instrumentation**: Components with complex lifecycle behavior should be instrumented
+
+### What I Ignore
+
+- Simple components that don't need lifecycle instrumentation
+- Components that already properly instrument lifecycle hooks
+- Test files and mock implementations
+- Static components with no lifecycle behavior
+
+### Analysis Framework
+
+**Lifecycle Hooks to Instrument**
+
+**connectedCallback**
+
+- Called when component is inserted into DOM
+- Use \`log()\` to track component connection
+- Use activities for async initialization operations
+
+**renderedCallback**
+
+- Called after component renders
+- Use \`log()\` to track page/component load events
+- Should only log once (use flags to prevent duplicate logging)
+
+**disconnectedCallback**
+
+- Called when component is removed from DOM
+- Use \`log()\` to track component disconnection
+- Use for cleanup tracking
+
+**Instrumentation Patterns**
+
+**Page Load Pattern**
+\`\`\`javascript
+renderedCallback() {
+if (!this.hasLoaded) {
+this.instrumentation.log(pageLoadSchema, {
+taskName: 'pageLoad',
+loadTime: performance.now()
+});
+this.hasLoaded = true;
+}
+}
+\`\`\`
+
+**Component Connection Pattern**
+\`\`\`javascript
+connectedCallback() {
+this.instrumentation.log(componentConnectSchema, {
+taskName: 'componentConnected',
+componentName: this.constructor.name
+});
+}
+\`\`\`
+
+**Async Initialization Pattern**
+\`\`\`javascript
+async connectedCallback() {
+const activity = this.instrumentation.startActivity('componentInitialization');
+try {
+await this.initializeData();
+} catch (err) {
+activity.error(err, errorSchema, errorPayload);
+} finally {
+activity.stop(activitySchema, payload);
+}
+}
+\`\`\`
+
+**Best Practices**
+
+- Use flags to prevent duplicate logging in \`renderedCallback\`
+- Use activities for async lifecycle operations
+- Include component context in lifecycle logs
+- Track performance metrics for initialization
+
+**Important**: If lifecycle hooks are properly instrumented, I return an empty list.

package/knowledge/o11y/logApi.md

@@ -0,0 +1,53 @@
+## o11y Log API Usage Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper usage of the o11y \`log()\` API for tracking significant events with structured data. I focus on verifying correct API usage, schema integration, and appropriate use cases.
+
+### What I Look For
+
+- **Missing log() calls for significant events**: User actions, page loads, feature toggles, or other important events that should be logged
+- **Incorrect log() API usage**: \`log()\` called without a schema, or with incorrect arguments
+- **Missing schema in log() calls**: \`log()\` should always receive a schema as the first argument
+- **Incorrect data structure**: Data object passed to \`log()\` doesn't match the schema structure
+- **Using log() for metrics**: \`log()\` is for events, not for counter metrics (use \`incrementCounter\` instead)
+- **Missing log() for page loads**: \`renderedCallback\` should log page/component load events when appropriate
+- **Missing log() for user interactions**: Significant user actions (form submissions, navigation, feature toggles) should be logged
+
+### What I Ignore
+
+- Simple components that don't have significant events to log
+- Components that already properly use \`log()\` API
+- Test files and mock implementations
+- Trivial operations that don't warrant logging
+
+### Analysis Framework
+
+**Log API Signature**
+
+- Correct: \`instrumentation.log(userSchema, userData, options)\`
+- Schema must be the first argument
+- Data object (optional) should match schema fields
+- Options (optional) for additional configuration
+
+**Use Cases for log()**
+
+- Page/component load events
+- User interactions (clicks, form submissions, navigation)
+- Feature toggles and configuration changes
+- Significant state changes
+- Business events that need tracking
+
+**When NOT to use log()**
+
+- For simple counter metrics (use \`incrementCounter\` instead)
+- For duration measurements (use \`startActivity\` / \`activity.stop\` instead)
+- For numeric value tracking (use \`trackValue\` instead)
+
+**Schema Integration**
+
+- Every \`log()\` call must include a schema
+- Data object must match schema field definitions
+- Use descriptive event names in the data
+
+**Important**: If \`log()\` API is used correctly for appropriate events, I return an empty list,

package/knowledge/o11y/schemaUsage.md

@@ -0,0 +1,48 @@
+## o11y Schema Usage Analysis
+
+### My Job
+
+I analyze Lightning Web Component code to ensure proper usage of o11y schemas. I focus on verifying that schemas are imported from the correct location, used with the appropriate APIs, and that schema fields match the data being logged.
+
+### What I Look For
+
+- **Missing schema imports**: Code using \`log()\` or \`activity.stop()\` without importing the required schema
+- **Incorrect schema import path**: Schemas should be imported from 'o11y_schema/sf/<team-folder>/<schema-name>', not from other locations
+- **Schema not used with log()**: When using \`log()\` API, a schema must be provided as the first argument
+- **Schema not used with activity.stop()**: When using \`activity.stop()\`, a schema should be provided for structured data
+- **Schema field mismatch**: Data object passed to \`log()\` or \`activity.stop()\` doesn't match the schema field definitions
+- **Missing schema for structured logging**: Using \`log()\` without a schema (schemas are required for structured logging)
+
+### What I Ignore
+
+- Counter and value tracking APIs (\`incrementCounter\`, \`trackValue\`) which don't require schemas
+- Error logging with just error text (not structured error schemas)
+- Components that don't use structured logging
+- Test files and mock implementations
+
+### Analysis Framework
+
+**Schema Import Check**
+
+- Verify schemas are imported from 'o11y_schema' directories
+- Check import path follows pattern: 'o11y_schema/sf/<team-folder>/<schema-name>'
+- Ensure schema names match their usage
+
+**Schema Usage with log()**
+
+- \`log()\` API signature: \`log(userSchema: Schema, userData?: SchematizedData, options?: ApiOptions)\`
+- First argument must be a schema
+- Data object (second argument) should match schema fields
+
+**Schema Usage with activity.stop()**
+
+- \`activity.stop()\` can accept a schema and data: \`activity.stop(activitySchema, payload)\`
+- When used, schema should match the payload structure
+
+**Field Validation**
+
+- Data objects should only contain fields defined in the schema
+- Field names should match schema field names exactly
+- Field types should match schema field types
+
+**Important**: If schemas are properly imported and used, I return an empty list.