0
# Performance Instrumentation
1

2
Built-in performance monitoring and profiling tools with timer support and automatic reporting for development workflows. The Instrumentation class provides hit counting and nested timing capabilities with detailed reporting.
3

4
## Capabilities
5

6
### Instrumentation Class
7

8
Performance monitoring class with disposable pattern for automatic reporting.
9

10
```typescript { .api }
11
/**
12
 * Performance instrumentation and profiling class
13
 * Implements Disposable for automatic cleanup and reporting
14
 */
15
class Instrumentation implements Disposable {
16
  /**
17
   * Creates a new instrumentation instance
18
   * @param defaultFlush - Optional custom flush function for output (defaults to stderr)
19
   */
20
  constructor(defaultFlush?: (message: string) => void);
21

22
  /**
23
   * Records a hit counter for the given label
24
   * @param label - Identifier for the counter
25
   */
26
  hit(label: string): void;
27

28
  /**
29
   * Starts a timer with the given label
30
   * Supports nested timers with hierarchical labeling
31
   * @param label - Identifier for the timer
32
   */
33
  start(label: string): void;
34

35
  /**
36
   * Ends the most recently started timer with the given label
37
   * @param label - Identifier for the timer (must match the most recent start())
38
   * @throws Error if label doesn't match the most recent timer
39
   */
40
  end(label: string): void;
41

42
  /**
43
   * Resets all counters and timers
44
   * Clears all recorded data and timer stack
45
   */
46
  reset(): void;
47

48
  /**
49
   * Generates and outputs a performance report
50
   * @param flush - Optional custom output function (uses constructor default if not provided)
51
   */
52
  report(flush?: (message: string) => void): void;
53

54
  /**
55
   * Automatic cleanup method (Symbol.dispose)
56
   * Automatically calls report() if DEBUG environment variable is enabled
57
   */
58
  [Symbol.dispose](): void;
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { Instrumentation } from "@tailwindcss/node";
66

67
// Basic usage with automatic disposal
68
{
69
  using instrumentation = new Instrumentation();
70
  
71
  instrumentation.hit("process-start");
72
  
73
  instrumentation.start("compilation");
74
  // ... compilation work ...
75
  instrumentation.end("compilation");
76
  
77
  instrumentation.start("optimization");
78
  // ... optimization work ...
79
  instrumentation.end("optimization");
80
  
81
  // Report is automatically generated when exiting scope (if DEBUG=true)
82
}
83

84
// Manual reporting
85
const instrumentation = new Instrumentation();
86

87
instrumentation.start("build-process");
88

89
instrumentation.start("css-parsing");
90
// ... parsing work ...
91
instrumentation.end("css-parsing");
92

93
instrumentation.start("asset-processing");
94
// ... asset work ...
95
instrumentation.end("asset-processing");
96

97
instrumentation.end("build-process");
98

99
// Generate report manually
100
instrumentation.report();
101

102
// Custom output function
103
const logs: string[] = [];
104
instrumentation.report((message) => {
105
  logs.push(message);
106
});
107
```
108

109
### Nested Timing Example
110

111
The instrumentation system supports nested timers with hierarchical labeling:
112

113
```typescript
114
import { Instrumentation } from "@tailwindcss/node";
115

116
const instrumentation = new Instrumentation();
117

118
instrumentation.start("build");
119
  instrumentation.start("compile");
120
    instrumentation.start("parse-css");
121
    instrumentation.end("parse-css");
122
    
123
    instrumentation.start("process-styles");  
124
    instrumentation.end("process-styles");
125
  instrumentation.end("compile");
126
  
127
  instrumentation.start("optimize");
128
  instrumentation.end("optimize");
129
instrumentation.end("build");
130

131
instrumentation.report();
132

133
// Output example:
134
// Timers:
135
// [  45.23ms] build × 1
136
// [  32.15ms]  ↳ compile × 1  
137
// [  12.80ms]   ↳ parse-css × 1
138
// [  18.45ms]   ↳ process-styles × 1
139
// [  11.08ms]  ↳ optimize × 1
140
```
141

142
### Hit Counter Example
143

144
Hit counters track how many times specific operations occur:
145

146
```typescript
147
import { Instrumentation } from "@tailwindcss/node";
148

149
const instrumentation = new Instrumentation();
150

151
// Track cache hits/misses
152
for (let i = 0; i < 100; i++) {
153
  if (cache.has(key)) {
154
    instrumentation.hit("cache-hit");
155
  } else {
156
    instrumentation.hit("cache-miss");
157
  }
158
}
159

160
instrumentation.report();
161

162
// Output example:
163
// Hits:
164
//   cache-hit × 85
165
//   cache-miss × 15
166
```
167

168
### Custom Output Function
169

170
You can provide custom output functions for different logging systems:
171

172
```typescript
173
import { Instrumentation } from "@tailwindcss/node";
174

175
// Custom logger integration
176
const instrumentation = new Instrumentation((message) => {
177
  logger.debug(message);
178
});
179

180
// Or provide at report time
181
const metrics: string[] = [];
182
instrumentation.report((message) => {
183
  metrics.push(message);
184
  // Send to monitoring system
185
  sendToMonitoring(message);
186
});
187
```
188

189
## Environment Integration
190

191
The instrumentation system integrates with the environment debugging system:
192

193
```typescript
194
import { env } from "@tailwindcss/node";
195

196
// When DEBUG environment variable is enabled, instrumentation
197
// automatically reports on disposal
198
if (env.DEBUG) {
199
  using instrumentation = new Instrumentation();
200
  // ... work ...
201
  // Report is automatically generated when scope exits
202
}
203
```
204

205
## Error Handling
206

207
The instrumentation system includes built-in error checking:
208

209
```typescript
210
import { Instrumentation } from "@tailwindcss/node";
211

212
const instrumentation = new Instrumentation();
213

214
instrumentation.start("outer");
215
instrumentation.start("inner");
216

217
// This will throw an error - must end "inner" before "outer"
218
try {
219
  instrumentation.end("outer"); // Error: Mismatched timer label
220
} catch (error) {
221
  console.error(error.message);
222
  // Correct the order
223
  instrumentation.end("inner");
224
  instrumentation.end("outer");
225
}
226
```
227

228
## Performance Considerations
229

230
- Timers use `process.hrtime.bigint()` for high-resolution timing
231
- Hit counters use simple integer increments for minimal overhead
232
- Nested timer tracking maintains a lightweight stack
233
- Automatic cleanup prevents memory leaks in long-running processes