0
# Logging Utilities
1

2
Ice.js provides a sophisticated logging system with namespace support and debug controls for development and production environments. The logging system is built on top of consola with additional features for better debugging experience.
3

4
## Capabilities
5

6
### Create Logger
7

8
Creates a namespaced logger instance with debug controls and intelligent filtering.
9

10
```typescript { .api }
11
/**
12
 * Creates a namespaced logger instance
13
 * @param namespace - Optional namespace for the logger (supports wildcards)
14
 * @returns Logger instance with all logging methods
15
 */
16
function createLogger(namespace?: string): Logger;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { createLogger } from "@ice/app";
23

24
// Default logger (no namespace)
25
const logger = createLogger();
26
logger.info('Application started');
27

28
// Namespaced logger
29
const dbLogger = createLogger('database');
30
dbLogger.debug('Database query executed');
31

32
// Component-specific logger
33
const componentLogger = createLogger('component:user-list');
34
componentLogger.warn('Component re-rendered');
35
```
36

37
### Default Logger
38

39
Pre-configured logger instance ready for immediate use.
40

41
```typescript { .api }
42
/**
43
 * Default logger instance without namespace
44
 */
45
const logger: Logger;
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { logger } from "@ice/app";
52

53
logger.start('Build process starting...');
54
logger.success('Build completed successfully');
55
logger.error('Build failed with error:', error);
56
```
57

58
### Logger Interface
59

60
Complete interface for all logger instances with support for different log levels.
61

62
```typescript { .api }
63
interface Logger {
64
  /** Fatal level logging - for critical errors that stop execution */
65
  fatal(message: any, ...args: any[]): void;
66
  /** Error level logging - for errors that don't stop execution */
67
  error(message: any, ...args: any[]): void;
68
  /** Warning level logging - for potential issues */
69
  warn(message: any, ...args: any[]): void;
70
  /** Standard logging - for general information */
71
  log(message: any, ...args: any[]): void;
72
  /** Info level logging - for informational messages */
73
  info(message: any, ...args: any[]): void;
74
  /** Start event logging - for process start notifications */
75
  start(message: any, ...args: any[]): void;
76
  /** Success event logging - for successful operations */
77
  success(message: any, ...args: any[]): void;
78
  /** Ready event logging - for readiness notifications */
79
  ready(message: any, ...args: any[]): void;
80
  /** Debug level logging - for debugging information */
81
  debug(message: any, ...args: any[]): void;
82
  /** Trace level logging - for detailed execution traces */
83
  trace(message: any, ...args: any[]): void;
84
  /** Brief error logging with instructions for detailed errors */
85
  briefError(message: any, ...args: any[]): void;
86
}
87
```
88

89
## Debug Control
90

91
The logging system supports debug controls through the `DEBUG_TAG` environment variable, allowing you to filter logs by namespace.
92

93
### Environment Variables
94

95
```bash
96
# Enable all debug logs
97
DEBUG_TAG=* npm start
98

99
# Enable specific namespace
100
DEBUG_TAG=database npm start
101

102
# Enable multiple namespaces
103
DEBUG_TAG=database,component:* npm start
104

105
# Disable specific namespace
106
DEBUG_TAG=*,-component:user-list npm start
107
```
108

109
### Namespace Patterns
110

111
The debug system supports wildcard patterns similar to the debug library:
112

113
```typescript
114
// Enable all component logs
115
DEBUG_TAG=component:*
116

117
// Enable specific component
118
DEBUG_TAG=component:user-list
119

120
// Enable multiple patterns
121
DEBUG_TAG=database,component:*,service:auth
122

123
// Disable specific patterns
124
DEBUG_TAG=*,-component:legacy-*
125
```
126

127
## Advanced Usage
128

129
### Brief Error Logging
130

131
The `briefError` method provides user-friendly error messages with instructions for viewing detailed error information:
132

133
```typescript
134
import { createLogger } from "@ice/app";
135

136
const logger = createLogger('build');
137

138
try {
139
  // Some operation that might fail
140
  await buildProject();
141
} catch (error) {
142
  // Shows brief error and instructions for detailed debugging
143
  logger.briefError('Build failed', error);
144
  // Output: "Build failed [error details]"
145
  // If DEBUG_TAG is not set: "run `DEBUG_TAG=build npm run start` to view error details"
146
}
147
```
148

149
### Logger Integration in Plugins
150

151
Logger can be used effectively in Ice.js plugins:
152

153
```typescript
154
import { createLogger } from "@ice/app";
155

156
const logger = createLogger('plugin:my-plugin');
157

158
export default function myPlugin() {
159
  return {
160
    setup({ onHook }) {
161
      logger.info('Plugin initialized');
162
      
163
      onHook('before:compile', () => {
164
        logger.debug('Starting compilation...');
165
      });
166
      
167
      onHook('after:compile', () => {
168
        logger.success('Compilation completed');
169
      });
170
    }
171
  };
172
}
173
```
174

175
### Development vs Production
176

177
The logging system automatically adjusts behavior based on the environment:
178

179
- **Development**: All logs are shown by default
180
- **Production**: Only logs matching DEBUG_TAG patterns are shown
181
- **Brief errors**: Always provide debug instructions when DEBUG_TAG is not set
182

183
## Type Definitions
184

185
```typescript { .api }
186
type ICELogNamespace = string;
187
type CreateLogger = (namespace?: ICELogNamespace) => Logger;
188

189
interface CreateLoggerReturnType extends Logger {
190
  briefError?: (message: any, ...args: any[]) => void;
191
}
192
```