@venizia/ignis-docs 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",
@@ -114,7 +114,7 @@
     "@braintree/sanitize-url": "^7.1.1",
     "@types/bun": "^1.3.4",
     "@types/glob": "^8.1.0",
-    "@venizia/dev-configs": "^0.0.5",
+    "@venizia/dev-configs": "^0.0.6",
     "eslint": "^9.36.0",
     "glob": "^10.4.2",
     "prettier": "^3.6.2",

package/wiki/best-practices/code-style-standards/function-patterns.md

@@ -109,14 +109,17 @@ export class UserController extends BaseController {
 
 ## Performance Logging Pattern
 
-Use `performance.now()` for timing critical operations:
+Use `performance.now()` for timing critical operations with method-scoped logging:
 
 ```typescript
-const t = performance.now();
+async syncData() {
+  const t = performance.now();
+  this.logger.for('syncData').info('START | Syncing data...');
 
-// ... operation to measure ...
+  // ... operation to measure ...
 
-this.logger.info('[methodName] DONE | Took: %s (ms)', performance.now() - t);
+  this.logger.for('syncData').info('DONE | Took: %s (ms)', performance.now() - t);
+}
 ```
 
 **With the helper utility:**
@@ -125,7 +128,7 @@ this.logger.info('[methodName] DONE | Took: %s (ms)', performance.now() - t);
 import { executeWithPerformanceMeasure } from '@venizia/ignis';
 
 await executeWithPerformanceMeasure({
-  logger: this.logger,
+  logger: this.logger.for('syncData'),
   scope: 'DataSync',
   description: 'Sync user records',
   task: async () => {
@@ -135,6 +138,29 @@ await executeWithPerformanceMeasure({
 // Logs: [DataSync] Sync user records | Took: 1234.56 (ms)
 ```
 
+**Method-scoped logging pattern:**
+
+```typescript
+class UserService {
+  private logger = Logger.get('UserService');
+
+  async createUser(data: CreateUserDto) {
+    // Use .for() to add method context to all logs
+    this.logger.for('createUser').info('Creating user: %j', data);
+    // Output: [UserService-createUser] Creating user: {...}
+
+    try {
+      const user = await this.userRepo.create({ data });
+      this.logger.for('createUser').info('User created: %s', user.id);
+      return user;
+    } catch (error) {
+      this.logger.for('createUser').error('Failed: %s', error);
+      throw error;
+    }
+  }
+}
+```
+
 ## See Also
 
 - [Naming Conventions](./naming-conventions) - Class and file naming

package/wiki/best-practices/performance-optimization.md

@@ -354,6 +354,44 @@ setInterval(() => {
 }, 3600000); // Every hour
 ```
 
+## 10. High-Frequency Logging
+
+For performance-critical applications like HFT systems, use `HfLogger` instead of standard logging.
+
+### Standard Logger vs HfLogger
+
+| Feature | Standard Logger | HfLogger |
+|---------|-----------------|----------|
+| Latency | ~1-10 microseconds | ~100-300 nanoseconds |
+| Allocation | Per-call string formatting | Zero in hot path |
+| Use case | General application | Trading, real-time systems |
+
+### HfLogger Usage
+
+```typescript
+import { HfLogger, HfLogFlusher } from '@venizia/ignis-helpers';
+
+// At initialization (once):
+const logger = HfLogger.get('OrderEngine');
+const MSG_ORDER_SENT = HfLogger.encodeMessage('Order sent');
+const MSG_ORDER_FILLED = HfLogger.encodeMessage('Order filled');
+
+// Start background flusher
+const flusher = new HfLogFlusher();
+flusher.start(100); // Flush every 100ms
+
+// In hot path (~100-300ns, zero allocation):
+logger.log('info', MSG_ORDER_SENT);
+logger.log('info', MSG_ORDER_FILLED);
+```
+
+**Key points:**
+- Pre-encode messages at initialization, not in hot path
+- Use background flushing to avoid I/O blocking
+- HfLogger uses a lock-free ring buffer (64K entries, 16MB)
+
+> **Deep Dive:** See [Logger Helper](../references/helpers/logger.md) for complete HfLogger API.
+
 ## Performance Checklist
 
 | Category | Check | Impact |
@@ -367,6 +405,7 @@ setInterval(() => {
 | **Memory** | Large datasets processed in batches | High |
 | **Caching** | Expensive queries cached | High |
 | **Workers** | CPU-intensive tasks offloaded | High |
+| **Logging** | HfLogger for hot paths (HFT) | High |
 | **Monitoring** | Performance logging enabled | Low |
 
 ## See Also

package/wiki/best-practices/troubleshooting-tips.md

@@ -75,9 +75,30 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \
 ## 5. General Debugging Tips
 
 **Enable detailed logging:**
+```bash
+# Enable debug mode via environment variable
+DEBUG=true
+```
+
+**Use method-scoped logging with `.for()`:**
 ```typescript
-// Increase log verbosity
-LoggerFactory.setLevel('debug');
+class UserService {
+  private logger = Logger.get('UserService');
+
+  async createUser(data: CreateUserDto) {
+    this.logger.for('createUser').info('Creating user: %j', data);
+    // Output: [UserService-createUser] Creating user: {...}
+
+    try {
+      const user = await this.userRepo.create({ data });
+      this.logger.for('createUser').info('User created: %s', user.id);
+      return user;
+    } catch (error) {
+      this.logger.for('createUser').error('Failed: %s', error);
+      throw error;
+    }
+  }
+}
 ```
 
 **Common debugging commands:**
@@ -93,7 +114,7 @@ cat .env | grep APP_ENV
 ```
 
 **Useful debugging patterns:**
-- Add `console.log()` in route handlers to trace execution
+- Use `logger.for('methodName')` to trace execution with method context
 - Use `try-catch` blocks to catch and log errors
 - Check database queries with Drizzle's logging: `{ logger: true }`