|
| 1 | +/* |
| 2 | + * Copyright (c) 2024 Touchlab |
| 3 | + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. |
| 4 | + * You may obtain a copy of the License at |
| 5 | + * |
| 6 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 7 | + * |
| 8 | + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| 9 | + */ |
| 10 | + |
| 11 | +package co.touchlab.kermit.io |
| 12 | + |
| 13 | +import co.touchlab.kermit.* |
| 14 | +import kotlinx.coroutines.* |
| 15 | +import kotlinx.coroutines.channels.Channel |
| 16 | +import kotlinx.coroutines.channels.trySendBlocking |
| 17 | +import kotlinx.datetime.Clock |
| 18 | +import kotlinx.datetime.format |
| 19 | +import kotlinx.datetime.format.DateTimeComponents |
| 20 | +import kotlinx.io.* |
| 21 | +import kotlinx.io.files.FileSystem |
| 22 | +import kotlinx.io.files.Path |
| 23 | +import kotlinx.io.files.SystemFileSystem |
| 24 | + |
| 25 | +/** |
| 26 | + * Implements a log writer that writes log messages to a rolling file. |
| 27 | + * |
| 28 | + * It also deletes old log files when the maximum number of log files is reached. We simply keep |
| 29 | + * approximately [RollingFileLogWriterConfig.rollOnSize] bytes in each log file, |
| 30 | + * and delete the oldest file when we have more than [RollingFileLogWriterConfig.maxLogFiles]. |
| 31 | + * |
| 32 | + * Formatting is governed by the passed [MessageStringFormatter], but we do prepend a timestamp by default. |
| 33 | + * Turn this off via [RollingFileLogWriterConfig.prependTimestamp] |
| 34 | + * |
| 35 | + * Writes to the file are done by a different coroutine. The main reason for this is to make writes to the |
| 36 | + * log file sink thread-safe, and so that file rolling can be performed without additional synchronization |
| 37 | + * or locking. The channel that buffers log messages is currently unbuffered, so logging threads will block |
| 38 | + * until the I/O is complete. However, buffering could easily be introduced to potentially increase logging |
| 39 | + * throughput. The envisioned usage scenarios for this class probably do not warrant this. |
| 40 | + * |
| 41 | + * The recommended way to obtain the logPath on Android is: |
| 42 | + * |
| 43 | + * ```kotlin |
| 44 | + * Path(context.filesDir.path) |
| 45 | + * ``` |
| 46 | + * |
| 47 | + * and on iOS this wil return the application's sandboxed document directory: |
| 48 | + * |
| 49 | + * ```kotlin |
| 50 | + * (NSFileManager.defaultManager.URLsForDirectory(NSDocumentDirectory, NSUserDomainMask).last() as NSURL).path!! |
| 51 | + * ``` |
| 52 | + * |
| 53 | + * However, you can use any path that is writable by the application. This would generally be implemented by |
| 54 | + * platform-specific code. |
| 55 | + */ |
| 56 | +open class RollingFileLogWriter( |
| 57 | + private val config: RollingFileLogWriterConfig, |
| 58 | + private val messageStringFormatter: MessageStringFormatter = DefaultFormatter, |
| 59 | + private val clock: Clock = Clock.System, |
| 60 | + private val fileSystem: FileSystem = SystemFileSystem, |
| 61 | +) : LogWriter() { |
| 62 | + @OptIn(DelicateCoroutinesApi::class, ExperimentalCoroutinesApi::class) |
| 63 | + private val coroutineScope = CoroutineScope( |
| 64 | + newSingleThreadContext("RollingFileLogWriter") + |
| 65 | + SupervisorJob() + |
| 66 | + CoroutineName("RollingFileLogWriter") + |
| 67 | + CoroutineExceptionHandler { _, throwable -> |
| 68 | + // can't log it, we're the logger -- print to standard error |
| 69 | + println("RollingFileLogWriter: Uncaught exception in writer coroutine") |
| 70 | + throwable.printStackTrace() |
| 71 | + } |
| 72 | + ) |
| 73 | + |
| 74 | + private val loggingChannel: Channel<Buffer> = Channel() |
| 75 | + |
| 76 | + init { |
| 77 | + coroutineScope.launch { |
| 78 | + writer() |
| 79 | + } |
| 80 | + } |
| 81 | + |
| 82 | + override fun log(severity: Severity, message: String, tag: String, throwable: Throwable?) { |
| 83 | + bufferLog( |
| 84 | + formatMessage( |
| 85 | + severity = severity, |
| 86 | + tag = Tag(tag), |
| 87 | + message = Message(message) |
| 88 | + ), throwable |
| 89 | + ) |
| 90 | + } |
| 91 | + |
| 92 | + private fun bufferLog(message: String, throwable: Throwable?) { |
| 93 | + val log = buildString { |
| 94 | + append(clock.now().format(DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET)) |
| 95 | + append(" ") |
| 96 | + appendLine(message) |
| 97 | + if (throwable != null) { |
| 98 | + appendLine(throwable.stackTraceToString()) |
| 99 | + } |
| 100 | + } |
| 101 | + loggingChannel.trySendBlocking(Buffer().apply { writeString(log) }) |
| 102 | + } |
| 103 | + |
| 104 | + private fun formatMessage(severity: Severity, tag: Tag?, message: Message): String = |
| 105 | + messageStringFormatter.formatMessage(severity, if (config.logTag) tag else null, message) |
| 106 | + |
| 107 | + private fun maybeRollLogs(size: Long): Boolean { |
| 108 | + return if (size > config.rollOnSize) { |
| 109 | + rollLogs() |
| 110 | + true |
| 111 | + } else false |
| 112 | + } |
| 113 | + |
| 114 | + private fun rollLogs() { |
| 115 | + if (fileSystem.exists(pathForLogIndex(config.maxLogFiles - 1))) { |
| 116 | + fileSystem.delete(pathForLogIndex(config.maxLogFiles - 1)) |
| 117 | + } |
| 118 | + (0..<(config.maxLogFiles - 1)).reversed().forEach { |
| 119 | + val sourcePath = pathForLogIndex(it) |
| 120 | + val targetPath = pathForLogIndex(it + 1) |
| 121 | + if (fileSystem.exists(sourcePath)) { |
| 122 | + try { |
| 123 | + fileSystem.atomicMove(sourcePath, targetPath) |
| 124 | + } catch (e: IOException) { |
| 125 | + // we can't log it, we're the logger -- print to standard error |
| 126 | + println("RollingFileLogWriter: Failed to roll log file $sourcePath to $targetPath (sourcePath exists=${fileSystem.exists(sourcePath)})") |
| 127 | + e.printStackTrace() |
| 128 | + } |
| 129 | + } |
| 130 | + } |
| 131 | + } |
| 132 | + |
| 133 | + private fun pathForLogIndex(index: Int): Path = |
| 134 | + Path(config.logFilePath, if (index == 0) "${config.logFileName}.log" else "${config.logFileName}-$index.log") |
| 135 | + |
| 136 | + private suspend fun writer() { |
| 137 | + val logFilePath = pathForLogIndex(0) |
| 138 | + |
| 139 | + if (fileSystem.exists(logFilePath)) { |
| 140 | + maybeRollLogs(fileSizeOrZero(logFilePath)) |
| 141 | + } |
| 142 | + |
| 143 | + fun createNewLogSink(): Sink = fileSystem |
| 144 | + .sink(logFilePath, append = true) |
| 145 | + .buffered() |
| 146 | + |
| 147 | + var currentLogSink: Sink = createNewLogSink() |
| 148 | + |
| 149 | + while (currentCoroutineContext().isActive) { |
| 150 | + // wait for data to be available, flush periodically |
| 151 | + val result = loggingChannel.receiveCatching() |
| 152 | + |
| 153 | + // check if logs need rolling |
| 154 | + val rolled = maybeRollLogs(fileSizeOrZero(logFilePath)) |
| 155 | + if (rolled) { |
| 156 | + currentLogSink.close() |
| 157 | + currentLogSink = createNewLogSink() |
| 158 | + } |
| 159 | + |
| 160 | + result.getOrNull()?.transferTo(currentLogSink) |
| 161 | + |
| 162 | + // we could improve performance by flushing less frequently at the cost of potential data loss, |
| 163 | + // but this is a safe default |
| 164 | + currentLogSink.flush() |
| 165 | + } |
| 166 | + } |
| 167 | + |
| 168 | + private fun fileSizeOrZero(path: Path) = fileSystem.metadataOrNull(path)?.size ?: 0 |
| 169 | +} |
0 commit comments