Skip to content

Commit 97a6458

Browse files
turbolentturbolent
committed
document computation profiling and download of all deployed contracts
1 parent 6074a13 commit 97a6458

File tree

1 file changed

+73
-25
lines changed

1 file changed

+73
-25
lines changed

‎README.md‎

Lines changed: 73 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414
·
1515
<a href="https://github.com/onflow/flow-emulator/blob/master/CONTRIBUTING.md">Contribute</a>
1616
</p>
17-
</p>
1817
<br />
1918
<br />
2019

@@ -48,7 +47,7 @@ values.
4847
| `--verbose`, `-v` | `FLOW_VERBOSE` | `false` | Enable verbose logging (useful for debugging) |
4948
| `--log-format` | `FLOW_LOGFORMAT` | `text` | Output log format (valid values `text`, `JSON`) |
5049
| `--block-time`, `-b` | `FLOW_BLOCKTIME` | `0` | Time between sealed blocks. Valid units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h` |
51-
| `--contracts` | `FLOW_WITHCONTRACTS` | `false` | Start with contracts like [ExampleNFT](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) when the emulator starts |
50+
| `--contracts` | `FLOW_WITHCONTRACTS` | `false` | Start with contracts like [ExampleNFT](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) when the emulator starts |
5251
| `--service-priv-key` | `FLOW_SERVICEPRIVATEKEY` | random | Private key used for the [service account](https://docs.onflow.org/flow-token/concepts/#flow-service-account) |
5352
| `--service-sig-algo` | `FLOW_SERVICEKEYSIGALGO` | `ECDSA_P256` | Service account key [signature algorithm](https://docs.onflow.org/cadence/language/crypto/#signing-algorithms) |
5453
| `--service-hash-algo` | `FLOW_SERVICEKEYHASHALGO` | `SHA3_256` | Service account key [hash algorithm](https://docs.onflow.org/cadence/language/crypto/#hashing) |
@@ -64,7 +63,7 @@ values.
6463
| `--storage-limit` | `FLOW_STORAGELIMITENABLED` | `true` | Enable [account storage limit](https://docs.onflow.org/cadence/language/accounts/#storage-limit) |
6564
| `--storage-per-flow` | `FLOW_STORAGEMBPERFLOW` | | Specify size of the storage in MB for each FLOW in account balance. Default value from the flow-go |
6665
| `--min-account-balance` | `FLOW_MINIMUMACCOUNTBALANCE` | | Specify minimum balance the account must have. Default value from the flow-go |
67-
| `--transaction-fees` | `FLOW_TRANSACTIONFEESENABLED` | `false` | Enable variable transaction fees and execution effort metering <br> as described in [Variable Transaction Fees: Execution Effort](https://github.com/onflow/flow/pull/753) FLIP |
66+
| `--transaction-fees` | `FLOW_TRANSACTIONFEESENABLED` | `false` | Enable variable transaction fees and execution effort metering <br> as described in [Variable Transaction Fees: Execution Effort](https://github.com/onflow/flow/pull/753) FLIP |
6867
| `--transaction-max-gas-limit` | `FLOW_TRANSACTIONMAXGASLIMIT` | `9999` | Maximum [gas limit for transactions](https://docs.onflow.org/flow-go-sdk/building-transactions/#gas-limit) |
6968
| `--script-gas-limit` | `FLOW_SCRIPTGASLIMIT` | `100000` | Specify gas limit for script execution |
7069
| `--coverage-reporting` | `FLOW_COVERAGEREPORTING` | `false` | Enable Cadence code coverage reporting |
@@ -73,10 +72,11 @@ values.
7372
| `--host` | `FLOW_HOST` | ` ` | Host to listen on for emulator GRPC/REST/Admin servers (default: All Interfaces) |
7473
| `--chain-id` | `FLOW_CHAINID` | `emulator` | Chain to simulate, if 'mainnet' or 'testnet' values are used, you will be able to run transactions against that network and a local fork will be created. Valid values are: 'emulator', 'testnet', 'mainnet' |
7574
| `--redis-url` | `FLOW_REDIS_URL` | '' | Redis-server URL for persisting redis storage backend ( `redis://[[username:]password@]host[:port][/database]` ) |
76-
| `--fork-host` | `FLOW_FORK_HOST` | '' | gRPC access node address (`host:port`) to fork from |
77-
| `--fork-height` | `FLOW_FORK_HEIGHT` | `0` | Block height to pin the fork (defaults to latest sealed) |
75+
| `--fork-host` | `FLOW_FORK_HOST` | '' | gRPC access node address (`host:port`) to fork from |
76+
| `--fork-height` | `FLOW_FORK_HEIGHT` | `0` | Block height to pin the fork (defaults to latest sealed) |
7877
| `--legacy-upgrade` | `FLOW_LEGACYUPGRADE` | `false` | Enable upgrading of legacy contracts |
79-
| `--computation-reporting` | `FLOW_COMPUTATIONREPORTING` | `false` | Enable computation reporting for Cadence scripts & transactions |
78+
| `--computation-reporting` | `FLOW_COMPUTATIONREPORTING` | `false` | Enable computation reporting for Cadence programs |
79+
| `--computation-profiling` | `FLOW_COMPUTATIONPROFILING` | `false` | Enable computation profiling for Cadence programs |
8080
| `--checkpoint-dir` | `FLOW_CHECKPOINTDIR` | '' | Checkpoint directory to load the emulator state from, if starting the emulator from a checkpoint |
8181
| `--state-hash` | `FLOW_STATEHASH` | '' | State hash of the checkpoint, if starting the emulator from a checkpoint |
8282

@@ -136,7 +136,7 @@ blockchain, err := emulator.NewBlockchain(opts...)
136136
You can then access all methods of the blockchain like so:
137137

138138
```go
139-
account, err := blockchain.GetAccount(address)
139+
account, err := blockchain.GetAccount(address)
140140
```
141141

142142
## Rolling back state to blockheight
@@ -158,12 +158,12 @@ Note: it is only possible to roll back state to a height that was previously exe
158158
To pin the starting block height when using a fork, use the `--fork-height` flag.
159159
160160
## Managing emulator state
161-
It's possible to manage emulator state by using the admin API. You can at any point
162-
create a new named snapshot of the state and then at any later point revert emulator
163-
state to that reference.
161+
It's possible to manage emulator state by using the admin API. You can at any point
162+
create a new named snapshot of the state and then at any later point revert emulator
163+
state to that reference.
164164
165165
In order to use the state management functionality you need to run the emulator with persistent state:
166-
```bash
166+
```sh
167167
flow emulator --persist
168168
```
169169

@@ -201,15 +201,15 @@ The admin API includes endpoints for viewing and managing Cadence code coverage.
201201

202202
In order to use this functionality you need to run the emulator with the respective flag which enables code coverage:
203203

204-
```bash
204+
```sh
205205
flow emulator --coverage-reporting
206206
```
207207

208208
To view the code coverage report, visit this URL: http://localhost:8080/emulator/codeCoverage
209209

210210
To flush/reset the collected code coverage report, run the following command:
211211

212-
```bash
212+
```sh
213213
curl -XPUT 'http://localhost:8080/emulator/codeCoverage/reset'
214214
```
215215

@@ -225,23 +225,65 @@ transactions and scripts.
225225

226226
## Cadence Computation Reporting
227227

228-
The admin API includes an endpoint for viewing the Cadence computation reports for scripts & transactions.
228+
The admin API includes an endpoint for viewing the computation reports for Cadence programs.
229229

230230
In order to use this functionality you need to run the emulator with the respective flag which enables computation
231231
reporting:
232232

233-
```bash
233+
```sh
234234
flow emulator --computation-reporting
235235
```
236236

237-
To view the computation report, visit this URL: http://localhost:8080/emulator/computationReport
237+
To view the computation report, visit this URL: http://localhost:8080/emulator/computationReport.
238+
239+
The computation report can be reset by sending a PUT request to the following URL:
240+
http://localhost:8080/emulator/computationReport/reset.
241+
242+
## Cadence Computation Profiling
243+
244+
The admin API includes an endpoint for viewing the computation profile for Cadence programs.
245+
246+
In order to use this functionality you need to run the emulator with the respective flag which enables computation
247+
profiling:
248+
249+
```sh
250+
flow emulator --computation-profiling
251+
```
252+
253+
To view the computation report, visit this URL: http://localhost:8080/emulator/computationProfile.
254+
255+
This downloads a pprof file that can be analyzed using https://github.com/google/pprof.
256+
257+
To view the profile in a web browser, run the following command:
258+
259+
```sh
260+
pprof -http=:8081 profile.pprof
261+
```
262+
263+
Then open your web browser and navigate to `http://localhost:8081`.
264+
265+
To view the source code of the functions, first [download all deployed contracts](#downloading-all-deployed-contracts),
266+
extract the ZIP file, and place the `contracts` folder in the same directory where you run the pprof command.
267+
268+
Then run the pprof command with the `-source_path` flag:
269+
270+
```sh
271+
pprof -source_path=contracts -http=:8081 profile.pprof
272+
```
273+
274+
The computation profile can be reset by sending a PUT request to the following URL:
275+
http://localhost:8080/emulator/computationProfile/reset.
276+
277+
## Downloading all deployed contracts
278+
279+
To download all deployed contracts as a ZIP file, visit this URL: http://localhost:8080/emulator/allContracts
238280

239281
## Running the emulator with Docker
240282

241283
Docker builds for the emulator are automatically built and pushed to
242284
`gcr.io/flow-container-registry/emulator`, tagged by commit and semantic version. You can also build the image locally.
243285

244-
```bash
286+
```sh
245287
docker run -p 3569:3569 -p 8080:8080 -e FLOW_HOST=0.0.0.0 gcr.io/flow-container-registry/emulator
246288
```
247289

@@ -250,8 +292,13 @@ You can pass any environment variable by using `-e` docker flag and pass the val
250292

251293
*Custom Configuration Example:*
252294

253-
```bash
254-
docker run -p 3569:3569 -p 8080:8080 -e FLOW_HOST=0.0.0.0 -e FLOW_PORT=9001 -e FLOW_VERBOSE=true -e FLOW_SERVICEPRIVATEKEY=<hex-encoded key> gcr.io/flow-container-registry/emulator
295+
```sh
296+
docker run -p 3569:3569 -p 8080:8080 \
297+
-e FLOW_HOST=0.0.0.0 \
298+
-e FLOW_PORT=9001 \
299+
-e FLOW_VERBOSE=true \
300+
-e FLOW_SERVICEPRIVATEKEY=<hex-encoded key> \
301+
gcr.io/flow-container-registry/emulator
255302
```
256303

257304
To generate a service key, use the `keys generate` command in the Flow CLI.
@@ -262,20 +309,21 @@ flow keys generate
262309

263310
## Emulating mainnet and testnet transactions
264311

265-
The emulator allows you to simulate the execution of transactions as if
312+
The emulator allows you to simulate the execution of transactions as if
266313
performed on the Mainnet or Testnet. To activate this feature,
267314
you must specify the network name for the chain ID flag and the RPC host
268315
to connect to.
269316

270-
```
317+
```sh
271318
flow emulator --fork-host access.mainnet.nodes.onflow.org:9000
272319
flow emulator --fork-host access.mainnet.nodes.onflow.org:9000 --fork-height 12345
273320
```
274321

275-
Please note, that the actual execution on the real network may differ depending on the exact state when the transaction is
276-
executed.
322+
Please note, that the actual execution on the real network may differ depending on the exact state when the transaction
323+
is executed.
277324

278-
By default, the forked network will start from the latest sealed block when the emulator is started. You can specify a different starting block height by using the `--fork-height` flag.
325+
By default, the forked network will start from the latest sealed block when the emulator is started.
326+
You can specify a different starting block height by using the `--fork-height` flag.
279327

280328
You can also store all of your changes and cached registers to a persistent db by using the `--persist` flag,
281329
along with the other SQLite settings.
@@ -289,7 +337,7 @@ verification. Then submit transactions from any account using any valid private
289337
To debug any transactions sent via VSCode or Flow CLI, you can use the `debugger` pragma.
290338
This will cause execution to pause at the debugger for any transaction or script which includes that pragma.
291339

292-
```cadence
340+
```cadence
293341
#debugger()
294342
```
295343

0 commit comments

Comments
 (0)