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: 3 additions & 1 deletion .github/PULL_REQUEST_TEMPLATE/english.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ See CONTRIBUTING.md for PR targets and merge methods.

## Why

<!-- What problem does this solve? Link a related issue if there is one. -->
<!-- What problem does this solve? If there is an issue, use Refs #59 for a PR to develop
or Closes #59 for a PR to master that includes the fix. Replace 59 with the issue number.
-->

## Changes

Expand Down
4 changes: 3 additions & 1 deletion .github/PULL_REQUEST_TEMPLATE/korean.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ PR 대상 브랜치와 병합 방식은 CONTRIBUTING.md를 참고해 주세요.

## 변경 이유

<!-- 어떤 문제를 해결하나요? 관련 이슈가 있으면 연결해 주세요. -->
<!-- 어떤 문제를 해결하나요? 관련 이슈가 있다면 develop 대상 PR에는 Refs #59,
해결분을 포함한 master 대상 PR에는 Closes #59를 적습니다. 59는 실제 이슈 번호로 바꿔 주세요.
-->

## 주요 변경

Expand Down
58 changes: 58 additions & 0 deletions .github/scripts/summarize-tests.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
#!/usr/bin/env python3
"""Render Gradle test counts and the coverage summary without publishing logs."""

import argparse
from pathlib import Path
import xml.etree.ElementTree as ET


def summarize(tests_directory: Path, coverage_summary: Path) -> str:
lines = ["## Test results (Linux)", ""]
reports = sorted(tests_directory.glob("TEST-*.xml"))
try:
if not reports:
raise ValueError("No test reports")
totals = dict.fromkeys(("tests", "failures", "errors", "skipped"), 0)
for report in reports:
suite = ET.parse(report).getroot()
if suite.tag != "testsuite":
raise ValueError("Unexpected report root")
counts = {name: int(suite.attrib[name]) for name in totals}
if min(counts.values()) < 0 or counts["tests"] < sum(counts[name] for name in ("failures", "errors", "skipped")):
raise ValueError("Invalid report counts")
for name, value in counts.items():
totals[name] += value
passed = totals["tests"] - totals["failures"] - totals["errors"] - totals["skipped"]
lines += [
"| Total | Passed | Failed | Errors | Skipped |",
"| ---: | ---: | ---: | ---: | ---: |",
f"| {totals['tests']} | {passed} | {totals['failures']} | {totals['errors']} | {totals['skipped']} |",
]
if not totals["tests"]:
lines += ["", "No tests were executed."]
except (ET.ParseError, OSError, KeyError, ValueError):
lines += ["Test results are unavailable or invalid. Check the build logs; this is not a passing test result."]
lines += [""]
try:
coverage = coverage_summary.read_text(encoding="utf-8").strip()
except (OSError, UnicodeError):
coverage = ""
if coverage:
lines += [coverage]
else:
lines += ["## Test coverage", "", "Coverage is unavailable. The build or tests may have stopped before a report was generated."]
return "\n".join(lines) + "\n"


def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--tests-directory", type=Path, default=Path("build/test-results/test"))
parser.add_argument("--coverage-summary", type=Path, default=Path("build/reports/jacoco/summary.md"))
parser.add_argument("--output", type=Path, default=Path("build/reports/ci/summary.md"))
args = parser.parse_args()
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(summarize(args.tests_directory, args.coverage_summary), encoding="utf-8")


if __name__ == "__main__":
main()
4 changes: 2 additions & 2 deletions .github/workflows/capture-scale.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
- uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
with:
distribution: temurin
java-version: '21'
Expand Down Expand Up @@ -51,7 +51,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
- uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
with:
distribution: temurin
java-version: '21'
Expand Down
90 changes: 87 additions & 3 deletions .github/workflows/ci-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jobs:
master:develop|master:hotfix/*|master:release-please--branches--master) ;;
*) echo "Unsupported PR route: $HEAD_BRANCH -> $BASE_BRANCH" >&2; exit 1 ;;
esac
- uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
- uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
with:
distribution: temurin
java-version: '21'
Expand All @@ -67,8 +67,12 @@ jobs:
env:
EXPECTED_TAG: ${{ inputs.release_tag }}
run: |
coverage_args=()
if [[ -z "${EXPECTED_TAG:-}" ]]; then
coverage_args=(-Pcoverage=true coverageCheck)
fi
if [[ -f .github/scripts/verify-release-files.sh ]]; then
./gradlew --no-daemon test verifyReleaseInputs
./gradlew --no-daemon test "${coverage_args[@]}" verifyReleaseInputs
printf 'format=commands\n' >> "$GITHUB_OUTPUT"
printf 'package_path=build/release-inputs\n' >> "$GITHUB_OUTPUT"
else
Expand All @@ -83,6 +87,34 @@ jobs:
[[ -z "${EXPECTED_TAG:-}" || "$EXPECTED_TAG" == "v$version" ]]
printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
printf 'sha=%s\n' "$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
- name: Summarize tests and coverage
if: ${{ always() && inputs.release_tag == '' }}
run: |
python3 .github/scripts/summarize-tests.py
cat build/reports/ci/summary.md >> "$GITHUB_STEP_SUMMARY"
- name: Upload PR test summary
if: ${{ always() && github.event_name == 'pull_request' && !env.ACT }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: pr-test-summary
path: build/reports/ci/summary.md
if-no-files-found: warn
retention-days: 14
- name: Upload coverage reports
if: ${{ always() && !env.ACT && hashFiles('build/reports/jacoco/**') != '' }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: coverage-reports
path: build/reports/jacoco/
if-no-files-found: error
retention-days: 14
- name: Save local coverage reports
if: ${{ always() && env.ACT == 'true' && hashFiles('build/reports/jacoco/**') != '' }}
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2; act artifact API
with:
name: coverage-reports
path: build/reports/jacoco/
if-no-files-found: error
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
if: ${{ always() && !env.ACT }}
with:
Expand Down Expand Up @@ -112,6 +144,58 @@ jobs:
path: ${{ steps.package.outputs.package_path }}
if-no-files-found: error

test-comment:
name: Comment test results
needs: build
if: >-
always() && !cancelled() && github.event_name == 'pull_request' &&
github.event.pull_request.head.repo.full_name == github.repository &&
github.event.pull_request.user.login != 'dependabot[bot]'
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
actions: read
pull-requests: write
steps:
- name: Download test summary
continue-on-error: true
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: pr-test-summary
path: ci-summary
- name: Create or update the PR comment
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
BUILD_RESULT: ${{ needs.build.result }}
with:
script: |
const fs = require('node:fs');
const marker = '<!-- scouterctl-ci-test-summary -->';
const {owner, repo} = context.repo;
const issue_number = context.payload.pull_request.number;
const head = context.payload.pull_request.head.sha;
const {data: pr} = await github.rest.pulls.get({owner, repo, pull_number: issue_number});
if (pr.state !== 'open' || pr.head.sha !== head) {
core.info('Skipping results for an outdated or closed pull request.');
return;
}
// Read report text only. Never check out or execute PR code with this token.
const file = 'ci-summary/summary.md';
const summary = fs.existsSync(file) && fs.statSync(file).size <= 16000
? fs.readFileSync(file, 'utf8')
: 'Test and coverage summary unavailable. Check the workflow logs.';
const run = `${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`;
const body = `${marker}\n**Linux CI: ${process.env.BUILD_RESULT}** · Commit \`${head.slice(0, 7)}\`\n\n${summary}\n[Workflow logs and report artifacts](${run})\n\n_Updated on each CI run. Windows checks, when required, are reported separately in the workflow._`;
const comments = await github.paginate(github.rest.issues.listComments,
{owner, repo, issue_number, per_page: 100});
const previous = comments.find(comment =>
comment.user?.login === 'github-actions[bot]' && comment.body?.startsWith(marker));
if (previous) {
await github.rest.issues.updateComment({owner, repo, comment_id: previous.id, body});
} else {
await github.rest.issues.createComment({owner, repo, issue_number, body});
}

portable:
name: Windows command package
needs: build
Expand All @@ -128,7 +212,7 @@ jobs:
with:
ref: ${{ inputs.release_tag || github.sha }}
persist-credentials: false
- uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
- uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
with:
distribution: temurin
java-version: '21'
Expand Down
12 changes: 10 additions & 2 deletions CONTRIBUTING.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ Linux 명령 ZIP의 빌드·검증:

개발용 설치는 `./gradlew installDist` 후 `build/install/scouterctl/bin/scouterctl`로 실행합니다. 네이티브 Windows 패키지는 별도 빌드 도구가 필요합니다. [릴리스 안내(영문)](docs/releasing.md)를 참고하세요. 실제 Collector·Agent·Spring 검사는 [테스트 안내(영문)](docs/testing.md)의 별도 작업이며, [로컬 CI(영문)](docs/local-ci.md)에서 act 실행 방법을 확인할 수 있습니다.

커버리지 리포트를 만들고 라인·분기 최소 기준을 검증하려면 `./gradlew -Pcoverage=true coverageCheck`를 실행합니다. 테스트 JVM과 CLI 자식 프로세스를 함께 집계하며, 라인 90%·분기 80% 미만이면 실패합니다. 기본 `test` 실행에는 커버리지를 적용하지 않습니다. HTML/XML 리포트와 요약은 `build/reports/jacoco/`에 생성됩니다. 측정 범위와 CI 동작은 [테스트 안내(영문)](docs/testing.md#coverage)를 참고하세요.

같은 저장소의 PR에는 Linux 테스트 통과·실패·오류·스킵 수, 라인·분기 커버리지와 최소 기준, CI 결과와 실행 링크를 코멘트로 표시합니다. 재실행하면 기존 봇 코멘트를 갱신하며, 이전 커밋의 결과는 게시하지 않습니다. Windows 검사는 워크플로우에서 별도로 확인합니다. 읽기 전용 토큰을 사용하는 포크·Dependabot PR은 Actions 요약과 artifact를 제공하며 코멘트는 작성하지 않습니다.

## 코드와 테스트

- CLI 기능은 Kotlin으로 작성합니다. Kotest `FunSpec`과 matcher를 사용하며 실행에는 JUnit Platform을 사용합니다. 네이티브 [Windows 실행기(영문)](https://github.com/oxspan/scouterctl/blob/master/native/windows/README.md)는 별도 플랫폼 구성 요소입니다.
Expand All @@ -37,10 +41,14 @@ Linux 명령 ZIP의 빌드·검증:

| 변경 | 시작 브랜치 | PR 대상 |
| --- | --- | --- |
| 기능·일반 수정·테스트·문서 (`feature/*`) | `develop` | `develop` |
| 긴급 배포 수정 (`hotfix/*`) | `master` | `master` |
| 기능·일반 수정·테스트·문서 (`feature/<이슈번호>[-<설명>]`) | `develop` | `develop` |
| 긴급 배포 수정 (`hotfix/<이슈번호>[-<설명>]`) | `master` | `master` |
| 배포할 변경 통합 | `develop` | `master` |

`feature/59`처럼 `#`을 뺀 이슈 번호를 사용합니다. 작업을 알아보기 쉽도록 `feature/59-object-list`처럼 소문자와 하이픈으로 짧은 설명을 붙이는 것을 권장하며, 설명은 생략할 수 있습니다. 연결할 이슈가 없는 소규모 유지보수는 `feature/<설명>`을 사용합니다. Dependabot과 release-please는 자동 생성된 브랜치명을 사용합니다.

`develop` 대상 PR에는 `Refs #59`로 이슈를 참조합니다. 해결분을 포함한 `master` 대상 PR에는 `Closes #59`를 적어 병합 시 이슈가 닫히도록 합니다.

`master`는 기본·배포 브랜치이고 `develop`은 다음 변경을 통합합니다. 별도 release 브랜치는 현재 사용하지 않습니다. PR에는 문제·변경 후 동작·실제로 수행한 검증·기존 사용자에게 미치는 영향을 적습니다.

비교할 브랜치를 고른 뒤 기본 PR 설명의 **Preview** 탭에서 **English** 또는 **한국어**를 선택하세요. 언어를 바꾸면 양식이 다시 열리므로 본문 작성 전에 선택합니다. GitHub가 작성 중인 내용을 복원하면 언어 링크를 새 탭에서 열고, 브랜치를 바꿨다면 언어를 다시 선택하세요. 양식은 기본 브랜치에서 불러옵니다. 로컬 템플릿도 사용할 수 있습니다.
Expand Down
12 changes: 10 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ To build and verify the Linux command package:

For a local Linux installation, use `./gradlew installDist` and run `build/install/scouterctl/bin/scouterctl`. Native Windows packaging additionally requires the pinned toolchain; see [releasing](docs/releasing.md). Real Collector/Agent/Spring checks are opt-in and described in [testing](docs/testing.md). Use [local CI](docs/local-ci.md) to run the workflow build with act when needed.

To generate coverage reports and enforce the line/branch minimums, run `./gradlew -Pcoverage=true coverageCheck`. This includes the test JVM and CLI subprocesses. See [testing](docs/testing.md#coverage) for measurement scope and report locations.

Same-repository PRs receive a bot comment with Linux test counts, coverage/thresholds, the CI result and run links. Re-runs update the existing comment and outdated commits are skipped. Windows checks remain in the workflow; fork and Dependabot PRs receive the Actions summary and artifacts without a comment because their tokens are read-only.

## Code and tests

- Implement CLI behavior in Kotlin. Use Kotest `FunSpec` and matchers; JUnit Platform runs Kotest, while test APIs remain Kotest. The native [Windows launcher](https://github.com/oxspan/scouterctl/blob/master/native/windows/README.md) is a separate platform boundary.
Expand All @@ -37,10 +41,14 @@ For a local Linux installation, use `./gradlew installDist` and run `build/insta

| Change | Start from | PR target |
| --- | --- | --- |
| Feature, regular fix, tests or documentation (`feature/*`) | `develop` | `develop` |
| Urgent release fix (`hotfix/*`) | `master` | `master` |
| Feature, regular fix, tests or documentation (`feature/<issue>[-<slug>]`) | `develop` | `develop` |
| Urgent release fix (`hotfix/<issue>[-<slug>]`) | `master` | `master` |
| Release-ready integration | `develop` | `master` |

Use the issue number without `#`, as in `feature/59`. A short lowercase, hyphen-separated description is optional and recommended for readability, as in `feature/59-object-list`. For small maintenance changes without an issue, use `feature/<slug>`. Dependabot and release-please use their generated branch names.

Reference the issue with `Refs #59` in a PR to `develop`. When the fix is included in a PR to `master`, use `Closes #59` to close the issue on merge.

`master` is the default and release branch; `develop` integrates upcoming changes. Release branches are not currently used. Keep each PR focused and explain the problem, resulting behavior, validation actually performed, and compatibility risks.

Choose the base and compare branches before selecting **English** or **한국어** from the default PR description's **Preview** tab. Switching languages reloads the form, so select a language before writing the description. If GitHub restores a draft, open the language link in a new tab; reselect it after changing branches. Templates are loaded from the default branch. Alternatively, use a local template:
Expand Down
7 changes: 7 additions & 0 deletions QUICKSTART.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ JDK 21과 [운영체제에 맞는 ZIP](docs/ko/installation.md)을 설치한 뒤
```sh
scouterctl --version
scouterctl --help
scouterctl capture --help
```

여러 줄로 적은 명령은 Bash 예시입니다. Windows에서는 각 명령을 한 줄로 입력하면 같은 옵션을 사용할 수 있습니다.
Expand Down Expand Up @@ -40,6 +41,8 @@ scouterctl counter get --object-hash 123456 --counter HeapUsed --no-input

## 3. 트랜잭션과 프로파일 저장

Collector를 재시작한 뒤에도 `scouterctl object list --date 20261107 --no-input`으로 해당 저장 날짜에 기록된 `objHash`를 찾을 수 있습니다. 저장된 목록에는 실시간 상태가 없어 날짜를 지정하면 `alive: false`로 표시합니다. 현재 상태는 날짜를 빼고 `object list`로 확인하세요.

조회할 자료가 저장된 날짜와 Collector의 시간대를 사용합니다. 아래는 UTC 예시입니다. `captures`가 없으면 먼저 만들고, 캡처마다 새 하위 디렉터리를 지정하세요.

```sh
Expand All @@ -49,8 +52,12 @@ scouterctl capture --object-hash 123456 --date 20261107 \
--include-profiles --directory captures/incident-001 --no-input
```

캡처 결과의 `storageDateVerification: "unverified"`는 입력한 저장 날짜를 Collector에서 확인하지 않았다는 뜻입니다. 조회가 완료됐는데 결과가 비어 있으면 저장 날짜를 확인하세요.

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

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

## 4. Collector 없이 분석

```sh
Expand Down
Loading
Loading