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
4 changes: 2 additions & 2 deletions docs/captures.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ scouterctl capture \

Add `--include-text` to `xlog search` to resolve service names and error text without downloading profiles. Error text can contain sensitive values, including bound values or values from existing database rows.

The destination directory must not exist for a new capture. If the export is interrupted or partially completes, add `--resume` to the same capture command. Each query covers one date and one object over `[from,to)`. Set `--timezone` to the Collector's actual time zone.
For a new transaction capture, choose an unused destination under an existing parent directory. An occupied destination or a missing or invalid parent returns `INVALID_ARGUMENT` (exit 2). If the export is interrupted or partially completes, add `--resume` to the same capture command. Each query covers one date and one object over `[from,to)`. Set `--timezone` to the Collector's actual time zone.

The example saves profiles in a v3 bundle. Add `--include-text` to the capture command only when you intend to store potentially sensitive service, SQL and error text; the default page size is 25 and the maximum is 100. Resume v3 with the same flags and query. Existing v2 bundles remain readable but cannot be resumed by this version; see [Capture compatibility](capture-compatibility.md). Missing profiles are recorded and retried on resume; connection failures preserve earlier page checkpoints. See [Capture recovery](capture-recovery.md) for interruption handling and the limits of recovery.

Expand All @@ -45,7 +45,7 @@ scouterctl inspect --directory captures/incident-001 \
--txid 9223372036854775806
```

Use `--include-text` when the capture was created with stored text and you want to display it. Requesting text that was not stored returns `2`. Inspect verifies all referenced pages and returns `8` with data for partial captures or unavailable profiles. A missing transaction returns `7`; damaged files return `10`. It supports v2 and v3, with no implicit v1 migration.
Use `--include-text` when the capture was created with stored text and you want to display it. Requesting text that was not stored returns `2`. Inspect verifies all referenced pages and returns `8` with data for partial captures or unavailable profiles. A missing transaction returns `7`. A missing capture directory or a path to a file returns `INVALID_ARGUMENT` (exit 2). Damaged capture files return `10`. It supports v2 and v3, with no implicit v1 migration.

To find a transaction ID first, search the same bundle offline:

Expand Down
50 changes: 50 additions & 0 deletions src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
package dev.scouterctl.adapters.files

import dev.scouterctl.core.ErrorCode
import dev.scouterctl.core.OperationFailure
import java.nio.file.FileAlreadyExistsException
import java.nio.file.FileSystemException
import java.nio.file.Files
import java.nio.file.NoSuchFileException
import java.nio.file.NotDirectoryException
import java.nio.file.Path
import java.nio.file.attribute.BasicFileAttributes

private const val MISSING_PARENT = "Capture parent directory does not exist. Create it before starting a capture."

internal fun createCaptureDirectory(directory: Path): Unit = fileOperation {
directory.toAbsolutePath().parent?.let { parent ->
requireDirectory(parent, MISSING_PARENT, "Capture parent path is not a directory. Choose an existing parent directory.")
}

try {
Files.createDirectory(directory)
} catch (_: FileAlreadyExistsException) {
throw OperationFailure(
ErrorCode.INVALID_ARGUMENT,
"Capture destination already exists. Choose an unused path, or use --resume for a compatible capture."
)
} catch (_: NoSuchFileException) {
throw OperationFailure(ErrorCode.INVALID_ARGUMENT, MISSING_PARENT)
}
}

internal fun requireCaptureDirectory(directory: Path) = requireDirectory(
directory,
"Capture directory does not exist. Specify the path to an existing capture.",
"Capture path is not a directory. Specify the path to an existing capture."
)

private fun requireDirectory(path: Path, missing: String, invalid: String) {
val attributes = try {
Files.readAttributes(path, BasicFileAttributes::class.java)
} catch (_: NoSuchFileException) {
throw OperationFailure(ErrorCode.INVALID_ARGUMENT, missing)
} catch (_: NotDirectoryException) {
throw OperationFailure(ErrorCode.INVALID_ARGUMENT, invalid)
} catch (error: FileSystemException) {
path.toAbsolutePath().parent?.let { requireDirectory(it, missing, invalid) }
throw error
}
if (!attributes.isDirectory) throw OperationFailure(ErrorCode.INVALID_ARGUMENT, invalid)
}
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ import java.nio.file.StandardCopyOption.REPLACE_EXISTING
import java.security.MessageDigest

class CaptureStore(private val directory: Path) : CaptureRepository {
override fun create() = fileOperation { Files.createDirectory(directory); Unit }
override fun create() = createCaptureDirectory(directory)
override fun load(): CaptureManifest = fileOperation {
requireCaptureDirectory(directory)
val content = Files.readString(directory.resolve("manifest.json"))
requireCaptureSchema(content, "scouterctl.capture/v1")
json.decodeFromString<CaptureManifestDto>(content).toModel()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,10 @@ import java.nio.file.StandardCopyOption.REPLACE_EXISTING
import java.security.MessageDigest

class EvidenceStore(private val directory: Path) : EvidenceRepository {
override fun create(): Unit = fileOperation {
Files.createDirectory(directory)
}
override fun create() = createCaptureDirectory(directory)

override fun load(): EvidenceManifest = fileOperation {
requireCaptureDirectory(directory)
val content = read("manifest.json", 8_388_608)
requireCaptureSchema(content, "scouterctl.capture/v2", "scouterctl.capture/v3")
val manifest = json.decodeFromString<EvidenceManifestDto>(content).toModel()
Expand Down
74 changes: 74 additions & 0 deletions src/test/kotlin/dev/scouterctl/CapturePathTest.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
package dev.scouterctl

import io.kotest.core.spec.style.FunSpec
import io.kotest.engine.spec.tempdir
import io.kotest.matchers.shouldBe
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import java.nio.file.Files

class CapturePathTest : FunSpec({
test("inspect distinguishes missing and invalid paths from a damaged bundle") {
val work = tempdir().toPath()
Files.writeString(work.resolve("not-a-directory"), "ordinary file")
Files.createDirectory(work.resolve("empty-capture"))
val cli = ContractCli(work)
val inspect = listOf("inspect", "--txid", "1", "--directory")

cli.run(inspect + "missing-capture", password = null).shouldFailWith(
2, "INVALID_ARGUMENT", "Capture directory does not exist. Specify the path to an existing capture."
)
for (path in listOf("not-a-directory", "not-a-directory/child", "not-a-directory/child/grandchild")) {
cli.run(inspect + path, password = null).shouldFailWith(
2, "INVALID_ARGUMENT", "Capture path is not a directory. Specify the path to an existing capture."
)
}
cli.run(inspect + "empty-capture", password = null).shouldFailWith(
10, "IO_ERROR", "Capture integrity or record validation failed"
)
}

for (includeProfiles in listOf(false, true)) {
test("new capture reports occupied destinations and invalid parents with include-profiles=$includeProfiles") {
val work = tempdir().toPath()
val existing = Files.createDirectory(work.resolve("existing"))
val marker = Files.writeString(existing.resolve("marker"), "existing capture data")
val occupiedFile = Files.writeString(work.resolve("occupied-file"), "existing file")
val cli = ContractCli(work)
val args = listOf("capture") + evidenceWindow + if (includeProfiles) listOf("--include-profiles") else emptyList()
val occupied = "Capture destination already exists. Choose an unused path, or use --resume for a compatible capture."

WireFixture().use { server ->
cli.run(server, args + listOf("--directory", "existing")).shouldFailWith(2, "INVALID_ARGUMENT", occupied)
cli.run(server, args + listOf("--directory", "occupied-file")).shouldFailWith(2, "INVALID_ARGUMENT", occupied)
cli.run(server, args + listOf("--directory", "missing-parent/capture")).shouldFailWith(
2, "INVALID_ARGUMENT", "Capture parent directory does not exist. Create it before starting a capture."
)
for (parent in listOf("occupied-file", "occupied-file/child", "occupied-file/child/grandchild")) {
cli.run(server, args + listOf("--directory", "$parent/capture")).shouldFailWith(
2, "INVALID_ARGUMENT", "Capture parent path is not a directory. Choose an existing parent directory."
)
cli.run(server, args + listOf("--resume", "--directory", parent)).shouldFailWith(
2, "INVALID_ARGUMENT", "Capture path is not a directory. Specify the path to an existing capture."
)
}
cli.run(server, args + listOf("--resume", "--directory", "missing-capture")).shouldFailWith(
2, "INVALID_ARGUMENT", "Capture directory does not exist. Specify the path to an existing capture."
)
}

Files.list(existing).use { it.toList() } shouldBe listOf(marker)
Files.readString(marker) shouldBe "existing capture data"
Files.readString(occupiedFile) shouldBe "existing file"
Files.notExists(work.resolve("missing-parent")) shouldBe true
Files.notExists(work.resolve("missing-capture")) shouldBe true
}
}
})

private fun Outcome.shouldFailWith(expectedExit: Int, code: String, message: String) {
exit shouldBe expectedExit
val error = events.single().getValue("error").jsonObject
error.getValue("code").jsonPrimitive.content shouldBe code
error.getValue("message").jsonPrimitive.content shouldBe message
}
Loading