|
| 1 | +# Countly Server Observability Guidelines |
| 2 | + |
| 3 | +This document describes best practices for logging, debugging, and error reporting in Countly Server. All contributors must follow these guidelines to ensure robust observability and traceability. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Logging Library |
| 8 | +- **Always use** `api/utils/log.js` for all logging. Do **not** use `console.log` or similar. |
| 9 | +- The logger provides levels: `debug`, `info`, `warn`, `error`. |
| 10 | +- Example usage: |
| 11 | + ```js |
| 12 | + const log = require('../../../api/utils/log.js')('crashes:api'); |
| 13 | + log.d('Debug message'); |
| 14 | + log.e('Error occurred: %j', error); |
| 15 | + ``` |
| 16 | + |
| 17 | +## 2. Module Naming Convention |
| 18 | +- **Plugin files:** Use the plugin name as the logger prefix. Example: `crashes`, `push`, `views`. |
| 19 | +- **Submodules:** Separate submodules with `:`. Example: `crashes:api`, `crashes:render`. |
| 20 | +- **Core files:** Prefix with `core:`. Example: `core:render`, `core:auth`. |
| 21 | +- **Job files:** Prefix with `job:`. Example: `job:crashes`, `job:push`. This allows enabling/disabling logging for all jobs at once. |
| 22 | + |
| 23 | +## 3. Logging Practices |
| 24 | +- **Log all errors** and error handling with `error` level (`log.e`). |
| 25 | +- **Add debug logs** (`log.d`) at every major step of execution to trace code flow. |
| 26 | +- Use `log.i` for important state changes, and `log.w` for warnings. |
| 27 | +- Use the logger's `callback` and `logdb` helpers for error logging in async/database operations. |
| 28 | +- Example: |
| 29 | + ```js |
| 30 | + log.d('Starting job execution'); |
| 31 | + // ... |
| 32 | + log.e('Failed to process job: %j', err); |
| 33 | + ``` |
| 34 | + |
| 35 | +## 4. Enabling Logging |
| 36 | +- **Via Dashboard:** Go to Management → Settings → Logs to configure log levels and modules. |
| 37 | +- **Via Environment Variables:** |
| 38 | + - Set `DEBUG=*` to enable all debug logs. |
| 39 | + - Set `DEBUG=crashes:*,job:*` to enable debug logs for all crashes and job modules. |
| 40 | + - Example: |
| 41 | + ```bash |
| 42 | + DEBUG=core:*,crashes:api npm run start:all:dev |
| 43 | + ``` |
| 44 | + |
| 45 | +## 5. Log Level Configuration |
| 46 | +- Log levels can be set in `api/config.js` under the `logging` section. |
| 47 | +- Example: |
| 48 | + ```js |
| 49 | + logging: { |
| 50 | + info: ['core', 'crashes'], |
| 51 | + debug: ['job:*'], |
| 52 | + default: 'warn' |
| 53 | + } |
| 54 | + ``` |
| 55 | +- You can also set log levels at runtime: |
| 56 | + ```js |
| 57 | + require('api/utils/log.js').setLevel('job:crashes', 'debug'); |
| 58 | + ``` |
| 59 | + |
| 60 | +## 6. Error Handling |
| 61 | +- **Always log errors** with `log.e`. |
| 62 | +- Use logger's `callback` and `logdb` for async/database error handling. |
| 63 | +- Example: |
| 64 | + ```js |
| 65 | + someAsyncOperation(log.callback((result) => { |
| 66 | + log.d('Operation completed', result); |
| 67 | + })); |
| 68 | + ``` |
| 69 | +
|
| 70 | +## 7. Debugging Flow |
| 71 | +- Add debug logs at: |
| 72 | + - Function entry/exit |
| 73 | + - Major state changes |
| 74 | + - Before/after external calls (DB, API, etc.) |
| 75 | + - All error handling branches |
| 76 | +- This enables tracing execution in debug mode. |
| 77 | +
|
| 78 | +## 8. References |
| 79 | +- See `api/utils/log.js` for advanced usage (sub-loggers, logdb, callback, etc.). |
| 80 | +- See [CODING_GUIDELINES.md](../CODING_GUIDELINES.md) for general code standards. |
| 81 | +
|
| 82 | +--- |
| 83 | +
|
| 84 | +
|
| 85 | +## Log Message Formatting |
| 86 | +
|
| 87 | +- **Be clear and concise:** Log messages should be easy to understand and provide enough context for debugging. |
| 88 | +- **Use structured formatting:** Prefer format specifiers (`%s`, `%j`, `%d`, etc.) for variables and objects. Example: |
| 89 | + ```js |
| 90 | + log.d('Processing user %s with data: %j', userId, userData); |
| 91 | + ``` |
| 92 | +- **Include relevant identifiers:** Always log IDs, error objects, and key parameters to help trace issues. |
| 93 | +- **Timestamp and level:** The logger automatically adds timestamps and log levels to each message. |
| 94 | +- **Consistent style:** Use similar phrasing for similar events across modules (e.g., "Starting job", "Job completed", "Error processing job"). |
| 95 | +- **Avoid sensitive data:** Never log credentials, secrets, or personal data. |
| 96 | +- **Multi-line logs:** For complex objects, use `%j` to pretty-print JSON. For multi-step flows, use separate log statements for each step. |
| 97 | +
|
| 98 | +--- |
| 99 | +
|
| 100 | +**Consistent, structured logging is required for all new code.** |
0 commit comments