001package io.jstach.rainbowgum; 002 003import java.lang.System.Logger.Level; 004import java.time.Instant; 005import java.util.ArrayList; 006import java.util.Arrays; 007import java.util.Collection; 008import java.util.EnumSet; 009import java.util.List; 010import java.util.Locale; 011import java.util.Objects; 012import java.util.Set; 013import java.util.concurrent.atomic.AtomicBoolean; 014import java.util.concurrent.atomic.AtomicLong; 015import java.util.concurrent.locks.ReentrantLock; 016 017import org.jspecify.annotations.NonNull; 018import org.jspecify.annotations.Nullable; 019 020import io.jstach.rainbowgum.annotation.CaseChanging; 021 022/** 023 * Appenders are guaranteed to be written synchronously much like an actor in actor 024 * concurrency. They safely hold onto and communicate with the encoder and output. 025 * Appenders largely deal with correct locking, buffer reuse and flushing. 026 * {@linkplain LogAppender.AppenderFlag Flags } can be set to control the behavior the 027 * appenders and publishers can request different appender behavior through the flags. 028 * 029 * @see LogAppender.AppenderFlag 030 * @apiNote because appenders require complicated implementation and to guarantee 031 * integrity the implementations are encapsulated (sealed). 032 */ 033public sealed interface LogAppender extends LogLifecycle { 034 035 /** 036 * Default Console appender name. 037 */ 038 static final String CONSOLE_APPENDER_NAME = "console"; 039 040 /** 041 * Removes the current thread's encoding buffers from every appender of the globally 042 * bound {@link RainbowGum}, so a pooled thread does not keep a buffer it may never 043 * use again. Only {@link AppenderType#LOCK_THREAD_LOCAL_BUFFER} and 044 * {@link AppenderType#SYNCHRONIZED_THREAD_LOCAL_BUFFER} appenders keep per thread 045 * buffers; the next event the thread logs simply creates a new one. Does nothing if 046 * no Rainbow Gum is bound. Logging context such as MDC is cleared separately with 047 * {@link LogEventFactory.KeyValuesContributor#clear()}. 048 * {@snippet : 049 * LogAppender.clearThreadLocals(); 050 * KeyValuesContributor.global().clear(); 051 * } 052 */ 053 public static void clearThreadLocals() { 054 var gum = RainbowGumHolder.peek(); 055 if (gum == null) { 056 return; 057 } 058 for (var appender : gum.config().serviceRegistry().find(LogAppender.class)) { 059 InternalLogAppender.of(appender).clearThreadLocals(); 060 } 061 } 062 063 /** 064 * Default output file appender name. 065 */ 066 static final String FILE_APPENDER_NAME = "file"; 067 068 /** 069 * Output appender property. 070 */ 071 static final String APPENDER_OUTPUT_PROPERTY = LogProperties.APPENDER_OUTPUT_PROPERTY; 072 073 /** 074 * Encoder appender property. 075 */ 076 static final String APPENDER_ENCODER_PROPERTY = LogProperties.APPENDER_ENCODER_PROPERTY; 077 078 /** 079 * Appender flags. A list of flags (usually comma separated). 080 * @see AppenderFlag 081 */ 082 static final String APPENDER_FLAGS_PROPERTY = LogProperties.APPENDER_FLAGS_PROPERTY; 083 084 /** 085 * Appender type. 086 * @see AppenderType 087 */ 088 static final String APPENDER_TYPE_PROPERTY = LogProperties.APPENDER_TYPE_PROPERTY; 089 090 /** 091 * Batch of events. <strong>DO NOT MODIFY THE ARRAY</strong>. Do not use the 092 * <code>length</code> of the passed in array but instead use <code>count</code> 093 * parameter. 094 * @param events an array guaranteed to be smaller than count. 095 * @param count the number of items. 096 */ 097 public void append(LogEvent[] events, int count); 098 099 /** 100 * Appends a single event. 101 * @param event event. 102 */ 103 public void append(LogEvent event); 104 105 /** 106 * Boolean like flags for appender that can be set with 107 * {@link LogAppender#APPENDER_FLAGS_PROPERTY}. Unlike {@link AppenderType} more than 108 * one flag can be set at once. 109 */ 110 @CaseChanging 111 public enum AppenderFlag { 112 113 /** 114 * By default the appender will call flush on each item appended or if in async 115 * batch mode for each batch. This flag disables that behavior so that flushing is 116 * left up to the output (or an external mechanism) instead. 117 */ 118 DISABLE_IMMEDIATE_FLUSH, 119 /** 120 * The appender will drop events on reentry which happens if an appender during 121 * its append causes recursive appending in the same thread. This is an analog to 122 * what 123 * <a href="https://logback.qos.ch/manual/appenders.html#AppenderBase">Logback 124 * does by default</a>. Detection uses the appender's lock or monitor. Appenders 125 * that reuse a thread local buffer also detect reentry during encoding. 126 * {@link AppenderType#LOCK_NEW_BUFFER} only detects reentry while writing under 127 * its lock. <strong>Dropping is not enabled by default.</strong> 128 * <p> 129 * This flag is to allow outputs that do logging themselves. For performance 130 * reasons and to allow async publishers it is recommended that you fix the output 131 * code such that it does not do logging. This flag is ignored if 132 * {@link #REENTRY_LOG} is set. 133 * <p> 134 * <strong>This flag will not fix outputs causing lool like logging if an async 135 * publisher is used!</strong> That is why it is recommended you fix the output by 136 * dropping events that would cause infinite loop like logging. 137 * @see #REENTRY_LOG 138 */ 139 REENTRY_DROP, 140 /** 141 * The appender will log events as errors to std error on reentry which happens if 142 * an appender during its append causes recursive appending in the same thread. 143 * This is an analog to what 144 * <a href="https://logback.qos.ch/manual/appenders.html#AppenderBase">Logback 145 * does by default</a>. Detection is the same as {@link #REENTRY_DROP} and is not 146 * enabled by default. This flag is to resolve failures of outputs that then do 147 * logging. 148 * <p> 149 * This flag takes precedence over {@link #REENTRY_DROP}. 150 */ 151 REENTRY_LOG; 152 153 static Set<AppenderFlag> parse(Collection<String> value) { 154 if (value.isEmpty()) { 155 return EnumSet.noneOf(AppenderFlag.class); 156 } 157 var s = EnumSet.noneOf(AppenderFlag.class); 158 for (var v : value) { 159 s.add(parse(v)); 160 } 161 return s; 162 } 163 164 static AppenderFlag parse(String value) { 165 return LogProperty.enumValue(AppenderFlag.class, value); 166 } 167 168 } 169 170 /** 171 * The buffer/locking strategy an appender uses. Unlike {@link AppenderFlag} exactly 172 * one is in effect for a given appender - set on the {@link LogAppender.Builder} (or 173 * via {@link LogAppender#APPENDER_TYPE_PROPERTY}) at construction time and fixed for 174 * the appender's lifetime; a publisher cannot change it afterward. 175 */ 176 @CaseChanging 177 public enum AppenderType { 178 179 /** 180 * The appender will create a single buffer that will be reused and will be 181 * protected by the appenders locking. 182 */ 183 REUSE_BUFFER, 184 /** 185 * The appender will give each thread its own reusable buffer (a 186 * {@link ThreadLocal}) instead of allocating a new buffer per event. Encoding is 187 * done <strong>outside</strong> the appender's lock (the thread's buffer is only 188 * visited by that thread so no protection is needed while encoding) with the lock 189 * only held for the final write to the output. 190 * <p> 191 * The same {@link ThreadLocal} buffer is used regardless of whether the calling 192 * thread is a platform or virtual thread. A virtual thread's entry becomes 193 * collectible once the thread itself terminates, and a typical unit of work (e.g. 194 * one HTTP request) logs several times on the same thread, so reusing the buffer 195 * across those calls still pays off even for short-lived virtual threads. 196 * <p> 197 * This is the default type - see {@link #SYNCHRONIZED_THREAD_LOCAL_BUFFER} for 198 * the alternative lock-kind opt-in. 199 */ 200 LOCK_THREAD_LOCAL_BUFFER, 201 /** 202 * Like {@link #LOCK_THREAD_LOCAL_BUFFER} (a reused per-thread buffer, encoding 203 * done outside any lock) except the final write to the output is protected by a 204 * plain {@code synchronized} block (the JVM's intrinsic monitor) instead of a 205 * {@link ReentrantLock}. 206 * <p> 207 * The Java language has no way to acquire a monitor in one method call and 208 * release it in another, so this appender's critical sections are written as 209 * literal {@code synchronized} blocks rather than going through a shared lock 210 * abstraction the way {@link #LOCK_THREAD_LOCAL_BUFFER} does. 211 * {@link AppenderFlag#REENTRY_DROP} and {@link AppenderFlag#REENTRY_LOG} are 212 * still honored though - {@link Thread#holdsLock(Object)} is the 213 * {@code synchronized} equivalent of {@code ReentrantLock}'s 214 * {@code isHeldByCurrentThread()}, so reentrancy is detected the same way. 215 * <p> 216 * Motivated by Log4j2's own garbage-free appenders using {@code synchronized} 217 * rather than a {@code java.util.concurrent} lock around their buffer-transfer 218 * step, and confirmed by real-workload benchmarking to outperform 219 * {@link ReentrantLock} under platform-thread contention - this was the default 220 * for a time. Real-workload benchmarking under virtual threads found the 221 * opposite, a large and reproducible loss versus {@link ReentrantLock} for 222 * reasons not fully understood (classic JEP 491 pinning was checked and ruled 223 * out), so {@link #LOCK_THREAD_LOCAL_BUFFER} is the default now and this type is 224 * an opt-in for platform-thread-heavy deployments that want the edge. 225 * <p> 226 * {@link LogConfig.Globals#appenderLock()} decides whether this type is honored: 227 * {@link LogConfig.Globals.AppenderLock#REENTRANT}, and the default 228 * {@link LogConfig.Globals.AppenderLock#AUTO} before JDK 24 (where 229 * {@code synchronized} pins a virtual thread's carrier, see 230 * <a href="https://openjdk.org/jeps/491">JEP 491</a>), turn it into 231 * {@link #LOCK_THREAD_LOCAL_BUFFER}. 232 */ 233 SYNCHRONIZED_THREAD_LOCAL_BUFFER, 234 /** 235 * Like {@link #LOCK_THREAD_LOCAL_BUFFER} (encoding done outside the lock, the 236 * lock only guards the final write to the output) except the buffer is allocated 237 * fresh for every single event instead of being cached in a {@link ThreadLocal}. 238 * <p> 239 * For deployments that want a hard guarantee of never using {@link ThreadLocal} 240 * anywhere in the logging path - {@link #REUSE_BUFFER} is the existing 241 * no-{@code ThreadLocal} option, but it holds its lock across the entire 242 * encode-then-write critical section (the single shared buffer must stay 243 * protected for as long as anything is writing into it), so it pays for that 244 * guarantee with lock contention proportional to encoding cost, not just I/O 245 * cost. This type keeps {@link #LOCK_THREAD_LOCAL_BUFFER}'s low-contention shape 246 * (encode into a buffer nothing else can see, lock only for the write) while 247 * dropping the {@link ThreadLocal} - the buffer is simply a local variable, not 248 * cached anywhere, so nothing needs to be evicted or leaked-if-forgotten either. 249 * The tradeoff is a fresh buffer allocation (and whatever it grows to internally) 250 * on every single event instead of amortizing that allocation across a thread's 251 * whole lifetime. 252 * @apiNote not the default - {@link #LOCK_THREAD_LOCAL_BUFFER}'s reused buffer is 253 * the better choice unless avoiding {@link ThreadLocal} entirely is a hard 254 * requirement, not just a preference. 255 */ 256 LOCK_NEW_BUFFER, 257 /* 258 * Real-workload benchmarking under virtual threads found 259 * SYNCHRONIZED_THREAD_LOCAL_BUFFER and LOCK_THREAD_LOCAL_BUFFER each winning by a 260 * real, repeatable, double-digit-percentage margin on their own platform (native 261 * image, HotSpot respectively) and losing by a comparable margin on the other - a 262 * genuine cross-over, not just a shrinking gap, so no single fixed choice serves 263 * both well. Matters most for something distributed as more than one build of the 264 * same artifact for the same deployment - a native executable and a plain jar, 265 * say - where picking correctly per build would otherwise mean either shipping 266 * different configuration for each or sniffing the platform in application code. 267 * Detection is the same org.graalvm.nativeimage.imagecode system property check 268 * every native-image-aware framework uses to avoid a hard dependency on GraalVM's 269 * own SDK. 270 */ 271 /** 272 * Picks whichever concrete type actually performs best for the platform this 273 * process is currently running on, decided once, at appender construction time, 274 * not re-checked afterward. <strong>Currently</strong> that means 275 * {@link #SYNCHRONIZED_THREAD_LOCAL_BUFFER} when running as a GraalVM native 276 * image, or {@link #LOCK_THREAD_LOCAL_BUFFER} otherwise - but that specific 277 * mapping is an implementation detail of this heuristic, not a contract. The 278 * whole point of this type is to track whichever choice is actually best, so 279 * which concrete type a given platform resolves to today may change in a future 280 * release without notice, as benchmarking improves or platforms evolve. 281 * <strong>If your deployment needs a specific type to always be used, pick that 282 * type explicitly instead of relying on what {@code AUTO_DETECT} happens to 283 * resolve to right now.</strong> 284 * <p> 285 * <strong>Not the default</strong> - requires explicitly requesting this type, 286 * programmatically or via {@link LogAppender#APPENDER_TYPE_PROPERTY}. Downgraded 287 * the same as an explicit request for whichever type it currently resolves to 288 * would be: by {@link LogConfig.Globals#appenderLock()} and 289 * {@link LogConfig.Globals#threadLocal()}. 290 */ 291 AUTO_DETECT; 292 293 static AppenderType parse(String value) { 294 return LogProperty.enumValue(AppenderType.class, value); 295 } 296 297 } 298 299 /** 300 * Creates a builder. 301 * @param name appender name. 302 * @return builder. 303 */ 304 public static Builder builder(String name) { 305 /* 306 * Eagerly triggers LogProperties' own key-parameter-value validation now, 307 * matching every annotation-processor-generated Builder's own constructor, which 308 * does the same via its own eager interpolateKey call: needed because this 309 * hand-written Builder can otherwise skip every keyed property lookup entirely 310 * when every field is set explicitly, never validating the name at all. Wrapped 311 * into a ValidationException the same way a generated builder's constructor is, 312 * so a bad name reports the same exception type regardless of whether it came 313 * from logging.appenders (LogAppenderRegistry's own validateNames call) or a 314 * direct programmatic builder(name) call like this one. 315 */ 316 try { 317 LogProperties.interpolateNamedKey(LogProperties.APPENDER_PREFIX, name); 318 } 319 catch (IllegalArgumentException e) { 320 throw LogProperty.ValidationException.of(LogAppender.class, e); 321 } 322 return new Builder(name); 323 } 324 325 /** 326 * Builder for creating standard appenders. Whatever is not set explicitly is resolved 327 * from properties keyed under {@link LogProperties#APPENDER_PREFIX} for this 328 * builder's name (see {@link #fromProperties(LogProperties)}), and failing that from 329 * a small set of defaults: no encoder resolves one from the output's own type, no 330 * flags means none are set, and no appender type means 331 * {@link AppenderType#LOCK_THREAD_LOCAL_BUFFER} - or {@link AppenderType#AUTO_DETECT} 332 * instead, if {@link LogProperties#GLOBAL_OPTIMIZE_PROPERTY} is enabled. There is 333 * deliberately no such default for output, since a required source is not something a 334 * generic named appender can safely guess, except for the well known 335 * {@code "console"}/ {@code "file"} names, which register their own fallback via 336 * {@link #outputDefault(LogProvider)}. 337 */ 338 public static final class Builder implements LogBuilder<Builder, LogAppender> { 339 340 private @Nullable LogProvider<? extends LogOutput> output = null; 341 342 /* 343 * A weaker fallback than an explicit output(...) call: consulted only if neither 344 * that nor APPENDER_OUTPUT_PROPERTY resolves anything. Package-private, not part 345 * of the public Builder API: DefaultAppenderRegistry is the only caller, for 346 * "console"'s stdout default, where the precedence is deliberately the opposite 347 * of an ordinary explicit value (the property is meant to override this default, 348 * not the other way around). 349 */ 350 private @Nullable LogProvider<? extends LogOutput> outputDefault = null; 351 352 private @Nullable LogProvider<? extends LogEncoder> encoder = null; 353 354 private @Nullable EnumSet<AppenderFlag> flags = null; 355 356 private @Nullable AppenderType appenderType = null; 357 358 private final String name; 359 360 private Builder(String name) { 361 this.name = name; 362 } 363 364 Builder outputDefault(LogProvider<? extends LogOutput> outputDefault) { 365 this.outputDefault = outputDefault; 366 return this; 367 } 368 369 /** 370 * Name of the appender. 371 * @return name. 372 */ 373 public String name() { 374 return this.name; 375 } 376 377 /** 378 * Sets output. 379 * @param output output. 380 * @return builder. 381 */ 382 public Builder output(LogProvider<? extends LogOutput> output) { 383 this.output = output; 384 return this; 385 } 386 387 /** 388 * Sets output. 389 * @param output output. 390 * @return builder. 391 */ 392 public Builder output(LogOutput output) { 393 this.output = LogProvider.of(output); 394 return this; 395 } 396 397 /** 398 * Sets formatter as encoder. 399 * @param formatter formatter to be converted to encoder. 400 * @return builder. 401 * @see LogEncoder#of(LogFormatter) 402 */ 403 public Builder formatter(LogFormatter formatter) { 404 this.encoder = LogEncoder.of(formatter); 405 return this; 406 } 407 408 /** 409 * Sets formatter as encoder. 410 * @param formatter formatter to be converted to encoder. 411 * @return builder. 412 * @see LogEncoder#of(LogFormatter) 413 */ 414 public Builder formatter(LogFormatter.EventFormatter formatter) { 415 this.encoder = LogEncoder.of(formatter); 416 return this; 417 } 418 419 /** 420 * Sets encoder. 421 * @param encoder encoder not <code>null</code>. 422 * @return builder. 423 */ 424 public Builder encoder(LogProvider<? extends LogEncoder> encoder) { 425 this.encoder = encoder; 426 return this; 427 } 428 429 /** 430 * Sets encoder. 431 * @param encoder encoder not <code>null</code>. 432 * @return builder. 433 */ 434 public Builder encoder(LogEncoder encoder) { 435 this.encoder = LogProvider.of(encoder); 436 return this; 437 } 438 439 /** 440 * Sets appender flags. 441 * @param flags flags will replace all flags currently set. 442 * @return this. 443 */ 444 public Builder flags(Collection<AppenderFlag> flags) { 445 _flags().addAll(flags); 446 return this; 447 } 448 449 private EnumSet<AppenderFlag> _flags() { 450 EnumSet<AppenderFlag> flags = this.flags; 451 if (flags == null) { 452 this.flags = flags = EnumSet.noneOf(AppenderFlag.class); 453 } 454 return flags; 455 } 456 457 /** 458 * Adds a flag. 459 * @param flag flag. 460 * @return this. 461 */ 462 public Builder flag(AppenderFlag flag) { 463 _flags().add(flag); 464 return this; 465 } 466 467 /** 468 * Sets the appender type (buffer/locking strategy). If not set it is resolved 469 * from {@link LogAppender#APPENDER_TYPE_PROPERTY} or otherwise defaults to 470 * {@link AppenderType#LOCK_THREAD_LOCAL_BUFFER} ({@link AppenderType#AUTO_DETECT} 471 * instead if {@link LogProperties#GLOBAL_OPTIMIZE_PROPERTY} is enabled). Calling 472 * this method always wins over both. 473 * @param appenderType appender type. 474 * @return this. 475 */ 476 public Builder appenderType(AppenderType appenderType) { 477 this.appenderType = appenderType; 478 return this; 479 } 480 481 @Override 482 public String propertyPrefix() { 483 return LogProperties.APPENDER_PREFIX; 484 } 485 486 /** 487 * Fills in whatever of flags/appender type is not already explicitly set on this 488 * builder from properties keyed under {@link #propertyPrefix()} for this 489 * builder's name; an already-set field always wins over the property, matching 490 * every other generated builder's {@code fromProperties} in this project. Both 491 * are resolved and validated together against one {@link LogProperty.Validator}, 492 * so a builder with both malformed reports both in a single exception rather than 493 * just the first one reached. 494 * <p> 495 * Output/encoder are deliberately not handled here even though they too are keyed 496 * under {@link #propertyPrefix()}: turning either into a concrete, registered 497 * {@link LogOutput}/{@link LogEncoder} needs a {@link LogConfig} (to actually 498 * look up the URI scheme), which this method does not have. {@link #build()} 499 * resolves those two once a real {@link LogConfig} is available, using the same 500 * property keys. 501 * @param properties properties to resolve unset fields from. 502 * @return this. 503 */ 504 @Override 505 public Builder fromProperties(LogProperties properties) { 506 /* 507 * Register every result with the validator first, and only call validate(), 508 * which throws one aggregate exception up front if anything registered is 509 * Missing (when added via add(...)) or an Error (either method), before 510 * extracting any individual value below. Extracting a value via 511 * value()/valueOrNull() throws immediately for a still-unhandled Error (see 512 * LogProperty.Result.Error's own valueOrNull()), which would otherwise let 513 * the first bad property escape unwrapped before the Validator ever got a 514 * chance to collect the rest: the same ordering the annotation processor 515 * generates for every other builder in this project. 516 */ 517 var validator = LogProperty.Validator.of(LogAppender.class); 518 var flagsResult = flags == null ? properties.forKey(APPENDER_FLAGS_PROPERTY, name) 519 .ofList() 520 .map(AppenderFlag::parse) 521 .validateIfError(validator) : null; 522 var appenderTypeResult = appenderType == null ? properties.forKey(APPENDER_TYPE_PROPERTY, name) 523 .ofString() 524 .map(AppenderType::parse) 525 .validateIfError(validator) : null; 526 validator.validate(); 527 if (flagsResult != null) { 528 var resolved = flagsResult.valueOrNull(); 529 // AppenderFlag.parse always returns an EnumSet (empty or not), so 530 // EnumSet.copyOf is always safe here, never the "non-EnumSet and empty" 531 // case it rejects. 532 if (resolved != null) { 533 flags = EnumSet.copyOf(resolved); 534 } 535 } 536 if (appenderTypeResult != null) { 537 appenderType = appenderTypeResult.valueOrNull(); 538 } 539 return this; 540 } 541 542 /** 543 * Builds. 544 * @return an appender factory. 545 */ 546 public LogProvider<LogAppender> build() { 547 /* 548 * We need to capture parameters since appender creation needs to be lazy, and 549 * a copy is made below (rather than mutating this builder's own fields) so a 550 * shared/reused Builder instance is never mutated by a later 551 * fromProperties(...) call the lazy lambda makes once a real LogConfig is 552 * available. 553 */ 554 var _name = name; 555 var _output = output; 556 var _outputDefault = outputDefault; 557 var _encoder = encoder; 558 var _flags = flags; 559 var _appenderType = appenderType; 560 /* 561 * TODO should we use the parent name for resolution? 562 */ 563 return (n, config) -> { 564 var b = new Builder(_name); 565 b.flags = _flags; 566 b.appenderType = _appenderType; 567 b.fromProperties(config.properties()); 568 569 LogOutput output = LogProvider.provideOrNull(_output, _name, config); 570 if (output == null) { 571 /* 572 * A malformed (not just missing) property must throw here, 573 * immediately, regardless of whether a default exists below: e.g. 574 * "console" with a genuinely bad logging.appender.console.output.uri 575 * must fail loudly, not silently fall back to stdout. Only the 576 * Missing case falls through to outputDefault. 577 */ 578 output = switch (outputProperty(_name, config)) { 579 case LogProperty.Result.Success<LogOutput> s -> s.value(); 580 case LogProperty.Result.Missing<LogOutput> m -> null; 581 case LogProperty.Result.Error<LogOutput> e -> e.value(); 582 }; 583 } 584 if (output == null) { 585 output = LogProvider.provideOrNull(_outputDefault, _name, config); 586 } 587 if (output == null) { 588 /* 589 * No explicit value, no property, no default: the same missing 590 * -property failure a required property with no fallback produces 591 * anywhere else. Re-deriving the same (definitely still Missing) 592 * result and calling value() throws it unwrapped, no Validator 593 * involved, same as before this refactor. 594 */ 595 output = DefaultAppenderRegistry.rawValue(outputProperty(_name, config)).value(); 596 } 597 598 try { 599 return build(b, _name, output, _encoder, config); 600 } 601 catch (RuntimeException | Error e) { 602 /* 603 * The appender would have owned the output, so nothing else will 604 * close it, and an open file cannot be deleted on Windows. 605 */ 606 closeAfterFailure(output, e); 607 throw e; 608 } 609 }; 610 } 611 612 private static LogAppender build(Builder b, String name, LogOutput output, 613 @Nullable LogProvider<? extends LogEncoder> encoderProvider, LogConfig config) { 614 LogEncoder explicitEncoder = encoderProvider != null 615 ? LogProvider.provideOrNull(encoderProvider, name, config) : null; 616 LogEncoder encoder; 617 if (output instanceof LogOutput.ProvidesEncoder pe 618 && pe.policy() == LogOutput.ProvidesEncoder.Policy.MANDATORY) { 619 boolean propertyWired = !(encoderProperty(name, config) instanceof LogProperty.Result.Missing); 620 if (explicitEncoder != null || propertyWired) { 621 throw LogProperty.ValidationException 622 .of(LogAppender.class, new IllegalArgumentException("Appender '" + name + "' output " 623 + output.getClass().getName() 624 + " provides a mandatory encoder and does not allow another encoder to be configured.")); 625 } 626 encoder = pe.encoder(name, config); 627 } 628 else { 629 encoder = explicitEncoder; 630 if (encoder == null) { 631 var propertyResult = encoderProperty(name, config); 632 if (output instanceof LogOutput.ProvidesEncoder pe 633 && propertyResult instanceof LogProperty.Result.Missing) { 634 encoder = pe.encoder(name, config); 635 } 636 else { 637 encoder = DefaultAppenderRegistry.rawValue(propertyResult.or(() -> config.encoderRegistry() 638 .encoderForOutputType(output.type()) 639 .provide(name, config))).value(); 640 } 641 } 642 } 643 644 Set<AppenderFlag> flags = b.flags != null ? b.flags : EnumSet.noneOf(AppenderFlag.class); 645 AppenderType appenderType = b.appenderType != null ? b.appenderType 646 : config.globals().optimize() ? AppenderType.AUTO_DETECT : AppenderType.LOCK_THREAD_LOCAL_BUFFER; 647 648 return DirectLogAppender.of(name, output, encoder, appenderType, flags, config); 649 } 650 651 @SuppressWarnings("ReferenceEquality") // Self-suppression is based on identity. 652 static void closeAfterFailure(AutoCloseable resource, Throwable failure) { 653 try { 654 resource.close(); 655 } 656 catch (Exception | Error e) { 657 if (e != failure) { 658 failure.addSuppressed(e); 659 } 660 } 661 } 662 663 /* 664 * Resolves APPENDER_OUTPUT_PROPERTY all the way to a concrete LogOutput (not just 665 * a LogProvider), via LogProperty.provideValue so a failure inside the provided 666 * LogOutput's own construction (its own separate property tree, e.g. 667 * logging.appender.file.output.file.bufferSize) is not relabeled 668 * "Error converting property" as if APPENDER_OUTPUT_PROPERTY's own value had 669 * failed to convert - see LogProperty#providingError. Moved here since output 670 * resolution is now entirely this Builder's concern. 671 */ 672 private static LogProperty.Result<LogOutput> outputProperty(String name, LogConfig config) { 673 return LogProperty.provideValue( 674 config.properties().forKey(APPENDER_OUTPUT_PROPERTY, name).ofProvider(LogOutput::of), name, config); 675 } 676 677 private static LogProperty.Result<LogEncoder> encoderProperty(String name, LogConfig config) { 678 return LogProperty.provideValue( 679 config.properties().forKey(APPENDER_ENCODER_PROPERTY, name).ofProvider(LogEncoder::of), name, 680 config); 681 } 682 683 } 684 685 /** 686 * Provides appenders safely to the publisher. The providing calls of 687 * <code>asXXX</code> can only be called once as they register the appenders. 688 */ 689 final class Appenders { 690 691 private final AtomicBoolean created = new AtomicBoolean(); 692 693 private final String name; 694 695 private final LogConfig config; 696 697 private final List<LogProvider<LogAppender>> appenders; 698 699 /* 700 * Set once, inside asList()/asSingle(), so LogReporter can find out what a 701 * publisher was actually given without asking the publisher itself (which would 702 * mean every current and future publisher implementation cooperating): see 703 * resolvedOrNull(). Not re-derivable by calling asList()/asSingle() again: both 704 * are one-shot (see the created guard above). 705 */ 706 private @Nullable List<? extends LogAppender> resolved; 707 708 Appenders(String name, LogConfig config, List<LogProvider<LogAppender>> appenders) { 709 super(); 710 this.name = name; 711 this.config = config; 712 this.appenders = appenders; 713 } 714 715 /** 716 * Return the appenders as a list. 717 * @return list of appenders. 718 * @throws IllegalStateException if appenders are already registered. 719 */ 720 public List<? extends LogAppender> asList() throws IllegalStateException { 721 if (created.compareAndSet(false, true)) { 722 var apps = appenders(); 723 List<LogAppender> appenders = new ArrayList<>(); 724 for (var a : apps) { 725 appenders.add(register(a)); 726 } 727 resolved = appenders; 728 return appenders; 729 } 730 else { 731 throw new IllegalStateException("Appenders already provided."); 732 } 733 734 } 735 736 /** 737 * Consolidate the appenders as a single appender, appended synchronously. If more 738 * than one appender is combined, each keeps its own independent lock and is 739 * appended to directly - see {@link CompositeLogAppender}. 740 * @return single appender. 741 * @throws IllegalStateException if appenders are already registered. 742 */ 743 public LogAppender asSingle() throws IllegalStateException { 744 if (created.compareAndSet(false, true)) { 745 var apps = appenders(); 746 var appender = composite(apps); 747 resolved = List.of(appender); 748 return register(appender); 749 } 750 else { 751 throw new IllegalStateException("Appenders already provided."); 752 } 753 } 754 755 /** 756 * The appenders actually resolved by whichever of {@link #asList()}/ 757 * {@link #asSingle()} a publisher factory called, or <code>null</code> if neither 758 * has been called yet (a publisher factory that never calls either one has no 759 * real appenders to report on regardless). 760 * @return resolved appenders, or <code>null</code>. 761 */ 762 @Nullable List<? extends LogAppender> resolvedOrNull() { 763 return resolved; 764 } 765 766 private LogAppender register(LogAppender appender) { 767 return switch (appender) { 768 case DirectLogAppender ia -> { 769 config.serviceRegistry().put(LogAppender.class, name + "." + ia.name(), ia); 770 yield ia; 771 } 772 case CompositeLogAppender ca -> { 773 config.serviceRegistry().put(LogAppender.class, name, ca); 774 yield ca; 775 } 776 default -> { 777 throw new IllegalStateException(); 778 } 779 }; 780 } 781 782 private List<LogAppender> appenders() { 783 LogProvider<List<LogAppender>> all = (n, c) -> { 784 List<LogAppender> list = new ArrayList<>(); 785 try { 786 for (var p : appenders) { 787 list.add(p.provide(n, c)); 788 } 789 } 790 catch (RuntimeException | Error e) { 791 /* 792 * The route never gets the appenders already made, so close their 793 * outputs. 794 */ 795 for (var a : list) { 796 Builder.closeAfterFailure(a, e); 797 } 798 throw e; 799 } 800 return list; 801 }; 802 return all.describe(n -> "Appenders for route: '" + n + "'").provide(name, config); 803 } 804 805 /** 806 * Creates a composite log appender from many, each keeping its own independent 807 * lock. 808 * @param appenders appenders. 809 * @return appender. 810 */ 811 private static LogAppender composite(List<? extends LogAppender> appenders) { 812 if (appenders.isEmpty()) { 813 throw new IllegalArgumentException("A single appender is required"); 814 } 815 if (appenders.size() == 1) { 816 return Objects.requireNonNull(appenders.get(0)); 817 } 818 return CompositeLogAppender.of(appenders); 819 } 820 821 } 822 823 @Override 824 public void close(); 825 826} 827 828interface AppenderVisitor { 829 830 boolean consume(DirectLogAppender appender); 831 832} 833 834/** 835 * This is a JAVADOC BUG 836 */ 837sealed interface InternalLogAppender extends LogAppender, Actor { 838 839 static InternalLogAppender of(LogAppender appender) { 840 return Objects.requireNonNull((InternalLogAppender) appender); // TODO eclipse 841 // bug. 842 } 843 844 /** 845 * An appender can act on actions. One of the key actions is reopening files. 846 * @param action action to run. 847 * @return alert events for anything that failed, empty if the action fully succeeded. 848 */ 849 @Override 850 public List<LogEvent> act(LogAction action); 851 852 /** 853 * Removes the current thread's thread local state, if any. Unlike {@link #act} this 854 * takes no lock since only the calling thread's state is touched. 855 */ 856 default void clearThreadLocals() { 857 } 858 859} 860 861sealed interface DirectLogAppender extends InternalLogAppender { 862 863 String name(); 864 865 LogOutput output(); 866 867 LogEncoder encoder(); 868 869 default List<LogEvent> _request(LogAction action) { 870 return switch (action) { 871 case LogAction.StandardAction a -> switch (a) { 872 case LogAction.StandardAction.REOPEN -> reopen(); 873 case LogAction.StandardAction.FLUSH -> flush(); 874 }; 875 }; 876 } 877 878 /** 879 * Reopens {@link #output()}. Any failure is reported to the alert system rather than 880 * thrown, at {@link Level#ERROR}. 881 * @return the alert event if reopening failed, empty if it succeeded. 882 */ 883 List<LogEvent> reopen(); 884 885 /** 886 * Flushes {@link #output()}. Any failure is reported to the alert system rather than 887 * thrown, at {@link Level#ERROR}. 888 * @return the alert event if flushing failed, empty if it succeeded. 889 */ 890 List<LogEvent> flush(); 891 892 static DirectLogAppender of(String name, LogOutput output, LogEncoder encoder, AppenderType type, 893 Set<LogAppender.AppenderFlag> flags, LogConfig config) { 894 var alerts = config.alerts(); 895 var metrics = config.metrics(); 896 var globals = config.globals(); 897 type = AbstractLogAppender.resolveAutoDetectAppenderType(type); 898 type = AbstractLogAppender.applyAppenderLock(type, globals.appenderLock(), Runtime.version().feature()); 899 type = AbstractLogAppender.guardThreadLocalAppenderType(type, 900 globals.threadLocal() == LogConfig.Globals.ThreadLocalMode.FORBID); 901 return switch (type) { 902 case REUSE_BUFFER -> 903 new ReuseBufferLogAppender(name, output, encoder, flags, new ReentrantLock(), alerts, metrics); 904 case SYNCHRONIZED_THREAD_LOCAL_BUFFER -> 905 new SynchronizedThreadLocalBufferLogAppender(name, output, encoder, flags, alerts, metrics); 906 case LOCK_THREAD_LOCAL_BUFFER -> new LockThreadLocalBufferLogAppender(name, output, encoder, flags, 907 new ReentrantLock(), alerts, metrics); 908 case LOCK_NEW_BUFFER -> 909 new LockNewBufferLogAppender(name, output, encoder, flags, new ReentrantLock(), alerts, metrics); 910 case AUTO_DETECT -> 911 throw new IllegalStateException("AUTO_DETECT should have already been resolved to a concrete type"); 912 }; 913 } 914 915} 916 917/** 918 * An abstract appender to help create custom appenders. 919 */ 920sealed abstract class AbstractLogAppender implements DirectLogAppender { 921 922 /** 923 * Applies {@link LogConfig.Globals#appenderLock()} to a resolved appender type, the 924 * enforcement point that makes the lock a guarantee rather than a changed default. 925 * Only the thread local buffer types have both a reentrant lock and a 926 * {@code synchronized} variant; other types are returned unchanged. 927 * @param type resolved appender type. 928 * @param lock appender lock. 929 * @param jdkFeature the running JDK's feature version, which decides 930 * {@link LogConfig.Globals.AppenderLock#AUTO}. 931 * @return the appender type to use. 932 */ 933 static LogAppender.AppenderType applyAppenderLock(LogAppender.AppenderType type, 934 LogConfig.Globals.AppenderLock lock, int jdkFeature) { 935 var effective = lock == LogConfig.Globals.AppenderLock.AUTO && jdkFeature < 24 936 ? LogConfig.Globals.AppenderLock.REENTRANT : lock; 937 return switch (effective) { 938 case AUTO -> type; 939 case REENTRANT -> type == LogAppender.AppenderType.SYNCHRONIZED_THREAD_LOCAL_BUFFER 940 ? LogAppender.AppenderType.LOCK_THREAD_LOCAL_BUFFER : type; 941 case SYNCHRONIZED -> type == LogAppender.AppenderType.LOCK_THREAD_LOCAL_BUFFER 942 ? LogAppender.AppenderType.SYNCHRONIZED_THREAD_LOCAL_BUFFER : type; 943 }; 944 } 945 946 /** 947 * Downgrades either {@link ThreadLocal}-backed type ( 948 * {@link LogAppender.AppenderType#LOCK_THREAD_LOCAL_BUFFER} or 949 * {@link LogAppender.AppenderType#SYNCHRONIZED_THREAD_LOCAL_BUFFER}) to 950 * {@link LogAppender.AppenderType#LOCK_NEW_BUFFER} if {@code forbid} is true - the 951 * enforcement point that makes the global no-{@link ThreadLocal} guarantee a real 952 * guarantee rather than just a changed default. An explicit 953 * {@link LogAppender.AppenderType#REUSE_BUFFER} request is left as-is - it is already 954 * {@link ThreadLocal}-free, so there is nothing to downgrade. 955 * @param type type as given to an appender factory method. 956 * @param forbid whether {@link LogConfig.Globals#threadLocal()} is 957 * {@link LogConfig.Globals.ThreadLocalMode#FORBID}. 958 * @return {@code type} unchanged, unless the guarantee is active and a 959 * {@link ThreadLocal}-backed type was requested, in which case 960 * {@code LOCK_NEW_BUFFER} instead. 961 */ 962 static LogAppender.AppenderType guardThreadLocalAppenderType(LogAppender.AppenderType type, boolean forbid) { 963 if (!forbid) { 964 return type; 965 } 966 return switch (type) { 967 case LOCK_THREAD_LOCAL_BUFFER, SYNCHRONIZED_THREAD_LOCAL_BUFFER -> LogAppender.AppenderType.LOCK_NEW_BUFFER; 968 case REUSE_BUFFER, LOCK_NEW_BUFFER -> type; 969 case AUTO_DETECT -> 970 throw new IllegalStateException("AUTO_DETECT should have already been resolved to a concrete type"); 971 }; 972 } 973 974 /** 975 * Resolves {@link LogAppender.AppenderType#AUTO_DETECT} to 976 * {@link LogAppender.AppenderType#SYNCHRONIZED_THREAD_LOCAL_BUFFER} or 977 * {@link LogAppender.AppenderType#LOCK_THREAD_LOCAL_BUFFER} depending on 978 * {@link #isNativeImageRuntime()}; any other type is returned unchanged. Called 979 * before 980 * {@link #applyAppenderLock(LogAppender.AppenderType, LogConfig.Globals.AppenderLock, int)} 981 * and {@link #guardThreadLocalAppenderType(LogAppender.AppenderType, boolean)} so a 982 * resolved {@code SYNCHRONIZED_THREAD_LOCAL_BUFFER} is still subject to both of those 983 * global guarantees the same as if it had been requested directly. 984 * @param type type as given to an appender factory method. 985 * @return {@code type} unchanged unless it was {@code AUTO_DETECT}. 986 */ 987 static LogAppender.AppenderType resolveAutoDetectAppenderType(LogAppender.AppenderType type) { 988 if (type != LogAppender.AppenderType.AUTO_DETECT) { 989 return type; 990 } 991 return isNativeImageRuntime() ? LogAppender.AppenderType.SYNCHRONIZED_THREAD_LOCAL_BUFFER 992 : LogAppender.AppenderType.LOCK_THREAD_LOCAL_BUFFER; 993 } 994 995 /** 996 * The system property GraalVM native-image itself sets to {@code buildtime} during 997 * the image build and {@code runtime} when the built image actually executes - absent 998 * entirely on a plain JVM. The standard, dependency-free way every native-image-aware 999 * framework checks "am I native" without a hard compile-time dependency on GraalVM's 1000 * own SDK just to ask this one question. 1001 */ 1002 static final String NATIVE_IMAGE_CODE_PROPERTY = "org.graalvm.nativeimage.imagecode"; 1003 1004 /** 1005 * Whether this process is currently running as an executing (not building) GraalVM 1006 * native image - see {@link #NATIVE_IMAGE_CODE_PROPERTY}. 1007 * @return true if running as a native image at runtime. 1008 */ 1009 static boolean isNativeImageRuntime() { 1010 return "runtime".equals(System.getProperty(NATIVE_IMAGE_CODE_PROPERTY)); 1011 } 1012 1013 /** 1014 * Records a failed append: always counted, alerted only when it starts an episode of 1015 * failures. 1016 * <p> 1017 * An Error is a failure like any other, because event data can raise one while it is 1018 * encoded, for example a throwable whose getMessage() overflows the stack. Letting it 1019 * escape would throw it at the caller of a synchronous route and stop the worker of 1020 * an asynchronous one for good. Only an error that leaves the JVM unusable is 1021 * rethrown. 1022 * @param e the failure. 1023 * @param count events that failed to append. 1024 * @param batch whether they were appended as a batch. 1025 */ 1026 final void appendFailed(Throwable e, int count, boolean batch) { 1027 if (e instanceof VirtualMachineError fatal && !(e instanceof StackOverflowError)) { 1028 throw fatal; 1029 } 1030 metrics.errorCounter(LogMetrics.EVENTS_FAILED_METRIC, count); 1031 long previous = failureCount.getAndUpdate(value -> value < 0 ? 0 : value + count); 1032 if (previous < 0) { 1033 alerts.error(getClass(), batch ? "appender '" + name + "' failed to append batch of " + count + " event(s)" 1034 : "appender '" + name + "' failed to append event", e); 1035 } 1036 } 1037 1038 /** 1039 * Ends an episode of failures, if one is under way, with one warning saying how many 1040 * further events failed without being reported. 1041 */ 1042 final void appendSucceeded() { 1043 if (failureCount.get() < 0) { 1044 return; 1045 } 1046 long count = failureCount.getAndSet(-1); 1047 if (count >= 0) { 1048 alerts.warn(getClass(), "appender '" + name + "' recovered; " + count 1049 + " more event(s) failed to append after the reported failure"); 1050 } 1051 } 1052 1053 /** 1054 * Whether an appender should drop (or drop-and-log) an append call because it is 1055 * reentrant - i.e. the current thread is already inside a previous call to the same 1056 * appender, which happens if an output does logging itself during its own write or an 1057 * argument's {@code toString()} logs while the event is encoded. Shared by every 1058 * appender that can detect reentrancy, regardless of whether it does so via a 1059 * {@link ReentrantLock} ( {@code lock.isHeldByCurrentThread()}) or a 1060 * {@code synchronized} block ( {@link Thread#holdsLock(Object)}) - callers pass in 1061 * whichever check applies to them. Whenever this returns {@code true}, 1062 * {@link LogMetrics#EVENTS_DROPPED_METRIC} is incremented by {@code count} regardless 1063 * of whether {@link AppenderFlag#REENTRY_LOG} is set - counting and logging/alerting 1064 * are separate concerns, so the count still happens even when the drop itself is 1065 * silent. 1066 * @param reentrant whether the current thread already holds this appender's 1067 * lock/monitor or is using its thread's buffer. 1068 * @param flags the appender's flags. 1069 * @param metrics where to record {@link LogMetrics#EVENTS_DROPPED_METRIC} if events 1070 * are dropped. 1071 * @param count number of events that would be dropped - {@code 1} for a single event 1072 * append, or the batch size for a batch append. 1073 * @return {@code true} if the caller should drop the event(s) without appending. 1074 */ 1075 static boolean shouldDropForReentry(boolean reentrant, Set<LogAppender.AppenderFlag> flags, LogMetrics metrics, 1076 int count) { 1077 if (!reentrant) { 1078 return false; 1079 } 1080 if (flags.contains(LogAppender.AppenderFlag.REENTRY_LOG)) { 1081 Exception exception = new Exception("reentrant appender"); 1082 MetaLog.error(LogAppender.class, exception); 1083 metrics.errorCounter(LogMetrics.EVENTS_DROPPED_METRIC, count); 1084 return true; 1085 } 1086 if (flags.contains(LogAppender.AppenderFlag.REENTRY_DROP)) { 1087 metrics.errorCounter(LogMetrics.EVENTS_DROPPED_METRIC, count); 1088 return true; 1089 } 1090 return false; 1091 } 1092 1093 /** 1094 * name. 1095 */ 1096 protected final String name; 1097 1098 /** 1099 * output 1100 */ 1101 protected final LogOutput output; 1102 1103 /** 1104 * encoder 1105 */ 1106 protected final LogEncoder encoder; 1107 1108 protected final Set<LogAppender.AppenderFlag> flags; 1109 1110 protected final boolean immediateFlush; 1111 1112 /** 1113 * alerts for reporting encode/write failures that this appender catches so they never 1114 * propagate back to whatever application thread called logger.info(...). 1115 */ 1116 protected final LogAlerts alerts; 1117 1118 /** 1119 * metrics for recording counters like {@link LogMetrics#EVENTS_DROPPED_METRIC}. 1120 */ 1121 protected final LogMetrics metrics; 1122 1123 /* 1124 * A failing output usually fails every append until something outside the process 1125 * changes, so only the first failure of an episode is alerted: printing one stack 1126 * trace per log call only widens the damage. Every failure is still counted. 1127 */ 1128 // Negative means healthy; otherwise count failures after the first alert. 1129 private final AtomicLong failureCount = new AtomicLong(-1); 1130 1131 /** 1132 * Creates an appender from an output and encoder. 1133 * @param output set the output field and will be started and closed with the 1134 * appender. 1135 * @param encoder set the encoder field. 1136 * @param alerts alerts for reporting encode/write failures. 1137 * @param metrics metrics for recording counters. 1138 */ 1139 protected AbstractLogAppender(String name, LogOutput output, LogEncoder encoder, 1140 Set<LogAppender.AppenderFlag> flags, LogAlerts alerts, LogMetrics metrics) { 1141 super(); 1142 this.name = name; 1143 this.output = output; 1144 this.encoder = encoder; 1145 this.flags = flags; 1146 this.immediateFlush = !flags.contains(LogAppender.AppenderFlag.DISABLE_IMMEDIATE_FLUSH); 1147 this.alerts = alerts; 1148 this.metrics = metrics; 1149 } 1150 1151 @Override 1152 public void start(LogConfig config) { 1153 output.start(config); 1154 } 1155 1156 @Override 1157 public void close() { 1158 output.close(); 1159 } 1160 1161 @Override 1162 public String toString() { 1163 return getClass().getName() + "[name=" + name + " encoder=" + encoder + ", " + "output=" + output + ", flags=" 1164 + flags + "]"; 1165 } 1166 1167 @Override 1168 public String name() { 1169 return this.name; 1170 } 1171 1172 @Override 1173 public LogOutput output() { 1174 return this.output; 1175 } 1176 1177 @Override 1178 public LogEncoder encoder() { 1179 return this.encoder; 1180 } 1181 1182 @Override 1183 public List<LogEvent> reopen() { 1184 metrics.infoCounter(LogMetrics.REOPEN_METRIC, 1); 1185 try { 1186 output.reopen(); 1187 return List.of(); 1188 } 1189 catch (Exception e) { 1190 metrics.errorCounter(LogMetrics.REOPEN_FAIL_METRIC, 1); 1191 var event = errorEvent(getClass(), "appender '" + name + "' failed to reopen output", e); 1192 alerts.alert(event); 1193 return List.of(event); 1194 } 1195 } 1196 1197 @Override 1198 public List<LogEvent> flush() { 1199 try { 1200 output.flush(); 1201 return List.of(); 1202 } 1203 catch (Exception e) { 1204 var event = errorEvent(getClass(), "appender '" + name + "' failed to flush output", e); 1205 alerts.alert(event); 1206 return List.of(event); 1207 } 1208 } 1209 1210 private static LogEvent errorEvent(Class<?> loggerName, String message, Throwable throwable) { 1211 var currentThread = Thread.currentThread(); 1212 return LogEvent.of(Instant.now(), currentThread.getName(), currentThread.threadId(), Level.ERROR, 1213 loggerName.getName(), message, KeyValues.of(), throwable); 1214 } 1215 1216} 1217 1218/** 1219 * Combines more than one appender on a route into one {@link LogAppender}. Each appender 1220 * keeps the independent lock it was already constructed with, and 1221 * {@link #append(LogEvent)}/{@link #append(LogEvent[], int)} skip locking at the 1222 * composite level entirely and append to every component directly - so e.g. a console 1223 * appender and a file appender under the same route never contend on the same lock for 1224 * unrelated I/O. {@link #start(LogConfig)}/{@link #close()}/{@link #act(LogAction)} do 1225 * the same - there is no composite-owned mutable state to protect, only a loop over 1226 * components that already handle their own synchronization where it matters. 1227 */ 1228@SuppressWarnings("ArrayRecordComponent") 1229record CompositeLogAppender(DirectLogAppender[] appenders) implements InternalLogAppender { 1230 1231 public static CompositeLogAppender of(List<? extends LogAppender> appenders) { 1232 @SuppressWarnings("null") // TODO Eclipse issue here 1233 DirectLogAppender @NonNull [] array = appenders.stream() 1234 .map(CompositeLogAppender::cast) 1235 .toArray(i -> new DirectLogAppender[i]); 1236 return new CompositeLogAppender(array); 1237 } 1238 1239 private static DirectLogAppender cast(LogAppender appender) { 1240 return (DirectLogAppender) appender; 1241 } 1242 1243 @Override 1244 public void append(LogEvent event) { 1245 for (var appender : appenders) { 1246 appender.append(event); 1247 } 1248 } 1249 1250 @Override 1251 public void append(LogEvent[] event, int count) { 1252 for (var appender : appenders) { 1253 appender.append(event, count); 1254 } 1255 } 1256 1257 @Override 1258 public void close() { 1259 for (var appender : appenders) { 1260 appender.close(); 1261 } 1262 } 1263 1264 @Override 1265 public void start(LogConfig config) { 1266 for (var appender : appenders) { 1267 appender.start(config); 1268 } 1269 } 1270 1271 @Override 1272 public List<LogEvent> act(LogAction action) { 1273 return Actor.act(appenders, action); 1274 } 1275 1276 @Override 1277 public void clearThreadLocals() { 1278 for (var appender : appenders) { 1279 appender.clearThreadLocals(); 1280 } 1281 } 1282 1283 @Override 1284 public String toString() { 1285 return getClass().getName() + "[appenders=" + Arrays.toString(appenders) + "]"; 1286 } 1287 1288} 1289 1290sealed abstract class LockLogAppender extends AbstractLogAppender implements InternalLogAppender { 1291 1292 protected final ReentrantLock lock; 1293 1294 public LockLogAppender(String name, LogOutput output, LogEncoder encoder, Set<LogAppender.AppenderFlag> flags, 1295 ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) { 1296 super(name, output, encoder, flags, alerts, metrics); 1297 this.lock = lock; 1298 } 1299 1300 @Override 1301 public List<LogEvent> act(LogAction action) { 1302 lock.lock(); 1303 try { 1304 return _request(action); 1305 } 1306 finally { 1307 lock.unlock(); 1308 } 1309 } 1310 1311 @Override 1312 public void close() { 1313 lock.lock(); 1314 try { 1315 super.close(); 1316 } 1317 finally { 1318 lock.unlock(); 1319 } 1320 } 1321 1322} 1323 1324/* 1325 * The idea here is to reuse the buffer trading lock contention for less GC. 1326 */ 1327final class ReuseBufferLogAppender extends LockLogAppender implements InternalLogAppender { 1328 1329 private final LogEncoder.Buffer buffer; 1330 1331 ReuseBufferLogAppender(String name, LogOutput output, LogEncoder encoder, Set<LogAppender.AppenderFlag> flags, 1332 ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) { 1333 super(name, output, encoder, flags, lock, alerts, metrics); 1334 this.buffer = encoder.buffer(output.bufferHints()); 1335 } 1336 1337 @Override 1338 public final void append(LogEvent event) { 1339 boolean reentrant = lock.isHeldByCurrentThread(); 1340 if (shouldDropForReentry(reentrant, flags, metrics, 1)) { 1341 return; 1342 } 1343 try { 1344 lock.lock(); 1345 try { 1346 // A reentrant call must not clear the buffer the outer event is in. 1347 var buffer = reentrant ? encoder.buffer(output.bufferHints()) : this.buffer; 1348 buffer.clear(); 1349 encoder.encode(event, buffer); 1350 output.write(event, buffer); 1351 if (immediateFlush) { 1352 output.flush(); 1353 } 1354 } 1355 finally { 1356 lock.unlock(); 1357 } 1358 appendSucceeded(); 1359 } 1360 catch (Throwable e) { 1361 appendFailed(e, 1, false); 1362 } 1363 } 1364 1365 @Override 1366 public void append(LogEvent[] events, int count) { 1367 boolean reentrant = lock.isHeldByCurrentThread(); 1368 if (shouldDropForReentry(reentrant, flags, metrics, count)) { 1369 return; 1370 } 1371 try { 1372 lock.lock(); 1373 try { 1374 output.write(events, count, encoder, reentrant ? encoder.buffer(output.bufferHints()) : this.buffer); 1375 if (immediateFlush) { 1376 output.flush(); 1377 } 1378 } 1379 finally { 1380 lock.unlock(); 1381 } 1382 if (count > 0) { 1383 appendSucceeded(); 1384 } 1385 } 1386 catch (Throwable e) { 1387 appendFailed(e, count, true); 1388 } 1389 } 1390 1391 @Override 1392 public void close() { 1393 lock.lock(); 1394 try { 1395 super.close(); 1396 buffer.close(); 1397 } 1398 finally { 1399 lock.unlock(); 1400 } 1401 } 1402 1403} 1404 1405/* 1406 * The idea here is to encode outside the lock. Instead of allocating a fresh buffer per 1407 * event or sharing (and thus serializing access to) a single buffer 1408 * (ReuseBufferLogAppender), each thread gets its own buffer that only it will ever touch, 1409 * so encoding never needs to be guarded by the lock at all - only the final write to the 1410 * output does. 1411 */ 1412final class LockThreadLocalBufferLogAppender extends LockLogAppender implements InternalLogAppender { 1413 1414 /* 1415 * There is no way to enumerate every thread's buffer to close it on appender close so 1416 * we rely on Buffer implementations not holding onto real resources (today they are 1417 * all just wrapped in-memory builders) and let the ThreadLocal itself (and 1418 * consequently the per-thread entries) become collectible once this appender is 1419 * discarded. 1420 */ 1421 // CheckerFramework's ThreadLocal stub declares T as inherently @Nullable since get() 1422 // can return null before initialValue() runs, but withInitial(...) below guarantees 1423 // it never does here. 1424 @SuppressWarnings("nullness:type.argument") 1425 private final ThreadLocal<ThreadBuffer> bufferThreadLocal; 1426 1427 LockThreadLocalBufferLogAppender(String name, LogOutput output, LogEncoder encoder, 1428 Set<LogAppender.AppenderFlag> flags, ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) { 1429 super(name, output, encoder, flags, lock, alerts, metrics); 1430 this.bufferThreadLocal = ThreadLocal.withInitial(() -> new ThreadBuffer(encoder.buffer(output.bufferHints()))); 1431 } 1432 1433 @Override 1434 public void clearThreadLocals() { 1435 bufferThreadLocal.remove(); 1436 } 1437 1438 @Override 1439 public final void append(LogEvent event) { 1440 try { 1441 var local = bufferThreadLocal.get(); 1442 /* 1443 * Encoding is outside the lock, so the lock alone misses a log call made 1444 * while this thread encodes, such as from an argument's toString(). 1445 */ 1446 boolean reentrant = local.inUse || lock.isHeldByCurrentThread(); 1447 if (shouldDropForReentry(reentrant, flags, metrics, 1)) { 1448 return; 1449 } 1450 try { 1451 var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire(); 1452 encoder.encode(event, buffer); 1453 writeLocked(event, buffer); 1454 } 1455 finally { 1456 if (!reentrant) { 1457 local.inUse = false; 1458 } 1459 } 1460 appendSucceeded(); 1461 } 1462 catch (Throwable e) { 1463 appendFailed(e, 1, false); 1464 } 1465 } 1466 1467 private void writeLocked(LogEvent event, LogEncoder.Buffer buffer) { 1468 lock.lock(); 1469 try { 1470 output.write(event, buffer); 1471 if (immediateFlush) { 1472 output.flush(); 1473 } 1474 } 1475 finally { 1476 lock.unlock(); 1477 } 1478 } 1479 1480 @Override 1481 public void append(LogEvent[] events, int count) { 1482 try { 1483 var local = bufferThreadLocal.get(); 1484 boolean reentrant = local.inUse || lock.isHeldByCurrentThread(); 1485 if (shouldDropForReentry(reentrant, flags, metrics, count)) { 1486 return; 1487 } 1488 try { 1489 var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire(); 1490 lock.lock(); 1491 try { 1492 output.write(events, count, encoder, buffer); 1493 if (immediateFlush) { 1494 output.flush(); 1495 } 1496 } 1497 finally { 1498 lock.unlock(); 1499 } 1500 } 1501 finally { 1502 if (!reentrant) { 1503 local.inUse = false; 1504 } 1505 } 1506 if (count > 0) { 1507 appendSucceeded(); 1508 } 1509 } 1510 catch (Throwable e) { 1511 appendFailed(e, count, true); 1512 } 1513 } 1514 1515} 1516 1517/* 1518 * A thread's reusable buffer for the thread local buffer appenders. inUse marks that the 1519 * thread is encoding or writing an event with it, so a log call made meanwhile gets a 1520 * fresh buffer instead of clearing this one. 1521 */ 1522final class ThreadBuffer { 1523 1524 final LogEncoder.Buffer buffer; 1525 1526 boolean inUse; 1527 1528 ThreadBuffer(LogEncoder.Buffer buffer) { 1529 this.buffer = buffer; 1530 } 1531 1532 LogEncoder.Buffer acquire() { 1533 inUse = true; 1534 buffer.clear(); 1535 return buffer; 1536 } 1537 1538} 1539 1540/* 1541 * Like LockThreadLocalBufferLogAppender (encode outside the lock, lock only the final 1542 * write) except the buffer is a fresh allocation per event instead of a ThreadLocal - for 1543 * deployments that want a hard guarantee of no ThreadLocal anywhere in the logging path 1544 * without paying ReuseBufferLogAppender's lock-across-the-whole-encode cost. 1545 */ 1546final class LockNewBufferLogAppender extends LockLogAppender implements InternalLogAppender { 1547 1548 LockNewBufferLogAppender(String name, LogOutput output, LogEncoder encoder, Set<LogAppender.AppenderFlag> flags, 1549 ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) { 1550 super(name, output, encoder, flags, lock, alerts, metrics); 1551 } 1552 1553 @Override 1554 public final void append(LogEvent event) { 1555 try { 1556 var buffer = encoder.buffer(output.bufferHints()); 1557 encoder.encode(event, buffer); 1558 if (writeLocked(event, buffer)) { 1559 appendSucceeded(); 1560 } 1561 } 1562 catch (Throwable e) { 1563 appendFailed(e, 1, false); 1564 } 1565 } 1566 1567 private boolean writeLocked(LogEvent event, LogEncoder.Buffer buffer) { 1568 if (shouldDropForReentry(lock.isHeldByCurrentThread(), flags, metrics, 1)) { 1569 return false; 1570 } 1571 lock.lock(); 1572 try { 1573 output.write(event, buffer); 1574 if (immediateFlush) { 1575 output.flush(); 1576 } 1577 } 1578 finally { 1579 lock.unlock(); 1580 } 1581 return true; 1582 } 1583 1584 @Override 1585 public void append(LogEvent[] events, int count) { 1586 if (shouldDropForReentry(lock.isHeldByCurrentThread(), flags, metrics, count)) { 1587 return; 1588 } 1589 try { 1590 var buffer = encoder.buffer(output.bufferHints()); 1591 lock.lock(); 1592 try { 1593 output.write(events, count, encoder, buffer); 1594 if (immediateFlush) { 1595 output.flush(); 1596 } 1597 } 1598 finally { 1599 lock.unlock(); 1600 } 1601 if (count > 0) { 1602 appendSucceeded(); 1603 } 1604 } 1605 catch (Throwable e) { 1606 appendFailed(e, count, true); 1607 } 1608 } 1609 1610} 1611 1612/* 1613 * Like LockThreadLocalBufferLogAppender (per-thread reused buffer, encode outside any 1614 * lock) but the final write is protected by a plain `synchronized` block on this 1615 * appender's own monitor instead of a ReentrantLock. Does not extend LockLogAppender - 1616 * there is no way to acquire a monitor in one method call and release it in another, so 1617 * this appender's critical sections are written as literal synchronized blocks instead. 1618 */ 1619final class SynchronizedThreadLocalBufferLogAppender extends AbstractLogAppender implements InternalLogAppender { 1620 1621 private final Object monitor = new Object(); 1622 1623 // See LockThreadLocalBufferLogAppender's identical field for why this suppression is 1624 // needed. 1625 @SuppressWarnings("nullness:type.argument") 1626 private final ThreadLocal<ThreadBuffer> bufferThreadLocal; 1627 1628 SynchronizedThreadLocalBufferLogAppender(String name, LogOutput output, LogEncoder encoder, 1629 Set<LogAppender.AppenderFlag> flags, LogAlerts alerts, LogMetrics metrics) { 1630 super(name, output, encoder, flags, alerts, metrics); 1631 this.bufferThreadLocal = ThreadLocal.withInitial(() -> new ThreadBuffer(encoder.buffer(output.bufferHints()))); 1632 } 1633 1634 @Override 1635 public void clearThreadLocals() { 1636 bufferThreadLocal.remove(); 1637 } 1638 1639 @Override 1640 public void append(LogEvent event) { 1641 try { 1642 var local = bufferThreadLocal.get(); 1643 // As LockThreadLocalBufferLogAppender: the monitor alone misses reentry while 1644 // encoding. 1645 boolean reentrant = local.inUse || Thread.holdsLock(monitor); 1646 if (shouldDropForReentry(reentrant, flags, metrics, 1)) { 1647 return; 1648 } 1649 try { 1650 var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire(); 1651 encoder.encode(event, buffer); 1652 writeSynchronized(event, buffer); 1653 } 1654 finally { 1655 if (!reentrant) { 1656 local.inUse = false; 1657 } 1658 } 1659 appendSucceeded(); 1660 } 1661 catch (Throwable e) { 1662 appendFailed(e, 1, false); 1663 } 1664 } 1665 1666 private void writeSynchronized(LogEvent event, LogEncoder.Buffer buffer) { 1667 synchronized (monitor) { 1668 output.write(event, buffer); 1669 if (immediateFlush) { 1670 output.flush(); 1671 } 1672 } 1673 } 1674 1675 @Override 1676 public void append(LogEvent[] events, int count) { 1677 try { 1678 var local = bufferThreadLocal.get(); 1679 boolean reentrant = local.inUse || Thread.holdsLock(monitor); 1680 if (shouldDropForReentry(reentrant, flags, metrics, count)) { 1681 return; 1682 } 1683 try { 1684 var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire(); 1685 synchronized (monitor) { 1686 output.write(events, count, encoder, buffer); 1687 if (immediateFlush) { 1688 output.flush(); 1689 } 1690 } 1691 } 1692 finally { 1693 if (!reentrant) { 1694 local.inUse = false; 1695 } 1696 } 1697 if (count > 0) { 1698 appendSucceeded(); 1699 } 1700 } 1701 catch (Throwable e) { 1702 appendFailed(e, count, true); 1703 } 1704 } 1705 1706 @Override 1707 public void close() { 1708 synchronized (monitor) { 1709 super.close(); 1710 } 1711 } 1712 1713 @Override 1714 public List<LogEvent> act(LogAction action) { 1715 synchronized (monitor) { 1716 return _request(action); 1717 } 1718 } 1719 1720}