Skip to content

Document computation profiling and download of all deployed contracts #906

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document computation profiling and download of all deployed contracts #906

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
98 changes: 73 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
·
<a href="https://github.com/onflow/flow-emulator/blob/master/CONTRIBUTING.md">Contribute</a>
</p>
</p>
<br />
<br />

Expand Down Expand Up @@ -48,7 +47,7 @@ values.
| `--verbose`, `-v` | `FLOW_VERBOSE` | `false` | Enable verbose logging (useful for debugging) |
| `--log-format` | `FLOW_LOGFORMAT` | `text` | Output log format (valid values `text`, `JSON`) |
| `--block-time`, `-b` | `FLOW_BLOCKTIME` | `0` | Time between sealed blocks. Valid units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h` |
| `--contracts` | `FLOW_WITHCONTRACTS` | `false` | Start with contracts like [ExampleNFT](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) when the emulator starts |
| `--contracts` | `FLOW_WITHCONTRACTS` | `false` | Start with contracts like [ExampleNFT](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) when the emulator starts |
| `--service-priv-key` | `FLOW_SERVICEPRIVATEKEY` | random | Private key used for the [service account](https://docs.onflow.org/flow-token/concepts/#flow-service-account) |
| `--service-sig-algo` | `FLOW_SERVICEKEYSIGALGO` | `ECDSA_P256` | Service account key [signature algorithm](https://docs.onflow.org/cadence/language/crypto/#signing-algorithms) |
| `--service-hash-algo` | `FLOW_SERVICEKEYHASHALGO` | `SHA3_256` | Service account key [hash algorithm](https://docs.onflow.org/cadence/language/crypto/#hashing) |
Expand All @@ -64,7 +63,7 @@ values.
| `--storage-limit` | `FLOW_STORAGELIMITENABLED` | `true` | Enable [account storage limit](https://docs.onflow.org/cadence/language/accounts/#storage-limit) |
| `--storage-per-flow` | `FLOW_STORAGEMBPERFLOW` | | Specify size of the storage in MB for each FLOW in account balance. Default value from the flow-go |
| `--min-account-balance` | `FLOW_MINIMUMACCOUNTBALANCE` | | Specify minimum balance the account must have. Default value from the flow-go |
| `--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 |
| `--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 |
| `--transaction-max-gas-limit` | `FLOW_TRANSACTIONMAXGASLIMIT` | `9999` | Maximum [gas limit for transactions](https://docs.onflow.org/flow-go-sdk/building-transactions/#gas-limit) |
| `--script-gas-limit` | `FLOW_SCRIPTGASLIMIT` | `100000` | Specify gas limit for script execution |
| `--coverage-reporting` | `FLOW_COVERAGEREPORTING` | `false` | Enable Cadence code coverage reporting |
Expand All @@ -73,10 +72,11 @@ values.
| `--host` | `FLOW_HOST` | ` ` | Host to listen on for emulator GRPC/REST/Admin servers (default: All Interfaces) |
| `--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' |
| `--redis-url` | `FLOW_REDIS_URL` | '' | Redis-server URL for persisting redis storage backend ( `redis://[[username:]password@]host[:port][/database]` ) |
| `--fork-host` | `FLOW_FORK_HOST` | '' | gRPC access node address (`host:port`) to fork from |
| `--fork-height` | `FLOW_FORK_HEIGHT` | `0` | Block height to pin the fork (defaults to latest sealed) |
| `--fork-host` | `FLOW_FORK_HOST` | '' | gRPC access node address (`host:port`) to fork from |
| `--fork-height` | `FLOW_FORK_HEIGHT` | `0` | Block height to pin the fork (defaults to latest sealed) |
| `--legacy-upgrade` | `FLOW_LEGACYUPGRADE` | `false` | Enable upgrading of legacy contracts |
| `--computation-reporting` | `FLOW_COMPUTATIONREPORTING` | `false` | Enable computation reporting for Cadence scripts & transactions |
| `--computation-reporting` | `FLOW_COMPUTATIONREPORTING` | `false` | Enable computation reporting for Cadence programs |
| `--computation-profiling` | `FLOW_COMPUTATIONPROFILING` | `false` | Enable computation profiling for Cadence programs |
| `--checkpoint-dir` | `FLOW_CHECKPOINTDIR` | '' | Checkpoint directory to load the emulator state from, if starting the emulator from a checkpoint |
| `--state-hash` | `FLOW_STATEHASH` | '' | State hash of the checkpoint, if starting the emulator from a checkpoint |

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

```go
account, err := blockchain.GetAccount(address)
account, err := blockchain.GetAccount(address)
```

## Rolling back state to blockheight
Expand All @@ -158,12 +158,12 @@ Note: it is only possible to roll back state to a height that was previously exe
To pin the starting block height when using a fork, use the `--fork-height` flag.

## Managing emulator state
It's possible to manage emulator state by using the admin API. You can at any point
create a new named snapshot of the state and then at any later point revert emulator
state to that reference.
It's possible to manage emulator state by using the admin API. You can at any point
create a new named snapshot of the state and then at any later point revert emulator
state to that reference.

In order to use the state management functionality you need to run the emulator with persistent state:
```bash
```sh
flow emulator --persist
```

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

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

```bash
```sh
flow emulator --coverage-reporting
```

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

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

```bash
```sh
curl -XPUT 'http://localhost:8080/emulator/codeCoverage/reset'
```

Expand All @@ -225,23 +225,65 @@ transactions and scripts.

## Cadence Computation Reporting

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

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

```bash
```sh
flow emulator --computation-reporting
```

To view the computation report, visit this URL: http://localhost:8080/emulator/computationReport
To view the computation report, visit this URL: http://localhost:8080/emulator/computationReport.

The computation report can be reset by sending a PUT request to the following URL:
http://localhost:8080/emulator/computationReport/reset.

## Cadence Computation Profiling

The admin API includes an endpoint for viewing the computation profile for Cadence programs.

In order to use this functionality you need to run the emulator with the respective flag which enables computation
profiling:

```sh
flow emulator --computation-profiling
```

To view the computation report, visit this URL: http://localhost:8080/emulator/computationProfile.

This downloads a pprof file that can be analyzed using https://github.com/google/pprof.

To view the profile in a web browser, run the following command:

```sh
pprof -http=:8081 profile.pprof
```

Then open your web browser and navigate to `http://localhost:8081`.

To view the source code of the functions, first [download all deployed contracts](#downloading-all-deployed-contracts),
extract the ZIP file, and place the `contracts` folder in the same directory where you run the pprof command.

Then run the pprof command with the `-source_path` flag:

```sh
pprof -source_path=contracts -http=:8081 profile.pprof
```

The computation profile can be reset by sending a PUT request to the following URL:
http://localhost:8080/emulator/computationProfile/reset.

## Downloading all deployed contracts

To download all deployed contracts as a ZIP file, visit this URL: http://localhost:8080/emulator/allContracts

## Running the emulator with Docker

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

```bash
```sh
docker run -p 3569:3569 -p 8080:8080 -e FLOW_HOST=0.0.0.0 gcr.io/flow-container-registry/emulator
```

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

*Custom Configuration Example:*

```bash
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
```sh
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
```

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

## Emulating mainnet and testnet transactions

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

```
```sh
flow emulator --fork-host access.mainnet.nodes.onflow.org:9000
flow emulator --fork-host access.mainnet.nodes.onflow.org:9000 --fork-height 12345
```

Please note, that the actual execution on the real network may differ depending on the exact state when the transaction is
executed.
Please note, that the actual execution on the real network may differ depending on the exact state when the transaction
is executed.

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.
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.

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

```cadence
```cadence
#debugger()
```

Expand Down
Loading