Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions QUICKSTART.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ scouterctl capture --object-hash 123456 --date 20261107 \

중단되거나 일부만 저장됐으면 같은 명령에 `--resume`을 붙여 재개합니다. 서비스명·SQL·오류 원문을 저장하려는 경우에만 캡처할 때 `--include-text`를 추가하세요. 민감한 애플리케이션 정보가 포함될 수 있습니다. 자세한 사용법은 [캡처와 오프라인 분석(영문)](docs/captures.md)에 있습니다.

Windows에서는 일시적인 파일 교체 거부를 짧게 재시도합니다. 로컬 파일 오류가 계속되면 캡처를 사용하는 프로그램을 닫고 권한과 디스크 여유 공간을 확인하세요. 정상적으로 저장된 manifest가 있을 때만 재개하고, 없으면 실패한 디렉터리를 보존한 뒤 새 경로로 캡처합니다. 자세한 절차는 [캡처 복구 안내(영문)](docs/capture-recovery.md)를 참고하세요.

## 4. Collector 없이 분석

```sh
Expand Down
2 changes: 2 additions & 0 deletions QUICKSTART.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ The capture result reports `storageDateVerification: "unverified"`. Check the su

Repeat the same command with `--resume` after interruption or partial completion. Add `--include-text` at capture time only if you intend to store potentially sensitive service names, SQL and error text. See [capture and offline analysis](docs/captures.md).

Windows briefly retries temporary file replacement denial. If a local file error persists, close programs using the capture and check permissions and free disk space. Resume only when a valid committed manifest exists; otherwise preserve the failed directory and choose a new destination. See [capture recovery](docs/capture-recovery.md).

## 4. Inspect without a Collector

```sh
Expand Down
6 changes: 6 additions & 0 deletions docs/capture-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ A closed transport can report `IO_ERROR` (exit 10), whereas a refused connection

Pages that were already committed are validated before resume. An incomplete page is fetched again, including profiles already read but not committed. Temporary files not referenced by the manifest are not evidence. Repeating resume on a complete capture preserves its data.

## Local file failures on Windows

Windows can deny an atomic file replacement while another program holds the destination open. The CLI briefly retries access-denied replacements, preserving the committed file and the atomic replacement operation. Persistent denial still returns `IO_ERROR` (exit 10); other filesystem failures are not retried. An access-denied error can also mean insufficient permissions.

The message distinguishes local file I/O from Collector transport I/O. Close programs using the capture and check its path, permissions and available disk space. If the directory contains a valid committed manifest, rerun the original command with `--resume` after correcting the cause. If the first manifest could not be committed, preserve that directory and start a new capture in an unused directory. Do not promote a `.partial` file to a manifest or remove referenced pages to force recovery.

## Recovery limits

Recovery preserves the records available in the fixed query window and the committed capture. It cannot recover telemetry that an agent or Collector lost during an outage, expired retention, deleted databases, or sampled requests. `executionComplete` does not certify complete upstream traffic; `upstreamCoverage` and `sampling` remain `unknown`.
Expand Down
2 changes: 2 additions & 0 deletions docs/cli-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ The example message is illustrative. `error.code` is the machine-readable identi

A mid-response EOF currently maps to `IO_ERROR` (10), whereas socket exceptions/timeouts map to `CONNECTION_FAILED` (5). Exit 8 therefore needs both the exit status and the envelope: it can carry available data or describe a failure without data. Treat unrecognized nonzero exits as failures rather than guessing a known category.

Local file failures and Collector transport I/O have distinct human-readable messages while retaining `IO_ERROR` (10). Integrity errors retain their specific messages. See [capture recovery](capture-recovery.md) before retrying a failed file write; a `.partial` file is not a committed checkpoint.

## Streaming commands

`xlog search` uses `scouterctl.stream/v1` on its first `start` event:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ internal inline fun <T> collectorOperation(block: () -> T): T = try {
throw OperationFailure(ErrorCode.CONNECTION_FAILED,
"Collector connection failed; check --host, --port and TCP access")
} catch (_: IOException) {
throw OperationFailure(ErrorCode.IO_ERROR, "Transport or artifact I/O failed")
throw OperationFailure(ErrorCode.IO_ERROR, "Collector transport I/O failed; retry the query or check the Collector connection")
} catch (_: IllegalArgumentException) {
throw UnexpectedFailure(ErrorCode.INVALID_ARGUMENT, "Invalid argument or manifest")
} catch (_: java.time.DateTimeException) {
Expand Down
25 changes: 25 additions & 0 deletions src/main/kotlin/dev/scouterctl/adapters/files/AtomicReplacement.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
package dev.scouterctl.adapters.files

import java.nio.file.AccessDeniedException
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.StandardCopyOption.ATOMIC_MOVE
import java.nio.file.StandardCopyOption.REPLACE_EXISTING

internal fun replaceAtomically(partial: Path, target: Path) {
val attempts = if (System.getProperty("os.name").startsWith("Windows")) 5 else 1
repeat(attempts) { attempt ->
try {
Files.move(partial, target, ATOMIC_MOVE, REPLACE_EXISTING)
return
} catch (failure: AccessDeniedException) {
if (attempt == attempts - 1) throw failure
try {
Thread.sleep(50)
} catch (_: InterruptedException) {
Thread.currentThread().interrupt()
throw failure
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@ import dev.scouterctl.application.CaptureRepository
import dev.scouterctl.adapters.serialization.*
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.StandardCopyOption.ATOMIC_MOVE
import java.nio.file.StandardCopyOption.REPLACE_EXISTING
import java.security.MessageDigest

class CaptureStore(private val directory: Path) : CaptureRepository {
Expand Down Expand Up @@ -39,7 +37,7 @@ class CaptureStore(private val directory: Path) : CaptureRepository {
private fun atomicWrite(path: Path, content: String) {
val partial = path.resolveSibling(path.fileName.toString() + ".partial")
Files.writeString(partial, content)
Files.move(partial, path, ATOMIC_MOVE, REPLACE_EXISTING)
replaceAtomically(partial, path)
}
private fun digest(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256")
.digest(bytes).joinToString("") { "%02x".format(it) }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ import java.nio.channels.FileChannel
import java.nio.file.Files
import java.nio.file.NoSuchFileException
import java.nio.file.Path
import java.nio.file.StandardCopyOption.ATOMIC_MOVE
import java.nio.file.StandardCopyOption.REPLACE_EXISTING
import java.nio.file.StandardOpenOption.CREATE
import java.nio.file.StandardOpenOption.WRITE
import java.nio.file.attribute.PosixFilePermissions
Expand Down Expand Up @@ -44,7 +42,7 @@ class ContextStore(private val path: Path) : ContextRepository {
val temporary = Files.createTempFile(parent, ".scouterctl-", ".tmp", *attributes)
try {
Files.writeString(temporary, json.encodeToString(updated.toDto()) + "\n")
Files.move(temporary, path, ATOMIC_MOVE, REPLACE_EXISTING)
replaceAtomically(temporary, path)
} finally { Files.deleteIfExists(temporary) }
return@fileOperation updated
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ import java.nio.channels.OverlappingFileLockException
import java.nio.file.Files
import java.nio.file.LinkOption.NOFOLLOW_LINKS
import java.nio.file.Path
import java.nio.file.StandardCopyOption.ATOMIC_MOVE
import java.nio.file.StandardCopyOption.REPLACE_EXISTING
import java.nio.file.StandardOpenOption.*
import java.security.MessageDigest
import java.util.Locale
Expand Down Expand Up @@ -109,7 +107,7 @@ class CounterCaptureStore(private val directory: Path) : CounterCaptureRepositor
Files.newOutputStream(partial, CREATE, TRUNCATE_EXISTING, WRITE, NOFOLLOW_LINKS).use {
it.write(content.toByteArray(Charsets.UTF_8))
}
Files.move(partial, directory.resolve(name), ATOMIC_MOVE, REPLACE_EXISTING)
replaceAtomically(partial, directory.resolve(name))
}

private fun digest(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256").digest(bytes).joinToString("") { "%02x".format(Locale.ROOT, it) }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ import kotlinx.serialization.encodeToString
import java.nio.file.Files
import java.nio.file.LinkOption.NOFOLLOW_LINKS
import java.nio.file.Path
import java.nio.file.StandardCopyOption.ATOMIC_MOVE
import java.nio.file.StandardCopyOption.REPLACE_EXISTING
import java.security.MessageDigest

class EvidenceStore(private val directory: Path) : EvidenceRepository {
Expand Down Expand Up @@ -89,7 +87,7 @@ class EvidenceStore(private val directory: Path) : EvidenceRepository {
java.nio.file.StandardOpenOption.TRUNCATE_EXISTING, java.nio.file.StandardOpenOption.WRITE).use {
it.write(content.toByteArray(Charsets.UTF_8))
}
Files.move(partial, directory.resolve(name), ATOMIC_MOVE, REPLACE_EXISTING)
replaceAtomically(partial, directory.resolve(name))
}

private fun digest(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ internal inline fun <T> fileOperation(block: () -> T): T = try {
} catch (error: OperationFailure) {
throw error
} catch (_: IOException) {
throw OperationFailure(ErrorCode.IO_ERROR, "Transport or artifact I/O failed")
throw OperationFailure(ErrorCode.IO_ERROR, "Local file I/O failed; check the path, permissions and available disk space")
} catch (_: IllegalArgumentException) {
throw UnexpectedFailure(ErrorCode.INVALID_ARGUMENT, "Invalid argument or manifest")
} catch (_: java.time.DateTimeException) {
Expand Down
62 changes: 62 additions & 0 deletions src/test/kotlin/dev/scouterctl/CaptureWriteTest.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
package dev.scouterctl

import com.sun.nio.file.ExtendedOpenOption.NOSHARE_DELETE
import dev.scouterctl.adapters.files.CaptureStore
import dev.scouterctl.adapters.files.EvidenceStore
import dev.scouterctl.core.ErrorCode
import dev.scouterctl.core.OperationFailure
import io.kotest.assertions.throwables.shouldThrow
import io.kotest.core.spec.style.FunSpec
import io.kotest.engine.spec.tempdir
import io.kotest.matchers.shouldBe
import java.nio.channels.FileChannel
import java.nio.file.Files
import java.nio.file.StandardOpenOption.READ
import java.nio.file.attribute.PosixFilePermissions

class CaptureWriteTest : FunSpec({
for (includeProfiles in listOf(false, true)) {
test("denied checkpoint replacement preserves committed bytes and identifies local I/O with include-profiles=$includeProfiles") {
val work = tempdir().toPath()
val directory = work.resolve("capture")
val cli = ContractCli(work)
WireFixture().use { server ->
val args = listOf("capture", "--directory", directory.toString()) + evidenceWindow +
if (includeProfiles) listOf("--include-profiles") else emptyList()
cli.run(server, args).exit shouldBe 0
}
val manifest = directory.resolve("manifest.json")
val partial = directory.resolve("manifest.json.partial")
val before = Files.readString(manifest)
Files.writeString(partial, "prior partial")
val save: () -> Unit = if (includeProfiles) {
val store = EvidenceStore(directory)
val next = store.load().copy(executionComplete = false)
val write = { store.save(next) }
write
} else {
val store = CaptureStore(directory)
val next = store.load().copy(executionComplete = false)
val write = { store.save(next) }
write
}
val checkFailure = {
val failure = shouldThrow<OperationFailure> { save() }
failure.code shouldBe ErrorCode.IO_ERROR
failure.message shouldBe "Local file I/O failed; check the path, permissions and available disk space"
Files.readString(manifest) shouldBe before
Files.exists(partial) shouldBe true
}
if (System.getProperty("os.name").startsWith("Windows")) {
FileChannel.open(manifest, READ, NOSHARE_DELETE).use { checkFailure() }
} else {
val permissions = Files.getPosixFilePermissions(directory)
Files.setPosixFilePermissions(directory, PosixFilePermissions.fromString("r-x------"))
try { checkFailure() } finally { Files.setPosixFilePermissions(directory, permissions) }
}
save()
Files.exists(partial) shouldBe false
Files.readString(manifest).contains("\"executionComplete\":false") shouldBe true
}
}
})
1 change: 1 addition & 0 deletions src/test/kotlin/dev/scouterctl/ConnectionDiagnostic.kt
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ internal fun connectionDiagnostic(exit: Int?, elapsedMs: Long, output: String, s
"Collector timeout; check TCP access and --timeout-ms; upstream cancellation is not guaranteed" -> "socket_timeout"
"Collector connection failed; check --host, --port and TCP access" -> "socket_failure"
"Transport or artifact I/O failed" -> "transport_or_artifact_io"
"Collector transport I/O failed; retry the query or check the Collector connection" -> "collector_transport_io"
else -> "unclassified"
}
return buildJsonObject {
Expand Down
4 changes: 3 additions & 1 deletion src/test/kotlin/dev/scouterctl/ConnectionDiagnosticTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,9 @@ class ConnectionDiagnosticTest : FunSpec({
val result = ContractCli(tempdir().toPath()).run(server, profile)
result.exit shouldBe 10
val diagnostic = requireNotNull(result.diagnostic)
diagnostic["error"]!!.jsonObject["reason"] shouldBe JsonPrimitive("transport_or_artifact_io")
result.events.single()["error"]!!.jsonObject["message"] shouldBe
JsonPrimitive("Collector transport I/O failed; retry the query or check the Collector connection")
diagnostic["error"]!!.jsonObject["reason"] shouldBe JsonPrimitive("collector_transport_io")
diagnostic["fixture"]!!.jsonObject["command"] shouldBe JsonPrimitive("dictionary")
diagnostic.toString() shouldNotContain "secret-token"
diagnostic.toString() shouldNotContain "private-address"
Expand Down
40 changes: 40 additions & 0 deletions src/test/kotlin/dev/scouterctl/WindowsAtomicReplacementTest.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
package dev.scouterctl

import com.sun.nio.file.ExtendedOpenOption.NOSHARE_DELETE
import dev.scouterctl.adapters.files.replaceAtomically
import io.kotest.core.spec.style.FunSpec
import io.kotest.engine.spec.tempdir
import io.kotest.matchers.shouldBe
import java.io.IOException
import java.nio.channels.FileChannel
import java.nio.file.Files
import java.nio.file.StandardOpenOption.READ
import java.util.concurrent.CompletableFuture
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit.MILLISECONDS
import java.util.concurrent.TimeUnit.SECONDS

class WindowsAtomicReplacementTest : FunSpec({
if (System.getProperty("os.name").startsWith("Windows")) {
test("replacement succeeds after a temporary Windows handle releases the committed file") {
val work = tempdir().toPath()
val target = Files.writeString(work.resolve("manifest.json"), "committed")
val partial = Files.writeString(work.resolve("manifest.json.partial"), "replacement")
val released = CompletableFuture<Unit>()

FileChannel.open(target, READ, NOSHARE_DELETE).use { held ->
Executors.newSingleThreadScheduledExecutor().use { scheduler ->
scheduler.schedule({
try { held.close(); released.complete(Unit) }
catch (failure: IOException) { released.completeExceptionally(failure) }
}, 100, MILLISECONDS)
replaceAtomically(partial, target)
released.get(5, SECONDS)
}
}

Files.readString(target) shouldBe "replacement"
Files.exists(partial) shouldBe false
}
}
})
Loading