Skip to content

Commit eea6efb

Browse files
committed
Revert logging best practices section
1 parent 17605ff commit eea6efb

File tree

1 file changed

+0
-113
lines changed

1 file changed

+0
-113
lines changed

cli/knowledge.md

Lines changed: 0 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -671,116 +671,3 @@ When implementing automatic retry on reconnection, scheduling retries in both SD
671671
- Network failures with pending operations
672672
- Error cascades
673673
- Rapid state transitions
674-
675-
## Logging Strategy and Best Practices
676-
677-
The CLI uses Pino for structured logging with multiple severity levels. Proper log level selection is critical for debugging without creating noise in production.
678-
679-
### Log Levels
680-
681-
1. **debug** - Detailed diagnostic information for troubleshooting
682-
- Connection state changes (initial connection, reconnection, disconnection)
683-
- Retry scheduling and execution
684-
- State transitions and effect triggers
685-
- Internal operation details
686-
- **Use when**: Information is only needed for debugging specific issues
687-
688-
2. **info** - General informational messages about normal operations
689-
- User-initiated actions completing successfully
690-
- Significant application state changes visible to users
691-
- Major workflow milestones
692-
- **Use when**: Information is useful for understanding normal application flow
693-
694-
3. **warn** - Potentially harmful situations that don't prevent operation
695-
- Deprecated API usage
696-
- Approaching retry limits
697-
- Degraded functionality
698-
- Recoverable errors
699-
- **Use when**: Something unexpected happened but the application can continue
700-
701-
4. **error** - Error events that might still allow the application to continue
702-
- Failed API calls
703-
- Failed message sends
704-
- Validation errors
705-
- **Use when**: An operation failed but the application remains functional
706-
707-
5. **fatal** - Severe errors that cause the application to abort
708-
- Unrecoverable crashes
709-
- Critical resource failures
710-
- **Use when**: The application must terminate
711-
712-
### Best Practices
713-
714-
1. **Avoid Verbose Logging in Hot Paths**
715-
- Connection/reconnection events should use `debug` level
716-
- Frequent state updates should use `debug` level
717-
- Only log user-facing actions at `info` level
718-
719-
2. **Structured Logging**
720-
- Always include context data as the first parameter
721-
- Use consistent field names across the codebase
722-
- Example: `logger.debug({ userId, messageId }, 'Processing message')`
723-
724-
3. **Log Message Format**
725-
- Use clear, concise descriptions
726-
- Include relevant identifiers in brackets: `[Connection]`, `[RETRY-EFFECT]`
727-
- Avoid overly verbose messages
728-
729-
4. **Production vs Development**
730-
- Debug logs are automatically filtered in production based on log level
731-
- In development, all logs go to `debug/cli.log`
732-
- In production, logs go to the chat directory as `log.jsonl`
733-
734-
5. **Analytics Integration**
735-
- Setting `data.eventId` to an `AnalyticsEvent` sends the log to PostHog
736-
- Only use for user-facing actions, not internal debugging
737-
738-
### Example Usage
739-
740-
```typescript
741-
// Debug level - internal state changes
742-
logger.debug(
743-
{ isInitialConnection, timestamp: Date.now() },
744-
'[Connection] Reconnection callback triggered'
745-
)
746-
747-
// Info level - user-visible actions
748-
logger.info(
749-
{ userId, messageCount },
750-
'Chat session started successfully'
751-
)
752-
753-
// Warn level - recoverable issues
754-
logger.warn(
755-
{ messageId, attemptCount },
756-
'Message retry attempt failed, will retry'
757-
)
758-
759-
// Error level - operation failures
760-
logger.error(
761-
{ error: err.message, apiEndpoint },
762-
'API request failed'
763-
)
764-
```
765-
766-
### Logging Anti-Patterns
767-
768-
❌ **Don't**: Log at `info` level for every state change
769-
```typescript
770-
logger.info('[State] Counter incremented') // Too noisy!
771-
```
772-
773-
✅ **Do**: Use `debug` for internal state changes
774-
```typescript
775-
logger.debug({ counter }, '[State] Counter updated')
776-
```
777-
778-
❌ **Don't**: Include sensitive information in logs
779-
```typescript
780-
logger.info({ apiKey, password }, 'User authenticated') // Security risk!
781-
```
782-
783-
✅ **Do**: Sanitize or omit sensitive data
784-
```typescript
785-
logger.info({ userId }, 'User authenticated')
786-
```

0 commit comments

Comments
 (0)