You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
358 lines
8.4 KiB
358 lines
8.4 KiB
---
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Logging Migration — Patterns and Examples
|
|
|
|
> **Agent role**: Reference this file for specific migration patterns and
|
|
examples when converting console.* calls to logger usage.
|
|
|
|
## Migration — Auto‑Rewrites (Apply Every Time)
|
|
|
|
### Exact Transforms
|
|
|
|
- `console.debug(...)` → `logger.debug(...)`
|
|
|
|
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
|
|
|
|
clearly stateful)
|
|
|
|
- `console.info(...)` → `logger.info(...)`
|
|
|
|
- `console.warn(...)` → `logger.warn(...)`
|
|
|
|
- `console.error(...)` → `logger.error(...)`
|
|
|
|
### Multi-arg Handling
|
|
|
|
- First arg becomes `message` (stringify safely if non-string).
|
|
|
|
- Remaining args map 1:1 to `...args`:
|
|
|
|
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
|
|
|
|
### Sole `Error`
|
|
|
|
- `console.error(err)` → `logger.error(err.message, err)`
|
|
|
|
### Object-wrapping Cleanup
|
|
|
|
Replace `{{ userId, meta }}` wrappers with separate args:
|
|
`logger.info('User signed in', userId, meta)`
|
|
|
|
## Level Guidelines with Examples
|
|
|
|
### DEBUG Examples
|
|
|
|
```typescript
|
|
|
|
logger.debug('[HomeView] reloadFeedOnChange() called');
|
|
logger.debug('[HomeView] Current filter settings',
|
|
settings.filterFeedByVisible,
|
|
settings.filterFeedByNearby,
|
|
settings.searchBoxes?.length ?? 0);
|
|
logger.debug('[FeedFilters] Toggling nearby filter',
|
|
this.isNearby, this.settingChanged, this.activeDid);
|
|
|
|
```
|
|
|
|
**Avoid**: Vague messages (`'Processing data'`).
|
|
|
|
### INFO Examples
|
|
|
|
```typescript
|
|
|
|
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
|
|
logger.info('[StartView] User selected new seed generation');
|
|
logger.info('[SearchAreaView] Search box stored',
|
|
searchBox.name, searchBox.bbox);
|
|
logger.info('[ContactQRScanShowView] Contact registration OK',
|
|
contact.did);
|
|
|
|
```
|
|
|
|
**Avoid**: Diagnostic details that belong in `debug`.
|
|
|
|
### WARN Examples
|
|
|
|
```typescript
|
|
|
|
logger.warn('[ContactQRScanShowView] Invalid scan result – no value',
|
|
resultType);
|
|
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
|
|
logger.warn('[ContactQRScanShowView] JWT missing "own" field');
|
|
|
|
```
|
|
|
|
**Avoid**: Hard failures (those are `error`).
|
|
|
|
### ERROR Examples
|
|
|
|
```typescript
|
|
|
|
logger.error('[HomeView Settings] initializeIdentity() failed', err);
|
|
logger.error('[StartView] Failed to load initialization data', error);
|
|
logger.error('[ContactQRScanShowView] Error processing contact QR',
|
|
error, rawValue);
|
|
|
|
```
|
|
|
|
**Avoid**: Expected user cancels (use `info`/`debug`).
|
|
|
|
## Context Hygiene Examples
|
|
|
|
### Component Context
|
|
|
|
```typescript
|
|
|
|
const log = logger.withContext('UserService');
|
|
log.info('User created', userId);
|
|
log.error('Failed to create user', error);
|
|
|
|
```
|
|
|
|
If not using `withContext`, prefix message with `[ComponentName]`.
|
|
|
|
### Emoji Guidelines
|
|
|
|
Recommended set for visual scanning:
|
|
|
|
- Start/finish: 🚀 / ✅
|
|
|
|
- Retry/loop: 🔄
|
|
|
|
- External call: 📡
|
|
|
|
- Data/metrics: 📊
|
|
|
|
- Inspection: 🔍
|
|
|
|
## Quick Before/After
|
|
|
|
### **Before**
|
|
|
|
```typescript
|
|
|
|
console.log('User signed in', user.id, meta);
|
|
console.error('Failed to update profile', err);
|
|
console.info('Filter toggled', this.hasVisibleDid);
|
|
|
|
```
|
|
|
|
### **After**
|
|
|
|
```typescript
|
|
|
|
import { logger } from '@/utils/logger';
|
|
|
|
logger.info('User signed in', user.id, meta);
|
|
logger.error('Failed to update profile', err);
|
|
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
|
|
|
|
```
|
|
|
|
## Checklist (for every PR)
|
|
|
|
- [ ] No `console.*` (or properly pragma'd in the allowed locations)
|
|
|
|
- [ ] Correct import path for `logger`
|
|
|
|
- [ ] Rest-parameter call shape (`message, ...args`)
|
|
|
|
- [ ] Right level chosen (debug/info/warn/error)
|
|
|
|
- [ ] No secrets / oversized payloads / throwaway context objects
|
|
|
|
- [ ] Component context provided (scoped logger or `[Component]` prefix)
|
|
|
|
**See also**:
|
|
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules.
|
|
|
|
# Logging Migration — Patterns and Examples
|
|
|
|
> **Agent role**: Reference this file for specific migration patterns and
|
|
examples when converting console.* calls to logger usage.
|
|
|
|
## Migration — Auto‑Rewrites (Apply Every Time)
|
|
|
|
### Exact Transforms
|
|
|
|
- `console.debug(...)` → `logger.debug(...)`
|
|
|
|
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
|
|
|
|
clearly stateful)
|
|
|
|
- `console.info(...)` → `logger.info(...)`
|
|
|
|
- `console.warn(...)` → `logger.warn(...)`
|
|
|
|
- `console.error(...)` → `logger.error(...)`
|
|
|
|
### Multi-arg Handling
|
|
|
|
- First arg becomes `message` (stringify safely if non-string).
|
|
|
|
- Remaining args map 1:1 to `...args`:
|
|
|
|
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
|
|
|
|
### Sole `Error`
|
|
|
|
- `console.error(err)` → `logger.error(err.message, err)`
|
|
|
|
### Object-wrapping Cleanup
|
|
|
|
Replace `{{ userId, meta }}` wrappers with separate args:
|
|
`logger.info('User signed in', userId, meta)`
|
|
|
|
## Level Guidelines with Examples
|
|
|
|
### DEBUG Examples
|
|
|
|
```typescript
|
|
|
|
logger.debug('[HomeView] reloadFeedOnChange() called');
|
|
logger.debug('[HomeView] Current filter settings',
|
|
settings.filterFeedByVisible,
|
|
settings.filterFeedByNearby,
|
|
settings.searchBoxes?.length ?? 0);
|
|
logger.debug('[FeedFilters] Toggling nearby filter',
|
|
this.isNearby, this.settingChanged, this.activeDid);
|
|
|
|
```
|
|
|
|
**Avoid**: Vague messages (`'Processing data'`).
|
|
|
|
### INFO Examples
|
|
|
|
```typescript
|
|
|
|
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
|
|
logger.info('[StartView] User selected new seed generation');
|
|
logger.info('[SearchAreaView] Search box stored',
|
|
searchBox.name, searchBox.bbox);
|
|
logger.info('[ContactQRScanShowView] Contact registration OK',
|
|
contact.did);
|
|
|
|
```
|
|
|
|
**Avoid**: Diagnostic details that belong in `debug`.
|
|
|
|
### WARN Examples
|
|
|
|
```typescript
|
|
|
|
logger.warn('[ContactQRScanShowView] Invalid scan result – no value',
|
|
resultType);
|
|
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
|
|
logger.warn('[ContactQRScanShowView] JWT missing "own" field');
|
|
|
|
```
|
|
|
|
**Avoid**: Hard failures (those are `error`).
|
|
|
|
### ERROR Examples
|
|
|
|
```typescript
|
|
|
|
logger.error('[HomeView Settings] initializeIdentity() failed', err);
|
|
logger.error('[StartView] Failed to load initialization data', error);
|
|
logger.error('[ContactQRScanShowView] Error processing contact QR',
|
|
error, rawValue);
|
|
|
|
```
|
|
|
|
**Avoid**: Expected user cancels (use `info`/`debug`).
|
|
|
|
## Context Hygiene Examples
|
|
|
|
### Component Context
|
|
|
|
```typescript
|
|
|
|
const log = logger.withContext('UserService');
|
|
log.info('User created', userId);
|
|
log.error('Failed to create user', error);
|
|
|
|
```
|
|
|
|
If not using `withContext`, prefix message with `[ComponentName]`.
|
|
|
|
### Emoji Guidelines
|
|
|
|
Recommended set for visual scanning:
|
|
|
|
- Start/finish: 🚀 / ✅
|
|
|
|
- Retry/loop: 🔄
|
|
|
|
- External call: 📡
|
|
|
|
- Data/metrics: 📊
|
|
|
|
- Inspection: 🔍
|
|
|
|
## Quick Before/After
|
|
|
|
### **Before**
|
|
|
|
```typescript
|
|
|
|
console.log('User signed in', user.id, meta);
|
|
console.error('Failed to update profile', err);
|
|
console.info('Filter toggled', this.hasVisibleDid);
|
|
|
|
```
|
|
|
|
### **After**
|
|
|
|
```typescript
|
|
|
|
import { logger } from '@/utils/logger';
|
|
|
|
logger.info('User signed in', user.id, meta);
|
|
logger.error('Failed to update profile', err);
|
|
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
|
|
|
|
```
|
|
|
|
## Checklist (for every PR)
|
|
|
|
- [ ] No `console.*` (or properly pragma'd in the allowed locations)
|
|
|
|
- [ ] Correct import path for `logger`
|
|
|
|
- [ ] Rest-parameter call shape (`message, ...args`)
|
|
|
|
- [ ] Right level chosen (debug/info/warn/error)
|
|
|
|
- [ ] No secrets / oversized payloads / throwaway context objects
|
|
|
|
- [ ] Component context provided (scoped logger or `[Component]` prefix)
|
|
|
|
**See also**:
|
|
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules.
|
|
|
|
## Model Implementation Checklist
|
|
|
|
### Before Logging Migration
|
|
|
|
- [ ] **Code Review**: Identify all `console.*` calls in the codebase
|
|
- [ ] **Logger Import**: Verify logger utility is available and accessible
|
|
- [ ] **Context Planning**: Plan component context for each logging call
|
|
- [ ] **Level Assessment**: Determine appropriate log levels for each call
|
|
|
|
### During Logging Migration
|
|
|
|
- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls
|
|
- [ ] **Context Addition**: Add component context using scoped logger or prefix
|
|
- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error)
|
|
- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`)
|
|
|
|
### After Logging Migration
|
|
|
|
- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd)
|
|
- [ ] **Context Validation**: Verify all logging calls have proper context
|
|
- [ ] **Level Review**: Confirm log levels are appropriate for each situation
|
|
- [ ] **Testing**: Test logging functionality across all platforms
|
|
|