中文版

Generated reference snapshot

Original Cubic page · captured 2026-09-23 · source commit. This AI-generated page has not been verified against the current code. Use the Zhin documentation for current behavior and see known corrections.

Relevant source files

The following files were used as context for generating this wiki page:

• basic/logger/src/logger.ts
• packages/im/plugin-runtime/src/system-log.ts
• basic/logger/README.md
• basic/logger/tests/logger.test.ts
• basic/logger/package.json
• SECURITY.md
• basic/cli/src/commands/migrate.ts
• basic/cli/src/commands/setup.ts

Logging & Telemetry

Zhin provides a high-performance, structured logging system through the @zhin.js/logger package. This system supports hierarchical namespaces, customizable transports, and performance telemetry to monitor bot activity and system health.

Core Architecture

The logging system centers on the Logger class, which manages log levels, formatters, and output transports. Developers access loggers through the getLogger function, which creates or retrieves scoped instances based on a name string.

Logger Hierarchy

Loggers follow a parent-child relationship. A child logger automatically inherits its parent's log level, formatter, and transports unless explicitly overridden. Namespaces are joined by colons (e.g., App:Database).

The diagram shows how namespaces organize loggers into a tree structure for inherited configuration. Sources: basic/logger/README.md:105-125, basic/logger/tests/logger.test.ts:192-196

Log Levels

Zhin defines five standard log levels. The system filters logs based on the current threshold; logs with a lower priority than the threshold do not process.

Level	Value	Description
DEBUG	0	Detailed information for debugging.
INFO	1	General system information.
WARN	2	Potentially harmful situations.
ERROR	3	Error events that might allow the system to continue.
SILENT	4	Disables all logging output.

Sources: basic/logger/README.md:310-316, basic/logger/tests/logger.test.ts:60-70

Log Data Flow

When a component calls a log method (e.g., logger.info()), the system processes the entry through several stages:

This flow illustrates the lifecycle of a log message from invocation to final output. Sources: basic/logger/README.md:318-350, basic/logger/tests/logger.test.ts:220-250

Formatting

The DefaultFormatter organizes log data into a readable string. It uses a standard pattern: [Date][Level] [Name] Message.

• Date: Formatted as HH:mm:ss.SSS.
• Name: Represents the category, omitting the Zhin prefix for root-level children.
• Level: Color-coded output for console terminals.

Sources: basic/logger/tests/logger.test.ts:160-185, basic/logger/README.md:40-50

Telemetry & Performance Monitoring

The Logger class provides built-in methods for measuring execution time. This telemetry helps identify performance bottlenecks in command execution or plugin initialization.

• logger.time(label): Starts a high-precision timer associated with the provided label.
• logger.timeEnd(label): Ends the timer and logs the duration in milliseconds.

const timer = logger.time('data-processing');
// ... perform complex logic
timer.end(); // Outputs: data-processing took 12.45ms

Sources: basic/logger/tests/logger.test.ts:80-95, basic/logger/README.md:140-150

Security & Best Practices

Logging sensitive information presents security risks. Zhin project guidelines recommend specific precautions for telemetry and logs:

1. Avoid Sensitive Data: Do not record API tokens, .env content, user IDs, or internal URLs in logs.
2. Sanitize Output: Replace sensitive fields with <REDACTED> before logging.
3. Log Levels in Production: Set the log level to INFO or WARN in production to reduce overhead and limit data exposure.
4. Error Handling: Log errors with full stacks in development but use generalized messages for end-users to prevent information leakage.

Sources: SECURITY.md:85-95, packages/toolkit/create-zhin/template/skills/summarize/SKILL.md:110-115

Usage Examples

Scoped Plugin Logging

Plugins typically create a scoped logger during initialization to differentiate their logs from the core framework.

import { getLogger } from '@zhin.js/logger';

const logger = getLogger('plugin-my-feature');
logger.success('Feature initialized');
logger.warn('Configuration missing optional field: %s', 'api_key');

Sources: basic/logger/README.md:20-35, basic/cli/src/commands/setup.ts:160

Global Configuration

Global settings apply to the default logger and are inherited by all new instances.

import { setLevel, LogLevel, addTransport, FileTransport } from '@zhin.js/logger';
import fs from 'node:fs';

setLevel(LogLevel.INFO);
const stream = fs.createWriteStream('./bot.log');
addTransport(new FileTransport(stream));

Sources: basic/logger/README.md:265-285

Conclusion

The Logging & Telemetry system in Zhin facilitates robust monitoring through its hierarchical design and performance tracking tools. By utilizing scoped loggers and appropriate transports, developers can maintain clear visibility into their bot's behavior while adhering to security best practices.