0
# Logging and Reporting
1

2
Flexible logging framework with filtering, progress reporting, and console output management.
3

4
## Capabilities
5

6
### Logger Factory
7

8
Factory methods for creating loggers with various output configurations.
9

10
```scala { .api }
11
object Loggers {
12
  /**
13
   * Create composite logger with console and optional file output
14
   * @param level Logging level (Debug, Info, Warn, Error)
15
   * @param color Enable colored console output
16
   * @param out Console output destination (default: system out)
17
   * @param captureLog Optional file for capturing log output
18
   * @return Logger instance with specified configuration
19
   */
20
  def create(level: Level.Value, color: Boolean, 
21
             out: ConsoleOut = ConsoleOut.systemOut, 
22
             captureLog: Option[File] = None): Logger
23
}
24
```
25

26
### Reporter Factory
27

28
Factory for creating reporters with filtering capabilities for compilation messages.
29

30
```scala { .api }
31
object Reporters {
32
  /**
33
   * Create filtered reporter for compilation messages
34
   * @param log Underlying logger for message output
35
   * @param fileFilters Regex patterns to filter warnings by file path
36
   * @param msgFilters Regex patterns to filter warnings by message content
37
   * @param maximumErrors Maximum number of errors before stopping (default: 100)
38
   * @return Reporter with specified filtering configuration
39
   */
40
  def create(log: Logger, fileFilters: Seq[Regex], msgFilters: Seq[Regex], 
41
             maximumErrors: Int = 100): Reporter
42
}
43
```
44

45
### Regex Filter Reporter
46

47
Reporter implementation that filters compilation warnings using regex patterns.
48

49
```scala { .api }
50
class RegexFilterReporter(
51
  fileFilters: Seq[Regex],          // File path filter patterns
52
  msgFilters: Seq[Regex],           // Message content filter patterns
53
  maximumErrors: Int,               // Maximum error count
54
  log: Logger                       // Underlying logger
55
) extends Reporter {
56
  /**
57
   * Log compilation message with filtering
58
   * @param pos Source position information
59
   * @param msg Compilation message
60
   * @param sev Message severity level
61
   */
62
  def log(pos: xsbti.Position, msg: String, sev: xsbti.Severity): Unit
63
  
64
  /**
65
   * Report compilation problem with filtering
66
   * @param problem Compilation problem details
67
   */
68
  def report(problem: xsbti.Problem): Unit
69
  
70
  /**
71
   * Check if any errors have been reported
72
   * @return True if errors were reported
73
   */
74
  def hasErrors: Boolean
75
  
76
  /**
77
   * Check if any warnings have been reported
78
   * @return True if warnings were reported
79
   */
80
  def hasWarnings: Boolean
81
  
82
  /**
83
   * Get problems reported during compilation
84
   * @return Array of reported problems
85
   */
86
  def problems: Array[xsbti.Problem]
87
  
88
  /**
89
   * Reset reporter state
90
   */
91
  def reset(): Unit
92
}
93
```
94

95
### Progress Reporting
96

97
Simple compilation progress implementation with phase logging and heartbeat monitoring.
98

99
```scala { .api }
100
class SimpleCompileProgress(
101
  logPhases: Boolean,               // Log compilation phases
102
  printProgress: Boolean,           // Print progress percentage
103
  heartbeatSecs: Int                // Heartbeat interval in seconds
104
)(log: Logger) extends xsbti.compile.CompileProgress {
105
  
106
  /**
107
   * Report start of compilation phase for a source unit
108
   * @param phase Compilation phase name
109
   * @param unitPath Path to source unit being compiled
110
   */
111
  def startUnit(phase: String, unitPath: String): Unit
112
  
113
  /**
114
   * Report compilation progress and handle heartbeat
115
   * @param current Current number of completed units
116
   * @param total Total number of units to compile
117
   * @return True to continue compilation, false to cancel
118
   */
119
  def advance(current: Int, total: Int): Boolean
120
}
121
```
122

123
## Usage Examples
124

125
### Basic Logging Setup
126

127
```scala
128
import org.pantsbuild.zinc.logging._
129
import org.pantsbuild.zinc.Level
130
import java.io.File
131

132
// Create console logger with colored output
133
val log = Loggers.create(
134
  level = Level.Info,
135
  color = true
136
)
137

138
// Create logger with file capture
139
val logWithFile = Loggers.create(
140
  level = Level.Debug,
141
  color = false,
142
  captureLog = Some(new File("compilation.log"))
143
)
144

145
// Use logger
146
log.info("Starting compilation...")
147
log.warn("Deprecated API usage detected")
148
log.error("Compilation failed")
149
```
150

151
### Reporter with Filtering
152

153
```scala
154
import org.pantsbuild.zinc.logging._
155
import java.util.regex.Pattern
156
import scala.util.matching.Regex
157

158
// Create reporter with warning filters
159
val fileFilters = Seq(
160
  ".*generated.*".r,              // Filter warnings from generated files
161
  ".*test.*".r                    // Filter warnings from test files
162
)
163

164
val msgFilters = Seq(
165
  ".*deprecated.*".r,             // Filter deprecation warnings
166
  ".*unused import.*".r           // Filter unused import warnings
167
)
168

169
val reporter = Reporters.create(
170
  log = log,
171
  fileFilters = fileFilters,
172
  msgFilters = msgFilters,
173
  maximumErrors = 50
174
)
175

176
// Use reporter in compilation
177
compiler.compile(inputs, cwd, reporter, progress)(log)
178

179
// Check compilation results
180
if (reporter.hasErrors) {
181
  println("Compilation failed with errors")
182
  reporter.problems.foreach(problem => log.error(problem.message))
183
}
184
```
185

186
### Progress Reporting
187

188
```scala
189
import org.pantsbuild.zinc._
190

191
// Create progress reporter
192
val progress = new SimpleCompileProgress(
193
  logPhases = true,                // Log each compilation phase
194
  printProgress = true,            // Print percentage progress  
195
  heartbeatSecs = 30               // Heartbeat every 30 seconds
196
)(log)
197

198
// Use in compilation
199
compiler.compile(inputs, cwd, reporter, progress)(log)
200
```
201

202
### Advanced Reporter Configuration
203

204
```scala
205
import org.pantsbuild.zinc.logging._
206

207
// Create custom regex filter reporter
208
val customReporter = new RegexFilterReporter(
209
  fileFilters = Seq(
210
    ".*/target/.*".r,              // Exclude build output directories
211
    ".*/\\..*".r                   // Exclude hidden files
212
  ),
213
  msgFilters = Seq(
214
    ".*warning.*not exhaustive.*".r  // Filter specific warning types
215
  ),
216
  maximumErrors = 25,
217
  log = log
218
)
219

220
// Monitor compilation progress
221
compiler.compile(inputs, cwd, customReporter, progress)(log)
222

223
// Detailed result analysis
224
println(s"Compilation completed:")
225
println(s"  Errors: ${customReporter.hasErrors}")
226
println(s"  Warnings: ${customReporter.hasWarnings}")
227
println(s"  Total problems: ${customReporter.problems.length}")
228

229
// Reset for next compilation
230
customReporter.reset()
231
```
232

233
## Configuration Integration
234

235
### Console Options
236

237
The logging system integrates with the configuration system through `ConsoleOptions`:
238

239
```scala { .api }
240
case class ConsoleOptions(
241
  logLevel: Level.Value,            // Logging level
242
  color: Boolean,                   // Colored output
243
  logPhases: Boolean,               // Log compilation phases
244
  printProgress: Boolean,           // Print progress
245
  heartbeatSecs: Int,               // Heartbeat interval
246
  fileFilters: Seq[Regex],          // File filters for warnings
247
  msgFilters: Seq[Regex]            // Message filters for warnings
248
)
249
```
250

251
### Integration with Settings
252

253
```scala
254
import org.pantsbuild.zinc._
255

256
// Parse settings with logging configuration
257
val settings = Settings.parse(args.toSeq).get
258

259
// Extract console options
260
val consoleOpts = settings.consoleLog
261

262
// Create logger from settings
263
val log = Loggers.create(
264
  level = consoleOpts.logLevel,
265
  color = consoleOpts.color,
266
  captureLog = settings.captureLog
267
)
268

269
// Create reporter from settings  
270
val reporter = Reporters.create(
271
  log = log,
272
  fileFilters = consoleOpts.fileFilters,
273
  msgFilters = consoleOpts.msgFilters
274
)
275

276
// Create progress from settings
277
val progress = new SimpleCompileProgress(
278
  logPhases = consoleOpts.logPhases,
279
  printProgress = consoleOpts.printProgress,
280
  heartbeatSecs = consoleOpts.heartbeatSecs
281
)(log)
282
```
283

284
## Types
285

286
```scala { .api }
287
// Logging levels
288
object Level extends Enumeration {
289
  val Debug, Info, Warn, Error = Value
290
}
291

292
// Console output destinations
293
sealed trait ConsoleOut
294
object ConsoleOut {
295
  case object SystemOut extends ConsoleOut
296
  case object SystemErr extends ConsoleOut
297
}
298
```