Skip to content

Commit 11d0958

Browse files
committed
fix(logging): enhance logging guidelines with additional principles and sections
1 parent a8dab0e commit 11d0958

File tree

1 file changed

+10
-9
lines changed

1 file changed

+10
-9
lines changed

.github/prompts/dev.implement-logging.prompt.md

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,13 @@ For every file that uses logging (or should but does not), evaluate compliance a
3333
- **Silent failures**: bare `except:` or `except Exception:` without logging.
3434
- **Mixed output channels**: some modules using central logger while others bypass it.
3535

36-
### Principles
36+
### Principles 🧭
3737

3838
- **Signal over noise**: logs must capture intent, boundaries, decisions, and failures—not routine execution. Flag verbose or redundant log statements.
3939
- **Structured format**: prefer key=value pairs or JSON; avoid unstructured prose that is hard to parse.
4040
- **Consistency**: log fields, levels, and phrasing should be uniform across all classes and modules. Flag deviations.
4141

42-
### Project-level logger configuration
42+
### Project-level logger configuration 🏗️
4343

4444
- **Single configuration point**: one central factory or module must define logger setup; all other modules import from it.
4545
- **Environment-driven settings**: log level, sinks, and format must be configurable via environment variables or a config file, not hard-coded.
@@ -49,14 +49,15 @@ For every file that uses logging (or should but does not), evaluate compliance a
4949
- **No accidental duplication**: require explicit configuration to enable multiple sinks; guard against double logging.
5050
- **Redaction before output**: sensitive fields must be scrubbed before any sink receives the log entry.
5151

52-
### Class-level logging
52+
### Class-level logging 🧩
5353

54+
- **Bound logger pattern (mandatory)**: use the factory function `get_logger(component="ClassName")` which returns a `BoundLogger` pre-bound to the component name. Call log methods directly on the bound logger (`self._logger.debug(...)`) rather than defining per-class wrapper methods (`_log_debug`, `_log_info`, etc.). This eliminates boilerplate and ensures a single point of change.
5455
- **One logger per class/module**: instantiate a logger with the class or module name so context is always present.
5556
- **Constructor logging**: log significant configuration or injected dependencies once at INFO when the object is created.
5657
- **Lifecycle events**: log state transitions (started, stopped, reloaded) at INFO or WARN as appropriate.
5758
- **Dependency failures**: include identifiers, error details, and retry information when logging external dependency issues.
5859

59-
### Method-level logging
60+
### Method-level logging 🧪
6061

6162
- **Entry and exit traces**: every non-trivial method should log entry and exit at DEBUG or TRACE—unless it is a hot path.
6263
- **Safe input logging**: log inputs only after sanitisation; never log secrets, tokens, or PII.
@@ -65,7 +66,7 @@ For every file that uses logging (or should but does not), evaluate compliance a
6566
- **Timing information**: log duration for slow or critical operations (or emit metrics instead).
6667
- **Avoid noise**: do not add "started/finished" logs to trivial or idempotent methods.
6768

68-
### Log levels
69+
### Log levels 🎚️
6970

7071
| Level | Purpose |
7172
| ----- | ----------------------------------------- |
@@ -77,13 +78,13 @@ For every file that uses logging (or should but does not), evaluate compliance a
7778

7879
Flag any misuse (e.g., logging an error condition at INFO).
7980

80-
### Content
81+
### Content 🧾
8182

8283
- **Contextual identifiers**: include correlation/request ID, user/session ID (where safe), and operation name.
8384
- **No secrets**: never log passwords, tokens, API keys, or full request/response bodies.
8485
- **Redaction and truncation**: mask sensitive fields and truncate large payloads to a reasonable length.
8586

86-
### Console visualisation
87+
### Console visualisation 🖥️
8788

8889
- **Colour as enhancement**: use colour to reinforce meaning, but always pair with text labels, symbols, or icons for accessibility.
8990
- **Contrast and colour-blindness**: ensure sufficient contrast; avoid red/green-only distinctions.
@@ -94,7 +95,7 @@ Flag any misuse (e.g., logging an error condition at INFO).
9495
- **Level tags and icons**: use short, consistent tags (INFO, WARN, ERROR) with an optional single icon per level.
9596
- **Bounded output**: truncate or wrap large fields; never allow unbounded blobs to break layout.
9697

97-
### Performance
98+
### Performance
9899

99100
- **Guard expensive construction**: wrap costly string formatting or object serialisation in a level check (e.g., `if logger.isEnabledFor(DEBUG)`).
100101
- **Avoid tight-loop logging**: do not log inside hot loops unless sampled or rate-limited.
@@ -118,5 +119,5 @@ Flag any misuse (e.g., logging an error condition at INFO).
118119

119120
---
120121

121-
> **Version**: 1.1.0
122+
> **Version**: 1.1.1
122123
> **Last Amended**: 2026-01-28

0 commit comments

Comments
 (0)