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
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ See [command and output examples](examples.md) for actual response shapes.
- [Capture formats and older files](capture-compatibility.md)
- [Interrupted capture recovery](capture-recovery.md)
- [Profile completeness](profile-completeness.md)
- [Collector time zone and query checks](collector-timezone.md)
- [Grouped profile SQL output](profile-sql-summary.md)
- [Security](../SECURITY.md)

Expand Down
2 changes: 2 additions & 0 deletions docs/cli-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,8 @@ A consumer should accept the stream schema, process records, then require both t

`storageDateVerification: "unverified"` means the CLI used the supplied XLog storage date without confirmation from the Collector. An incorrect date can produce an empty completed query. XLog `capture` reports the same field in its outer result envelope.

Online window queries reject offset mismatches against the reported Collector JVM zone before streaming or writing captures. `doctor` and `collector status` expose the property's ID and a client-rule offset with explicit provenance; unavailable metadata remains `null`. These checks do not verify the storage calendar. See [Collector time zones](collector-timezone.md).

`counter history` uses its own `scouterctl.counter-stream/v1` schema with the same start/record/complete lifecycle. Its start includes the dated target and counter metadata, and records contain stored timestamps and numeric strings. See [counter history](counter-history.md) for missing values, units and query limits.

`counter export` returns a single manifest result and writes JSONL chunk files. Its `scouterctl.counter-capture/v1` format is separate from XLog captures. See [resumable counter export](counter-export.md) for budgets, checkpoints and completion semantics.
Expand Down
40 changes: 40 additions & 0 deletions docs/collector-timezone.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Collector time zone

English | [한국어](ko/collector-timezone.md)

`doctor` and `collector status` report a `timezone` object alongside the existing `timezoneDisplayName`. For `collector status`, it is inside `data.collector`:

```json
{
"id": "Asia/Seoul",
"utcOffsetSeconds": 32400,
"referenceTimeEpochMs": 1793491200000,
"idSource": "jvm-property",
"offsetSource": "client-zone-rules"
}
```

The ID comes from the Collector's reported JVM `user.timezone` property through the existing authenticated `SERVER_ENV` request. Java short IDs, when recognized, are expanded using Java's short-ID mapping. The offset is calculated by the **CLI's time-zone rules** at the Collector's `SERVER_TIME` timestamp; it is not a remotely measured offset. `timezoneDisplayName` remains the localized login label and is not used to infer an ID. Other JVM environment values are not included in output.

If the property is missing or cannot be parsed, `timezone` is `null`. No CLI-host zone or display-name guess is substituted. Invalid protocol types fail as protocol errors without printing their values. A configured property can differ from a runtime default changed after startup, and Collector/CLI time-zone database versions can differ; read the provenance before treating the values as proof of runtime state.

## Query mismatch checks

Online `xlog search`, `capture`, `counter history` and `counter export` compare `--timezone` offsets against the reported Collector zone using client rules over the requested half-open interval. Different IDs with equal offsets throughout the interval are accepted. The check uses the query's instants, including internal DST transitions, rather than comparing a historical query with today's offset.

A mismatch returns `INVALID_ARGUMENT` (exit 2), naming `--timezone` and the reported Collector zone, before emitting stream events or creating capture files. There is no override option. With unavailable zone metadata, the previous unverified query behavior remains. Transport and malformed-response errors still fail normally; they are not silently treated as missing metadata.

For a Collector reporting `Asia/Seoul`, this declared date/zone combination matches:

```sh
scouterctl xlog search --object-hash 42 --date 20261109 --timezone Asia/Seoul \
--from 2026-11-09T13:00:00+09:00 --to 2026-11-09T13:01:00+09:00 --no-input
```

The same instants declared as `America/Los_Angeles` with date `20261108` are rejected. A UTC timestamp suffix is still valid input with `--timezone Asia/Seoul`; the timestamp syntax itself is not required to use the Collector's offset.

## Storage dates remain unverified

This is a comparison with a **reported JVM zone**, not confirmation of the storage partition. XLog `storageDateVerification: "unverified"` and capture `timezoneVerification: "operator-declared"` remain unchanged. Capture formats and strict-reader compatibility are unchanged; the new diagnostic fields are live output only.

Scouter's `DateTimeHelper` in 2.8.1 and 2.21.3 builds a calendar from local `20000101` with fixed 86,400,000-ms days. That calendar can differ from civil time around DST. For example, in `America/Chicago`, `2026-07-01T05:30:00Z` is July 1 by current zone rules but June 30 in that storage calendar. A matching zone check cannot certify the correct partition or prove that an empty result means no traffic. Confirm storage dates with the Collector operator when results are unexpected. This change does not repair that upstream calendar behavior or verify the server's cached calendar through the protocol.
2 changes: 2 additions & 0 deletions docs/inspection.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ scouterctl collector config --key net_tcp_listen_port

Status reports `usedHeapBytes`, `committedHeapBytes` and `serverTimeEpochMs`. Committed heap is not the JVM maximum heap. Collector metadata accompanies both results.

`doctor` and status also report the [Collector's JVM time-zone ID and client-rule offset](collector-timezone.md), including their provenance and reference time. This is separate from storage-date verification.

Configuration lists runtime settings exposed by the Collector alongside their defaults. Values are strings. The CLI shows values only for selected port, HTTP-enable and retention settings; other entries have `value: null`, `defaultValue: null` and `redacted: true`. Filtering by `--key` does not reveal hidden values. A missing setting exits 7. This is not a raw configuration-file export, and it does not include arbitrary custom properties.

These commands do not write settings or require a local Agent. They authenticate with the selected Collector account. Successful access does not prove that the Collector enforces distinct permissions for every operation; `effectivePermission` remains `unknown`.
Expand Down
1 change: 1 addition & 0 deletions docs/ko/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
- [설치·업데이트·이전 버전으로 전환·제거](installation.md)
- [빠른 시작](../../QUICKSTART.ko.md)
- [연결과 비밀번호](connections.md)
- [Collector 시간대와 조회 검사](collector-timezone.md)
- [프로파일 SQL 집계](profile-sql-summary.md)
- [기여 안내](../../CONTRIBUTING.ko.md) · [보안 안내](../../SECURITY.ko.md)

Expand Down
19 changes: 19 additions & 0 deletions docs/ko/collector-timezone.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Collector 시간대

[English](../collector-timezone.md) | 한국어

`doctor`와 `collector status`에 기존 `timezoneDisplayName` 외에 `timezone` 객체를 추가합니다. 상태 조회에서는 `data.collector.timezone`에 있습니다.

```json
{"id":"Asia/Seoul","utcOffsetSeconds":32400,"referenceTimeEpochMs":1793491200000,"idSource":"jvm-property","offsetSource":"client-zone-rules"}
```

ID는 인증된 기존 `SERVER_ENV` 요청으로 받은 JVM `user.timezone` 속성입니다. 인식 가능한 Java 단축 ID는 Java 매핑으로 확장합니다. 오프셋은 Collector의 `SERVER_TIME` 시각을 기준으로 **CLI의 시간대 규칙으로 계산한 값**이며, 서버에서 직접 측정한 오프셋은 아닙니다. 지역화된 표시명으로 ID를 추정하지 않으며 다른 JVM 환경 값은 출력하지 않습니다. 속성이 없거나 해석할 수 없으면 `timezone: null`입니다. 잘못된 프로토콜 타입은 값을 공개하지 않고 오류로 처리합니다.

`xlog search`, `capture`, `counter history`, `counter export`는 요청 구간의 오프셋을 보고된 Collector 시간대와 비교합니다. ID가 달라도 구간 전체의 오프셋이 같으면 허용합니다. 과거 조회를 현재 오프셋과 비교하지 않으며 구간 내부의 DST 전환과 종료 시각 미포함 조건도 검사합니다. 불일치하면 `--timezone`과 Collector 시간대를 명시한 `INVALID_ARGUMENT`(종료 코드 2)을 스트림 시작·캡처 파일 생성 전에 반환합니다. 우회 옵션은 없습니다. 메타데이터가 없으면 기존의 미검증 조회 동작을 유지하며, 통신·응답 오류를 미확인 상태로 숨기지 않습니다.

예를 들어 `Asia/Seoul`을 보고한 Collector에서는 같은 시각을 `America/Los_Angeles`와 그 지역 날짜로 선언한 요청을 거부합니다. `--from`·`--to`를 UTC 문자열로 주면서 `--timezone Asia/Seoul`을 지정하는 방식은 계속 사용할 수 있습니다.

이 검사는 보고된 JVM 시간대와의 비교입니다. 실행 중 변경된 기본 시간대, 서버와 CLI의 시간대 데이터 차이, 실제 저장 파티션까지 보장하지 않습니다. XLog의 `storageDateVerification: "unverified"`와 캡처의 `timezoneVerification: "operator-declared"`는 유지합니다. 새 진단 필드는 실시간 출력에만 추가하며 캡처 형식은 바꾸지 않습니다.

Scouter 2.8.1·2.21.3의 `DateTimeHelper`는 해당 지역의 `20000101`을 기준으로 하루를 86,400,000ms씩 증가시킵니다. 이 저장 달력은 DST가 반영된 실제 지역 날짜와 다를 수 있습니다. `America/Chicago`에서 `2026-07-01T05:30:00Z`는 지역 시간상 7월 1일이지만 저장 달력에서는 6월 30일입니다. 시간대가 일치해도 빈 결과를 트래픽 부재로 단정하지 말고, 예상과 다르면 운영자와 저장 날짜를 확인하세요. 이번 변경은 이 Scouter 저장 달력 동작을 수정하지 않습니다. 자세한 예시는 [영문 가이드](../collector-timezone.md)를 참고하세요.
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,11 @@ class CollectorSource private constructor(private val socket: Socket, private va
private var session = 0L
override lateinit var info: ServerInfo
private set
private val reportedTimezone by lazy {
collectorOperation { decodeCollectorTimezone(exchange(RequestCmd.SERVER_ENV), exchange(RequestCmd.SERVER_TIME)) }
}

override fun timezone(): CollectorTimezone? = reportedTimezone

companion object {
fun connect(endpoint: Endpoint, password: String, clientVersion: String): CollectorSource = collectorOperation {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
package dev.scouterctl.adapters.collector

import dev.scouterctl.application.describeCollectorTimezone
import dev.scouterctl.core.*
import scouter.lang.pack.MapPack
import scouter.lang.pack.Pack
import scouter.lang.value.DecimalValue
import scouter.lang.value.TextValue

internal fun decodeCollectorTimezone(environment: List<Pack>, clock: List<Pack>): CollectorTimezone? {
if (environment.isEmpty()) return null
val properties = environment.singleOrNull() as? MapPack
?: throw OperationFailure(ErrorCode.PROTOCOL_ERROR, "Invalid Collector environment response")
val value = properties.get("user.timezone") ?: return null
val id = (value as? TextValue)?.value
?: throw OperationFailure(ErrorCode.PROTOCOL_ERROR, "Invalid Collector time zone field")
val time = ((clock.singleOrNull() as? MapPack)?.get("time") as? DecimalValue)?.value
?: throw OperationFailure(ErrorCode.PROTOCOL_ERROR, "Invalid Collector clock response")
if (time < 0) throw OperationFailure(ErrorCode.PROTOCOL_ERROR, "Invalid Collector clock value")
return describeCollectorTimezone(id, time)
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
package dev.scouterctl.adapters.serialization

import dev.scouterctl.core.*
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.*

@Serializable
data class CollectorTimezoneDto(
val id: String, val utcOffsetSeconds: Int, val referenceTimeEpochMs: Long,
val idSource: String = "jvm-property", val offsetSource: String = "client-zone-rules",
)

private fun CollectorTimezone?.toJson(): JsonElement = this?.let {
json.encodeToJsonElement(CollectorTimezoneDto(it.id, it.utcOffsetSeconds, it.referenceTimeEpochMs))
} ?: JsonNull

fun ServerInfo.toLiveJson(timezone: CollectorTimezone?): JsonObject =
JsonObject(json.encodeToJsonElement(toDto()).jsonObject + ("timezone" to timezone.toJson()))

fun CollectorStatus.toLiveJson(info: ServerInfo, timezone: CollectorTimezone?): JsonObject =
JsonObject(json.encodeToJsonElement(toDto(info)).jsonObject + ("collector" to info.toLiveJson(timezone)))
34 changes: 34 additions & 0 deletions src/main/kotlin/dev/scouterctl/application/CollectorTimezone.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
package dev.scouterctl.application

import dev.scouterctl.core.*
import java.time.DateTimeException
import java.time.Instant
import java.time.ZoneId

fun describeCollectorTimezone(id: String, referenceTimeEpochMs: Long): CollectorTimezone? {
val zone = try { ZoneId.of(id, ZoneId.SHORT_IDS) } catch (_: DateTimeException) { return null }
val offset = zone.rules.getOffset(Instant.ofEpochMilli(referenceTimeEpochMs))
return CollectorTimezone(zone.id, offset.totalSeconds, referenceTimeEpochMs)
}

fun validateCollectorTimezone(declared: String, from: Long, to: Long, collector: CollectorTimezone?) {
if (collector == null) return
val requested = ZoneId.of(declared).rules
val reported = ZoneId.of(collector.id).rules
val start = Instant.ofEpochMilli(from)
val end = Instant.ofEpochMilli(to)
fun check(instant: Instant) {
if (requested.getOffset(instant) != reported.getOffset(instant)) {
throw OperationFailure(ErrorCode.INVALID_ARGUMENT,
"--timezone $declared differs from reported Collector time zone ${collector.id} in the requested interval")
}
}
check(start)
for (rules in listOf(requested, reported)) {
var transition = rules.nextTransition(start)
while (transition != null && transition.instant < end) {
check(transition.instant)
transition = rules.nextTransition(transition.instant)
}
}
}
1 change: 1 addition & 0 deletions src/main/kotlin/dev/scouterctl/application/Ports.kt
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import dev.scouterctl.core.*

interface ObservationSource : AutoCloseable {
val info: ServerInfo
fun timezone(): CollectorTimezone?
fun status(): CollectorStatus
fun settings(): List<RuntimeSetting>
fun agentStatus(objHash: Int): AgentStatus
Expand Down
11 changes: 9 additions & 2 deletions src/main/kotlin/dev/scouterctl/cli/OnlineCommands.kt
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,15 @@ class OnlineCommands(
val secret = password.read(connection.interactive, connection.noInput, request is OnlineRequest.Doctor && request.login)
return source(endpoint, secret).use { observation ->
when (request) {
is OnlineRequest.Doctor -> output.result(json.encodeToJsonElement(observation.info.toDto()))
OnlineRequest.CollectorStatus -> output.result(json.encodeToJsonElement(observation.status().toDto(observation.info)))
is OnlineRequest.Search -> validateCollectorTimezone(request.query.timezone, request.query.from, request.query.to, observation.timezone())
is OnlineRequest.Capture -> validateCollectorTimezone(request.query.timezone, request.query.from, request.query.to, observation.timezone())
is OnlineRequest.CounterHistory -> validateCollectorTimezone(request.query.timezone, request.query.from, request.query.to, observation.timezone())
is OnlineRequest.CounterExport -> validateCollectorTimezone(request.query.timezone, request.query.from, request.query.to, observation.timezone())
else -> Unit
}
when (request) {
is OnlineRequest.Doctor -> output.result(observation.info.toLiveJson(observation.timezone()))
OnlineRequest.CollectorStatus -> output.result(observation.status().toLiveJson(observation.info, observation.timezone()))
is OnlineRequest.CollectorConfig -> output.result(json.encodeToJsonElement(collectorSettings(observation, request.key).toSettingsDto(observation.info)))
is OnlineRequest.AgentStatus -> output.result(json.encodeToJsonElement(observation.agentStatus(request.objHash).toDto(observation.info)))
is OnlineRequest.AgentConfig -> output.result(json.encodeToJsonElement(agentSettings(observation, request.objHash, request.key).toDto(observation.info)))
Expand Down
3 changes: 3 additions & 0 deletions src/main/kotlin/dev/scouterctl/core/CollectorTimezone.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
package dev.scouterctl.core

data class CollectorTimezone(val id: String, val utcOffsetSeconds: Int, val referenceTimeEpochMs: Long)
Loading
Loading