feat(logging): human-readable console logs and cleaner plugin errors #7293

davidecavaliere · 2026-02-11T10:27:55Z

Summary

This PR improves the developer experience when working with Countly by making console logs more human-readable during development.

Changes

Human-readable console logs

Enable pino-pretty by default for console output
Simplify timestamps to show only time (HH:MM:ss.l) instead of full datetime
JSON output can still be enabled via config.logging.prettyPrint = false for production/log aggregation

Cleaner plugin load errors

Plugin load failures now show a single concise line instead of dumping the full stack trace
Full error details available via DEBUG=countly:plugins environment variable

Why these changes?

Console readability: The default JSON output from Pino is optimized for machine parsing and log aggregation, but it's difficult for developers to scan during local development. Pretty-printed logs with simplified timestamps make it much easier to follow what's happening when debugging.

Debug-js for verbose errors: When a plugin fails to load due to a missing dependency, the full stack trace with "Require stack" clutters the console and obscures other important startup messages. Using debug-js follows the Node.js ecosystem convention where verbose output is opt-in via the DEBUG environment variable, keeping the default output clean while preserving access to detailed diagnostics when needed.

Test plan

Start API server and verify logs are pretty-printed with time-only timestamps
Verify plugin load errors show single-line message
Verify DEBUG=countly:plugins shows full stack traces
Verify config.logging.prettyPrint = false disables pretty-printing

🤖 Generated with Claude Code

Example of console output from starting the ingestor process

Example of console output when starting api without `DEBUG` set

### Example of console output when starting api with `DEBUG=countly:*`

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

kanwarujjaval · 2026-02-12T05:44:38Z

api/utils/log.js

+        // Set config.logging.prettyPrint = false for JSON output (e.g., for log aggregation)
+        this.#prettyPrint = this.#prefs.prettyPrint !== false;

        // Initialize OpenTelemetry metrics if available


I like this but please dont enable this by default.
This is only good for dev envs, since most of our logs are now json ( the ones that are not will be converted ) They will be human readable for prod using grafana or other tools.

The other issue with pretty is it works with event emitter and since countly has huge number of subloggers (plugins,modules each have their own) This can cause memory leaks and similar issues

ref: pinojs/pino-pretty#387
ref: pinojs/pino#144

Lets keep this but not enable by default, or by default when NODE_ENV === development or similar?

Copilot

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 3 comments.

Copilot · 2026-02-12T07:29:17Z

package.json

    "@types/underscore": "^1.13.0",
    "@typescript-eslint/eslint-plugin": "^8.54.0",
    "@typescript-eslint/parser": "^8.54.0",
+    "debug": "^4.4.3",


debug is required at runtime from plugins/pluginManager.ts, but it's being added under devDependencies. If Countly is installed with npm ci --omit=dev / production-only installs, require('debug') will throw and the plugin manager will crash on startup. Move debug to dependencies or make the import optional (fallback to a no-op logger).

Copilot · 2026-02-12T07:29:17Z

plugins/pluginManager.ts

 const spawn: typeof cp.spawn = cp.spawn;
 const configextender: ConfigExtenderFn = require('../api/configextender');

+const d = debug('countly:pluginManager');


The PR description says verbose plugin load errors are available via DEBUG=countly:plugins, but the code uses debug('countly:pluginManager'). Either switch the namespace to match the documented env var, or update the PR/docs so developers know which DEBUG value to set.

Copilot · 2026-02-12T07:29:17Z

api/utils/log.js

+        // Pretty-print enabled by default for human-readable console output
+        // Set config.logging.prettyPrint = false for JSON output (e.g., for log aggregation)
+        this.#prettyPrint = this.#prefs.prettyPrint !== false;


Defaulting prettyPrint to enabled (prettyPrint !== false) is a behavior change from the existing config docs/sample (api/config.sample.js documents [prettyPrint=false]). This can surprise production/log aggregation setups if they haven't explicitly set the flag. Consider enabling pretty printing only when process.stdout.isTTY / non-production, and/or update the sample config/docs to reflect the new default clearly.

- Enable pretty-print by default for better developer experience - Use pino-pretty as direct stream instead of pino.transport() - Simplify timestamp to show time only (HH:MM:ss.l) - Add graceful fallback when pino-pretty is not available Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add debug package for conditional verbose logging - Show clean one-line error on plugin load failure - Full stack trace only visible with DEBUG=countly:plugins Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Pretty-print for human-readable output in terminals and CI, JSON for log aggregation in production (Docker/PM2/pipes). - TTY detected → pretty format - CI env var set → pretty format - Otherwise → JSON for collectors (Loki, ELK, etc.) Explicit config still overrides: `logging.prettyPrint: true|false` Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

davidecavaliere requested review from ArtursKadikis, ar2rsawseen, Copilot and kanwarujjaval February 11, 2026 10:41

Copilot started reviewing on behalf of davidecavaliere February 11, 2026 10:41 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

kanwarujjaval requested changes Feb 12, 2026

View reviewed changes

kanwarujjaval requested a review from Copilot February 12, 2026 07:24

Copilot started reviewing on behalf of kanwarujjaval February 12, 2026 07:25 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

davidecavaliere and others added 4 commits February 13, 2026 11:09

refactor(plugins): use debug-js for verbose plugin load errors 🔇

fc7f945

- Add debug package for conditional verbose logging - Show clean one-line error on plugin load failure - Full stack trace only visible with DEBUG=countly:plugins Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore: fix codacy error

d627811

davidecavaliere force-pushed the refactor/human_readable_logs_in_console branch from a800b57 to bbe1fd5 Compare February 13, 2026 10:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(logging): human-readable console logs and cleaner plugin errors #7293

feat(logging): human-readable console logs and cleaner plugin errors #7293

davidecavaliere commented Feb 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

kanwarujjaval Feb 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(logging): human-readable console logs and cleaner plugin errors #7293

Are you sure you want to change the base?

feat(logging): human-readable console logs and cleaner plugin errors #7293

Conversation

davidecavaliere commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Why these changes?

Test plan

Example of console output from starting the ingestor process

Example of console output when starting api without DEBUG set

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

kanwarujjaval Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

davidecavaliere commented Feb 11, 2026 •

edited

Loading

Example of console output when starting api without `DEBUG` set