From e9339eae0b35465562b25443608b68e6beeae521 Mon Sep 17 00:00:00 2001 From: "nonvis@gmail.com" Date: Thu, 8 Jul 2021 17:28:28 +0900 Subject: [PATCH 1/3] docs(kr): core-cli --- docs/ko/core/cli.md | 173 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 docs/ko/core/cli.md diff --git a/docs/ko/core/cli.md b/docs/ko/core/cli.md new file mode 100644 index 000000000..918d24fee --- /dev/null +++ b/docs/ko/core/cli.md @@ -0,0 +1,173 @@ + + +# 명령어 인터페이스 (Command-Line Interface: CLI) + +본 문서는 애플리케이션에 대하여 명령어 인터페이스(CLI)가 어떻게 동작하는지 설명합니다. 명령어 인터페이스를 구현하는 방법에 대해서는 [이 문서](../building-modules/module-interfaces.md#cli)를 참조 바랍니다. + +## 명령어 인터페이스(CLI) + +### CLI 사용 예제 + +새로운 CLI를 만들기 위해 SDK 모듈은 일반적으로 [Cobra Library](https://github.com/spf13/cobra) 을 사용합니다. Cobra Library를 사용하여 CLI을 만들기 위해 commands(명령어), arguments(인자값), flags(플래그)가 정의 가능합니다. +[**Commands**](#commands)는 사용자가 실행하려는 동작에 대하여 정의합니다. 예를 들어 트랜잭션 생성 할 때는 `tx`라는 command를 사용하고, 애플리케이션에서 특정 값을 조회 할 때는 `query`라는 command를 사용하도록 정의할 수 있습니다. +또한 commands는 중첩되는 subcommands를 포함하여 추가적으로 트랜잭션 타입을 지정할 수 있습니다. 사용자는 코인을 수신하려고 하는 계정번호를 **Arguments**에 지정할 수 있고 코인 전송에 필요한 gas price나 이용하려고 하는 node 주소를 [**Flags**](#flags)에 정의하여 추가적으로 commands에 대한 다양한 요소들을 변경할 수 있습니다. + +다음은 사용자가 `simd`이라고 하는 CLI를 이용하여 토큰을 전송하려고 하는 예제입니다. +```bash +simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --gas auto --gas-prices +``` +처음 네개의 string 값들이 command에 대하여 정의하고 있습니다. +- `simd` : command 이름 +- `tx` : 트랜잭션 생성 +- `bank` : 사용하기 원하는 모듈 지정 ( [`x/bank`](../../x/bank/spec/README.md) 모듈) +- `send` : 트랜잭션 타입 + +그 다음 두개의 string 값들은 arguements 입니다. +- `from_address` : 송신자 주소 +- `to_address` : 수진자 주소 +- `amount` : 보내고자 하는 액수 + +마지막으로 나머지 strings 값들은 flags로 사용자가 얼마만큼의 사용료(사용한 gas 양과 gas price를 통해 산출)를 지불할지 정의합니다. + +위 CLI는 [node](../core/node.md)를 통하여 실행되며 인터페이스는 `main.go`에 정의됩니다. + + +### CLI 만들기 + +`main.go` 파일은 root command를 생성하는 `main()` 함수를 포함해야 하며 애플리케이션에서 할 모든 명령어들은 subcommands로 추가됩니다. root command는 추가적으로 다음을 수행합니다. + +- **설정 변경** : 설정파일(sdk 설정 파일)을 읽어 반영합니다. +- **flags 값 설정** : `--chain-id` 같은 새로운 flag 값을 추가합니다. +- **`codec` 실행** : 애플리케이션의 `MakeCodec()` 함수(`simapp`에서 `MakeTestEncodingConfig`)를 호출합니다. [`codec`](../core/encoding.md)은 애플리케이션에서 사용하는 데이터를 encode하고 decode 합니다. 기본적으로 Probuf를 사용하지만 개발자가 다른 serialization format을 정의하여 사용할 수 있습니다. +- **subcommand 설정** : 사용자의 편의를 위하여 [transaction commands](#transaction-commands)와 [query commands](#query-commands)를 포함한 모든 액션을 정의합니다. + +`main()`함수는 root command를 [실행](https://godoc.org/github.com/spf13/cobra#Command.Execute) 할 수 있는 executor를 생성합니다. 예제로 `simapp` 애플리케이션에서 `main()` 함수를 참조하세요. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/main.go#L12-L24 + +다음에는 각 절차마다 개발이 필요한 부분에 대하여 설명하고 `simapp` CLI 파일의 간단한 예제를 소개하겠습니다. + +## CLI에 새로운 commond를 추가하기 +모든 애플리케이션에서는 먼저 root command를 만들고, `rootCmd.AddCommand()`함수를 사용하여 subcommands를 집계(subcommands이 중첩가능)하여 기능을 추가하게 됩니다. 각 애플리케이션의 고유 기능에 대해서는 `TxCmd`라는 transaction command와 `QueryCmd`라는 query command에 정의됩니다. + +### Root Command +`rootCmd`라고 하는 root command는 사용하려고 하는 애플리케이션을 지정하려 사용자가 맨처음 커맨드라인에 입력하는 string 값입니다. 일반적으로 애플리케이션 이름에 `-d`를 접미사로 붙여 사용합니다. (예: `simd`, `gaiad`) root command는 다음 commands를 포함하여 애플리케이션의 기본 기능에 대하여 정의할 수 있습니다. + +- **Status** : SDK rpc client tools에서 제공합니다. 연결되어 있는 [`Node`](../core/node.md)에 대한 상태정보(`NodeInfo`,`SyncInfo`, `ValidatorInfo`)를 제공합니다. +- **Keys** : SDK client tools 에서 [제공](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys) 합니다. SDK crypto tools를 사용하기 위한 subcommands가 포함되어 새로운 key를 생성하여 keyring에 저장하고, keyring에 저장되어 있는 public key를 읽어오거나 key를 삭제할 수 있습니다. + 예를 들어 사용자가 `simd keys add `를 입력하여 새로운 key를 생성하고 암호화하여 keyring에 저장하거나, `--recover`라는 flag를 사용하여 seed phrase로 부터 private key를 복구하거나, `--multisig`라는 flag를 사용하여 여러개의 key를 그룹으로 묶어 multisig key를 생성할 수 있습니다. + `add` key command에 대한 더 자세한 정보는 이 [코드](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys/add.go) 를 참조바라고 key credential 보관을 위하여 `--keyring-backend` 사용방법에 대해서는 [keyrings docs](../run-node/keyring.md) 참조 바랍니다. +- **Server** : SDK server package에서 제공합니다. ABCI Terndermint 애플리케이션 구동에 필요한 패키지를 제공하며 [Cobra](github.com/spf13/cobra) 기반의 CLI 프레임워크도 포함하고 있습니다. + `StartCmd`와 `ExportCmd`라고 하는 두개의 코어 함수를 포함하여 애플리케이션을 시작하고 상태를 export 합니다. 더 자세한 정보는 [여기](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/server) 를 참조 바랍니다. +- [**Transaction**](#transaction-commands) +- [**Query**](#query-commands) + +다음은 `simapp` 애플리케이션의 `rootCmd` 예제 함수입니다. root command를 정의하고 [_persistent_ flag](#flags)와 `PreRun`함수를 추가하여 다른 execution전에 실행시키고 모든 필요한 subcommands를 추가합니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L37-L150 + +`rootCmd`에는 `initAppConfig()`라는 함수가 포함되어 있는데 애플리케이션의 설정을 임의 값으로 변경할 때 사용됩니다. 애플리케이션은 기본적으로 Tendermint의 config template을 사용하는데 `initAppConfig()`을 이용하여 설정을 덮어쓸수 있습니다. 다음은 기본 설정인 `app.toml`을 덮어쓰는 예제 입니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L84-L117 + +`initAppConfig()`는 또한 기본 SDK의 [서버설정](https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/server/config/config.go#L199) 을 덮어쓸수 있습니다. +트랜잭션을 실행할 때 validators가 요구하는 최저 gas price를 설정하는 `min-gas-prices`을 예로 들어 보겠습니다. SDK는 기본적으로 이 설정을 `""` (비어있는 string)로 설정하는데 validators는 이 경우 `app.toml`을 변경하여 비어있지 않도록 하고 그 변경이 실패할 경우 구동 후 즉시 node의 실행을 멈춥니다. +이 방식이 validators에게는 최선이 아니기 때문에 체인 개발자들은 validators들을 위하여 `initAppConfig()` 함수 안에 기본 `app.toml` 값을 설정 할 수 있습니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/aa9b055ddb46aacd4737335a92d0b8a82d577341/simapp/simd/cmd/root.go#L101-L116 + +`status`와 `keys` subcommands는 대부분의 애플리케이션들이 지원하지만 정작 애플리케이션의 상태를 변경시키지 않습니다. 애플리케이션의 기능들 대부분은 `tx`와 `query` commands를 통하여 변경될 수 있습니다. + +### Transaction Commands + +[Transactions](./transactions.md)은 [`Msg`s](../building-modules/messages-and-queries.md#messages) 를 감싸는 objects로 상태를 변경 시킬수 있습니다. +일반적으로 CLI를 통하여 트랜잭션을 생성시키고자 `rootCmd` 안에 `txCmd` 함수가 포함됩니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92 + +`txCmd` 함수는 사용 가능한 모든 트랜잭션 commands을 사용자에게 제공합니다. + +- **Sign command** : [`auth`](../../x/auth/spec/README.md) 모듈에서 제공되며 메시지 서명 기능을 제공합니다. multisig를 지원하려면 `auth` 모듈의 `MultiSign` command를 추가해야 합니다. 일반적으로 트랜잭션 안에 서명이 포함되어야 그 트랜잭션이 유효하기 때문에 이 sign command는 모든 애플리케이션에 필요합니다. +- **Broadcast command** : SDK client tools에서 제공되며 트랜잭션을 broadcast 할 때 사용합니다. +- **All [module transaction commands](../building-modules/module-interfaces.md#transaction-commands)** : [기본 모듈 매니저](../building-modules/module-manager.md#basic-manager)가 `AddTxCommands()` 함수를 통하여 제공합니다. + +다음은 `simapp` 애플리케이션에서 `txCmd` 함수를 사용하는 예제입니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L123-L149 + +### Query Commands + +[**Queries**](../building-modules/messages-and-queries.md#queries)는 애플리케이션의 상태를 가져올 수 있는 object 입니다. `rootCmd` 안에 `queryCmd` 함수가 포함됩니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92 + +`queryCmd` 함수는 사용 가능한 모든 트랜잭션 commands을 사용자에게 제공합니다. + +- **QueryTx** : `auth` 모듈에서 제공되며 사용자는 hash, tag, block height를 사용하여 트랜잭션을 검색 할 수 있습니다. 사용자는 이 command를 사용하여 트랜잭션이 블록에 포함되어 있는지 확인해 볼 수 있습니다. +- **Account command** : `auth` 모듈에서 제공되며 계정 잔고와 같은 상태를 확인 할 수 있습니다. +- **Validator command** : SDK rpc client tools에서 제공되며 height 별로 validator 그룹을 확인 할 수 있습니다. +- **Block command** : SDK rpc client tools에서 제공되며 height 별로 블록 데이터를 확인 할 수 있습니다. +- **All [module query commands](../building-modules/module-interfaces.md#query-commands)** : [기본 모듈 매니저](../building-modules/module-manager.md#basic-manager)가 `AddQueryCommands()` 함수를 통하여 제공됩니다. + +다음은 `simapp` 애플리케이션에서 `queryCmd` 함수를 사용하는 예제입니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L99-L121 + +## Flags + +Flags를 사용하여 commands를 변경할 수 있습니다. 개발자는 flags를 `flags.go`파일에 포함 할 수 있습니다. 사용자는 flags를 명확히 commands와 함께 입력할 수 있고 `app.toml`안에 사전 구성 할 수 있습니다. 일반적으로 사전 구성하는 flags는 `--node`(연결하려는 노드)와 `--chain-d`(블록체인)가 있습니다. + +Persistent flag는 지속성이 있는 flag로서 그 command로 부터 상속받는 subcommands은 그 flag 값도 상속을 받습니다. 또한 모든 flags는 기본값이 설정되어 사용자는 그 기본값을 다른 값으로 변경해야 command를 유용하게 사용할 수 있습니다. 필수 flag인 경우에도 불구하고 사용자가 입력하지 않는 경우 에러가 발생하도록 할 수 있습니다. + +Flag는 command에 바로 포함시키며 (일반적으로 [모듈의 CLI 파일](../building-modules/module-interfaces.md#flags) 안에) `rootCmd` persistent flags를 제외한 다른 flag들은 애플리케이션 레벨에 포함시킬 필요가 없습니다. +일반적으로 블록체인 아이디를 지정할 수 있는 persistent flag인 `--chain-d`을 root command에 추가합니다. 블록체인 아이디는 애플리케이션이 구동 된 후 변경되어서는 안되기 때문에 이 flag는 `main()`함수 안에 정의 할 수 있는 것이 좋습니다. +다음 `simapp` 애플리케이션 예제를 참조바랍니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118-L119 + +## Environment variables + +flag는 그 flag의 이름으로 구성되어 있는 환경변수와 깊이 결합되어 있습니다. 환경변수는 모두 대문자로 구성되어야 하고 `basename`으로 시작해야 하고 `-` 대신 `_`을 사용합니다. +예를 들어 flag `--home`이 있고 애플리케이션의 basename이 `GAIA`라고 한다면 해당 flag는 `GAIA_HOME` 환경변수와 결합되어 있습니다. +환경변수를 활용하면 flag를 입력할 필요가 없습니다. +예를 들면: + +```sh +gaia --home=./ --node= --chain-id="testchain-1" --keyring-backend=test tx ... --from= +``` + +위 예제 보다 아래가 더 사용하기 편리합니다. + +```sh +# 환경변수를 한번 정의하세요 +GAIA_HOME= +GAIA_NODE= +GAIA_CHAIN_ID="testchain-1" +GAIA_KEYRING_BACKEND="test" + +# 나중에 사용할 때 flag를 포함시키 않아도 됩니다 +gaia tx ... --from= +``` + +## Configurations + +애플리케이션의 root command가 Cobra의 `PersistentPreRun()` command property를 사용하는 것이 중요합니다. 그래야 그 command로부터 상속받는 다른 commands이 서버와 클라이언트의 contexts에 접근이 가능합니다. +이 contexts가 그들의 기본 설정으로 세팅이 되지만 나중에 변경도 가능하고 command 별로 변경이 적용이 되는 범위도 제한할 수 있습니다. +일반적으로 `client.Context`는 모든 commands들을 위하여 미리 유용한 기본값으로 설정이 되고 필요에 따라 값이 상속되거나 다른 값으로 변경될 수 있습니다. + +다음은 `simapp` 애플리케이션에서 `PersistentPreRun()`함수를 사용하는 예제입니다. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L54-L60 + +`SetCmdClientContextHandler`를 호출하면 `ReadPersistentCommandFlags`을 통하여 persistent flags를 읽고 `client.Context`를 생성하여 root command의 `Context`을 설정합니다. + +`InterceptConfigsPreRunHandler`를 호출하면 `server.Context`을 생성하여 root command의 `Context`을 설정합니다. +`server.Context`는 변경이 되어 `interceptConfigs`을 호출하여 디스크에 저장이 되고 `home path`에 정의되어 있는 Terdermint 설정파일을 읽어오든지 없다면 새롭게 생성합니다. +또한 `interceptConfigs`을 호출하여 애플리케이션 설정파일인 `app.toml`을 읽고 `server.Context`의 viper literal에 연동시킵니다. +이는 애플리케이션이 CLI flags 뿐만 아니라 애플리케이션 설정파일에 접근하기 위해 필요한 절차입니다. + +## Next {hide} + +[events](./events.md) {hide} \ No newline at end of file From 0a7f1a1dfffa99e068869ef9ebab78482e3be746 Mon Sep 17 00:00:00 2001 From: "nonvis@gmail.com" Date: Wed, 14 Jul 2021 18:39:10 +0900 Subject: [PATCH 2/3] docs(kr): core-simulation --- docs/ko/core/simulation.md | 76 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/ko/core/simulation.md diff --git a/docs/ko/core/simulation.md b/docs/ko/core/simulation.md new file mode 100644 index 000000000..a50d00b0c --- /dev/null +++ b/docs/ko/core/simulation.md @@ -0,0 +1,76 @@ + + +# 코스모스 블록체인 시뮬레이터 + +Cosmos SDK는 시뮬레이션 프레임워크를 제공하며 이를 통하여 모듈에서 사용하는 모든 메시지를 테스트 할 수 있습니다. + +SDK에서 이 기능은 [`simulation`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/simulation) 모듈 안에 포함되어 있고 +[`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/app.go) 이라는 `Baseapp` 애플리케이션을 실행시키면 확인 할 수 있습니다. +이 모듈은 시뮬레이션 로직을 정의하며 계정이나 잔고를 임의로 설정하는 기능도 포함하고 있습니다. + +## 목표 + +블록체인 시뮬레이터는 애플리케이션이 실제 상황에서 어떻게 작동하는지 테스트 하기 위하여 무작위로 메시지를 생성하고 보냅니다. +시뮬레이션의 목표는 로그 분석과 애플리케이션 상태 변화를 모니터하여 블록체인을 멈출수 있는 심각한 오류를 찾고 문제를 찾았을 경우 디버그하는 것입니다. + +통합테스트와의 주요 차이점은 시뮬레이터를 사용하면 시뮬레이션 하는 블록체인에 대한 매개 변수를 전달할 수 있다는 것입니다. +이것은 문제가 발견된 버그를 재현하려고 할 때 유용하게 사용할 수 있습니다. + +## 시뮬레이션 명령어 + +시뮬레이터는 다양한 시나리오를 테스트 할 수 있는 명령어가 있습니다. + +- `AppImportExport` : 시뮬레이터는 초기 앱 상태를 내보내고 새로운 앱을 생성하여 전에 내보내기 한 `genesis.json`을 읽어오며 저장할 때 발생할 수 있는 문제를 확인 할 수 있습니다. +- `AppSimulationAfterImport` : 두개의 시뮬레이션을 연속으로 실행하여 첫번째 시뮬레이션이 `genesis.json`을 생성하고 두번째 시뮬레이션이 그 앱 상태를 읽어들이도록 할 수 있습니다. 이를 통하여 소프트웨어를 업그레이드나 블록체인 하드포크가 일어나는 상황을 테스트 할 수 있습니다. +- `AppStateDeterminism` : 모든 노드가 같은 값을 같은 순서대로 반환하는지 확인 할 수 있습니다. +- `BenchmarkInvariants` : 모든 모듈의 불변성에 대한 분석을 할 수 있습니다. (예를 들어 순차적으로 여러 [벤치마크](https://golang.org/pkg/testing/#hdr-Benchmarks) 테스트를 실행할 수 있습니다) 불변성 검증은 특정값이 변경하지 않도록 고정시켜 놓고 다른 값들을 변화시키며 그 차이를 검증하는 것입니다. 예를 들어 한 계정이 보유중인 총 코인수와 전체 공급되어 있는 코인수 +- `FullAppSimulation` : 기본 시뮬레이션 모드입니다. 블록체인을 실행시키고 특정 블록에 대하여 여러 오퍼레이션을 적용시킬수 있습니다. `panic`발생 여부를 테스트 할 수 있고 벤치마크는 어렵겠지만 `period`마다 불변성 검증을 할 수 있습니다. + +각 시뮬레이션은 블록의 수, 시드, 블록 사이즈와 같은 일련의 입력(예: flags)을 받아야 합니다. +flag의 리스트는 [여기](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/config.go#L32-L55) 에서 확인이 가능합니다. + +## 시뮬레이션 모드 + +다양한 입력값과 명령어 외에 시뮬레이터는 3가지 모드로 실행가능 합니다. + +1. 초기 상태, 모듈과 시뮬레이션의 입력값 등을 완전히 무작위(**pseudo-randomly**)로 생성합니다. +2. `genesis.json` 파일을 읽어 초기 상태와 모듈 입력값을 설정할 수 있습니다. 이 모드는 이미 실행되고 있는 블록체인에서 내보내기를 실행하여 그 상태에서 부터 시뮬레이션을 실행하기에 유용합니다. +3. `params.json` 파일을 읽어 모듈과 시뮬레이션 입력값을 설정할 수 있습니다. 이때 초기 상태는 무작위로 생성 됩니다. 이 모드를 사용하면 비록 초기 상태는 무작위로 생성이 될지라도 좀 더 통제된 시뮬레이션 환경구성이 가능합니다. 설정 가능한 리스트는 [여기](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/simulation/params.go#L44-L52) 에서 확인 가능합니다. + +::: 팁) +이 모드들은 상호 배타적이지 않습니다. 예를 들어 무작위로 초기 상태를 설정한 후(`1`모드) 수동으로 시뮬레이션 입력값을 생성(`3`모드)해도 무방합니다. +::: + +## 사용방법 + +다음은 일반적으로 시뮬레이션이 실행되는 예제입니다. 더 구체적인 예제를 찾으신다면 SDK [Makefile](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/Makefile#L251-L287) 을 확인하세요. + +```bash + $ go test -mod=readonly github.com/cosmos/cosmos-sdk/simapp \ + -run=TestApp \ + ... + -v -timeout 24h +``` + +## 디버그 팁들 + +다음은 시뮬레이션이 실패 할 때 어떻게 대처해야 할지에 대한 가이드입니다: + +- 시뮬레이터에 `-ExportStatePath` flag을 전달하여 실패한 height에서 앱 상태를 내보기 합니다. +- `-Verbose`을 사용하여 더 자세한 로그를 출력합니다. +- 시뮬레이션의 주기를 줄여 봅니다(`-Period`). 그렇게 하면 불변성 검증이 좀 더 자주 발생합니다. +- `-PrintAllInvariants`을 사용하여 모든 실패한 불변성을 출력해 봅니다. +- 다른 씨드(`-Seed`)를 사용합니다. 만일 다른 씨드를 사용했을 때도 같은 문제가 발생하지만 시뮬레이션 실행이 감소했다면 반복되는 시뮬레이션에 소용되는 시간을 획기적으로 줄일 수 있습니다. +- `-NumBlocks`을 줄여 봅니다. 문제가 발생했던 블록전에 앱 상태가 어땠는데 검증합니다. +- `-SimulateEveryOperation`을 사용하여 모든 오퍼레이션에 대하여 불변성 검증을 실행합니다. _주의_: 이렇게 할 경우 시뮬레이션 실행이 **굉장히** 느려질 수 있습니다. +- 오퍼레이션에 대하여 새로운 로그를 추가합니다. `Keeper`에 새롭게 [Logger](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/keeper/keeper.go#L66-L69) 가 정의되야 합니다. + +## SDK에 기반한 애플리케이션에서 시뮬레이션을 사용하세요 + +SDK에 기반한 애플리케이션에 시뮬레이션을 통합하는 방법 알아보기: + +- 애플리케이션 시뮬레이션 관리자 +- [모듈 개발: 시뮬레이션](../building-modules/simulator.md) +- 시뮬레이터 테스트 \ No newline at end of file From 9cd4bcb61dfa6941faee77b2600811015b92336c Mon Sep 17 00:00:00 2001 From: "nonvis@gmail.com" Date: Wed, 14 Jul 2021 18:41:06 +0900 Subject: [PATCH 3/3] docs(kr): core-telemetry --- docs/ko/core/telemetry.md | 132 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 docs/ko/core/telemetry.md diff --git a/docs/ko/core/telemetry.md b/docs/ko/core/telemetry.md new file mode 100644 index 000000000..661de4b4b --- /dev/null +++ b/docs/ko/core/telemetry.md @@ -0,0 +1,132 @@ + + +# 원격 측정 + +사용자가 원하는 다양한 데이터를 분석하여 애플리케이션과 모듈에 대한 상태를 원격으로 모니터 합니다. {synopsis} + +운용자와 개발자는 Cosmos SDK가 제공하는 `telemetry` 패키지를 사용하여 애플리케이션의 성능과 상태를 모니터 할 수 있습니다. +한개의 API endpoint를 `/metrics?format={text|prometheus}`에 설정하여 외부에 있는 Prometheus 서버가 데이터를 `text` 형태로 읽어 갈 수 있습니다. + +원격 측정이 활성화가 되면 [go-metrics](https://github.com/armon/go-metrics) 라이브러리를 통하여 측정항목들이 수집되어 API 호출을 통하여 외부에서 읽어갈 수 있습니다. + +예제: +```go +func EndBlocker(ctx sdk.Context, k keeper.Keeper) { + defer telemetry.ModuleMeasureSince(types.ModuleName, time.Now(), telemetry.MetricKeyEndBlocker) + + // ... +} +``` + +개발자들은 직접 `telemetry` 패키지를 사용하여 측정항목들을 감싸 알아보기 쉽게 라벨을 붙일 수 있고 아니면 직접 `go-metrics` 라이브러리를 사용할 수 있습니다. +하지만 측정항목들에 대하여 알맞은 맥락과 적절한 값들을 표기할 수 있는 `telemetry` 패키지 사용이 일반적으로 더 선호되는 방식입니다. + +Cosmos SDK는 측정항목들에 대하여 다음과 같은 타입을 지원합니다: +* 게이지 (gauges) +* 요약 (summaries) +* 카운터 (counters) + +## 라벨 (Labels) + +모듈의 몇가지 항목들은 그 이름이 자동으로 라벨로 붙게 됩니다 (예:`BeginBlock`). +또한 오퍼레이터는 `telemetry` 패키지를 사용하여 애플리케이션에 제공하는 측정항목들 대하여 글로벌 라벨을 지정할 수도 있습니다 (예: chain-id). +글로벌 라벨은 [name, value] 튜플로 리스트를 만들어 설정 가능합니다. + +예제: + +```toml +global-labels = [ + ["chain_id", "chain-OfXo4V"], +] +``` + +## 카디널리티 (Cardinality) + +카디널리티는 하나의 세트나 그룹안에 몇개의 유니크한 값들이 있는지를 나타내는 숫자인데 측정항목들을 얼마나 자세히 세분화하여 나타낼지 잘 고려가 되어야 보다 효율적으로 원격으로 값들을 읽어가거나 인텍싱 할 수 있습니다. + +개발자들은 특히 측정항목들에 대하여 세분화 할 때 유용한 값들을 나타낼 수 있도록 충분한 카디널리티를 사용해야 하지만 씽크(sink)의 리밋을 초과하지 않도록 조심해야 합니다. 일반적으로 카디널리티는 10을 넘지않도록 합니다. + +다음 측정항목들에 대해서는 충분한 세부사항과 알맞은 카디널리티를 가지고 있습니다: + +* 블록의 시작과 종료 시간 +* 사용한 트랜잭션 개스 +* 사용한 블록 개스 +* 새로 발급한 토큰 갯수 +* 새로 발급한 계정 갯수 + +하지만 다음 측정항목들은 너무 많은 카디널리티를 가지고 있어 크게 쓸모가 없어 보입니다: + +* 계좌 송금 액수 +* 특정 주소로부터 투표나 입금액수 + +## 지원되는 측정항목들 + +| 측정항목 | 설명 | 유니트 | 타입 | +|:--------------------------------|:------------------------------------------------------------------------------------------|:----------------|:--------| +| `tx_count` | `DeliverTx`를 통해 수행한 전체 트랜잭션 수 | tx | 카운터 | +| `tx_successful` | `DeliverTx`를 통해 성공적으로 수행한 트랜잭션 수 | tx | 카운터 | +| `tx_failed` | `DeliverTx`를 통해 실패한 트랜잭션 수 | tx | 카운터 | +| `tx_gas_used` | 트랜잭션이 사용한 개스 양 | gas | 게이지 | +| `tx_gas_wanted` | 트랜잭션이 요청한 개스 양 | gas | 게이지 | +| `tx_msg_send` | `MsgSend`를 통해 보낸 토큰수량 (per denom) | token | 게이지 | +| `tx_msg_withdraw_reward` | `MsgWithdrawDelegatorReward`를 통해 출금한 토큰수량 (per denom) | token | 게이지 | +| `tx_msg_withdraw_commission` | `MsgWithdrawValidatorCommission`를 통해 출금한 토큰수량 (per denom) | token | 게이지 | +| `tx_msg_delegate` | `MsgDelegate`를 통해 일임한 토큰수량 | token | 게이지 | +| `tx_msg_begin_unbonding` | `MsgUndelegate`를 통해 일임을 해제한 토큰수량 | token | 게이지 | +| `tx_msg_begin_begin_redelegate` | `MsgBeginRedelegate`를 통해 다시 일임한 토큰수량 | token | 게이지 | +| `tx_msg_ibc_transfer` | `MsgTransfer`를 통해 이체한 토큰수량 (source 혹은 sink chain) | token | 게이지 | +| `ibc_transfer_packet_receive` |`FungibleTokenPacketData`를 통해 수신한 토큰수량 (source 혹은 sink chain) | token | 게이지 | +| `new_account` | 신규 발행한 계좌 수 | account | 카운터 | +| `gov_proposal` | 거버넌스 제안 수 | proposal | 카운터 | +| `gov_vote` | 거버넌스 투표 수 | vote | 카운터 | +| `gov_deposit` | 거버넌스 입금 건수 | deposit | 카운터 | +| `staking_delegate` | 일임을 수행한 수 | delegation | 카운터 | +| `staking_undelegate` | 일임을 취소한 수 | undelegation | 카운터 | +| `staking_redelegate` | 다시 일임한 수 | redelegation | 카운터 | +| `ibc_transfer_send` | 체인(source 혹은 sink)에서 보낸 IBC 이체 수 | transfer | 카운터 | +| `ibc_transfer_receive` | 체인(source 혹은 sink)에서 수신한 IBC 이체 수 | transfer | 카운터 | +| `ibc_client_create` | 생성한 클라이언트 수 | create | 카운터 | +| `ibc_client_update` | 갱신한 클라이언트 수 | update | 카운터 | +| `ibc_client_upgrade` | 업그레이드 한 클라이언트 수 | upgrade | 카운터 | +| `ibc_client_misbehaviour` | 잘못된 행동을 한 클라이언트 수 | misbehaviour | 카운터 | +| `ibc_connection_open-init` | `OpenInit` 커넥션 수 | handshake | 카운터 | +| `ibc_connection_open-try` | `OpenTry` 커넥션 수 | handshake | 카운터 | +| `ibc_connection_open-ack` | `OpenAck` 커넥션 수 | handshake | 카운터 | +| `ibc_connection_open-confirm` | `OpenConfirm` 커넥션 수 | handshake | 카운터 | +| `ibc_channel_open-init` | `OpenInit` 채널 수 | handshake | 카운터 | +| `ibc_channel_open-try` | `OpenTry` 채널 수 | handshake | 카운터 | +| `ibc_channel_open-ack` | `OpenAck` 채널 수 | handshake | 카운터 | +| `ibc_channel_open-confirm` | `OpenConfirm` 채널 수 | handshake | 카운터 | +| `ibc_channel_close-init` | `CloseInit` 채널 수 | handshake | 카운터 | +| `ibc_channel_close-confirm` | `CloseConfirm` 채널 수 | handshake | 카운터 | +| `tx_msg_ibc_recv_packet` | IBC 패킷 수신 수 | packet | 카운터 | +| `tx_msg_ibc_acknowledge_packet` | 인정한 IBC 패킷 수 | acknowledgement | 카운터 | +| `ibc_timeout_packet` | 시간 만료된 IBC 패킷 수 | timeout | 카운터 | +| `abci_check_tx` | ABCI `CheckTx` 기간 | ms | 요약 | +| `abci_deliver_tx` | ABCI `DeliverTx` 기간 | ms | 요약 | +| `abci_commit` | ABCI `Commit` 기간 | ms | 요약 | +| `abci_query` | ABCI `Query` 기간 | ms | 요약 | +| `abci_begin_block` | ABCI `BeginBlock` 기간 | ms | 요약 | +| `abci_end_block` | ABCI `EndBlock` 기간 | ms | 요약 | +| `begin_blocker` | 모듈에 대한 `BeginBlock` 기간 | ms | 요약 | +| `end_blocker` | 모듈에 대한 `EndBlock` 기간 | ms | 요약 | +| `store_iavl_get` | IAVL `Store#Get` 통화시간 | ms | 요약 | +| `store_iavl_set` | IAVL `Store#Set` 통화시간 | ms | 요약 | +| `store_iavl_has` | IAVL `Store#Has` 통화시간 | ms | 요약 | +| `store_iavl_delete` | IAVL `Store#Delete` 통화시간 | ms | 요약 | +| `store_iavl_commit` | IAVL `Store#Commit` 통화시간 | ms | 요약 | +| `store_iavl_query` | IAVL `Store#Query` 통화시간 | ms | 요약 | +| `store_gaskv_get` | GasKV `Store#Get` 통화시간 | ms | 요약 | +| `store_gaskv_set` | GasKV `Store#Set` 통화시간 | ms | 요약 | +| `store_gaskv_has` | GasKV `Store#Has` 통화시간 | ms | 요약 | +| `store_gaskv_delete` | GasKV `Store#Delete` 통화시간 | ms | 요약 | +| `store_cachekv_get` | CacheKV `Store#Get` 통화시간 | ms | 요약 | +| `store_cachekv_set` | CacheKV `Store#Set` 통화시간 | ms | 요약 | +| `store_cachekv_write` | CacheKV `Store#Write` 통화시간 | ms | 요약 | +| `store_cachekv_delete` | CacheKV `Store#Delete` 통화시간 | ms | 요약 | + +## 다음 {hide} + +[object-capability](./ocap.md) {hide} \ No newline at end of file