From db1f91c07d6f8046bd5946b8857a9dfa72f134ae Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:42:28 -0800 Subject: [PATCH 01/12] Create profiling page --- .../advanced-concepts/computation-profiling.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/build/cadence/advanced-concepts/computation-profiling.md diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md new file mode 100644 index 0000000000..22f2669e81 --- /dev/null +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -0,0 +1,18 @@ +--- +title: Cadence Computation Profiling +description: This guide provides comprehensive instructions for using the computation profiling and reporting features in the Flow Emulator. These tools help Cadence developers analyze and optimize their smart contracts by understanding computational costs and identifying performance bottlenecks. +keywords: + - computation profiling + - Flow Emulator + - smart contract optimization + - performance analysis + - computational costs + - Cadence + - profiling + - performance bottlenecks +sidebar_position: 1 +--- + +# Cadence Computation Profiling + +{/* Content coming soon */} From 5b8ba0b005033aec700b791536132155b447a688 Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:42:50 -0800 Subject: [PATCH 02/12] Add guide content --- .../computation-profiling.md | 483 +++++++++++++++++- 1 file changed, 482 insertions(+), 1 deletion(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 22f2669e81..3eb89c63b7 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -15,4 +15,485 @@ sidebar_position: 1 # Cadence Computation Profiling -{/* Content coming soon */} +This guide provides comprehensive instructions for using the computation profiling and reporting features in the Flow Emulator. These tools help Cadence developers analyze and optimize their smart contracts by understanding computational costs and identifying performance bottlenecks. + +## Table of Contents + +- [Introduction](#introduction) +- [Prerequisites](#prerequisites) +- [Computation Reporting](#computation-reporting) + - [Enabling Computation Reporting](#enabling-computation-reporting) + - [Viewing Computation Reports](#viewing-computation-reports) +- [Computation Profiling (pprof)](#computation-profiling-pprof) + - [Enabling Computation Profiling](#enabling-computation-profiling) + - [Downloading the Profile](#downloading-the-profile) + - [Viewing Profiles with pprof](#viewing-profiles-with-pprof) + - [Viewing Source Code in pprof](#viewing-source-code-in-pprof) + - [Resetting Computation Profiles](#resetting-computation-profiles) +- [Using Source File Pragmas](#using-source-file-pragmas) +- [Practical Examples](#practical-examples) + - [Profiling a Simple Transaction](#profiling-a-simple-transaction) + - [Identifying Performance Bottlenecks](#identifying-performance-bottlenecks) + - [Comparing Computation Costs](#comparing-computation-costs) +- [Best Practices](#best-practices) +- [API Reference](#api-reference) +- [Troubleshooting](#troubleshooting) +- [Related Features](#related-features) + +## Introduction + +When developing smart contracts on Flow, understanding computational costs is essential for: + +- **Performance Optimization**: Identify slow operations and optimize your code +- **Cost Awareness**: Understand how much computation your transactions and scripts consume +- **Bottleneck Identification**: Pinpoint exactly where your code spends the most resources + +The Flow Emulator provides two complementary tools for this purpose: + +| Feature | Output | Best For | +|---------|--------|----------| +| **Computation Reporting** | JSON report with detailed intensities | Quick numerical analysis, CI/CD integration, automated testing | +| **Computation Profiling** | pprof-compatible flame graphs | Visual analysis, deep-dive debugging, call stack exploration | + +## Prerequisites + +1. **Flow CLI** installed ([installation guide](https://docs.onflow.org/flow-cli/install/)) + +2. **[pprof tool](https://github.com/google/pprof)** (for computation profiling): + + ```bash + go install github.com/google/pprof@latest + ``` + +## Computation Reporting + +Computation reporting provides a JSON-based view of computational costs for all executed transactions and scripts. + +### Enabling Computation Reporting + +Start the emulator with the `--computation-reporting` flag: + +```bash +flow emulator --computation-reporting +``` + +### Viewing Computation Reports + +Once enabled, access the computation report at: + +``` +http://localhost:8080/emulator/computationReport +``` + +The report returns a JSON object with the following structure: + +```json +{ + "scripts": { + "": { + "path": "scripts/myScript.cdc", + "computation": 1250, + "intensities": { + "Statement": 45, + "FunctionInvocation": 12, + "GetValue": 8 + }, + "memory": 2048, + "source": "access(all) fun main(): Int { ... }", + "arguments": ["0x1"] + } + }, + "transactions": { + "": { + "path": "transactions/myTransaction.cdc", + "computation": 3500, + "intensities": { + "Statement": 120, + "EmitEvent": 5, + "SetValue": 15 + }, + "memory": 8192, + "source": "transaction { ... }", + "arguments": ["100.0"] + } + } +} +``` + +#### Report Fields + +| Field | Description | +|-------|-------------| +| `path` | Source file path (set via `#sourceFile` pragma) | +| `computation` | Total computation units used | +| `intensities` | Count of each operation type performed | +| `memory` | Estimated memory usage | +| `source` | Original Cadence source code | +| `arguments` | Arguments passed to the transaction/script | + +### Understanding Computation Intensities + +The `intensities` map shows how many times each operation type was performed. The keys are human-readable names like `Statement`, `Loop`, `FunctionInvocation`, `GetValue`, `SetValue`, `EmitEvent`, etc. + +The total `computation` value is calculated by multiplying each intensity by its corresponding weight (defined by the network) and summing the results. When optimizing, look for operations with high counts - reducing these will lower your total computation cost. + +## Computation Profiling (pprof) + +Computation profiling generates pprof-compatible profiles that can be visualized as flame graphs, providing a powerful way to understand your code's execution patterns. + +### Enabling Computation Profiling + +Start the emulator with the `--computation-profiling` flag: + +```bash +flow emulator --computation-profiling +``` + +> **Note**: You can enable both `--computation-reporting` and `--computation-profiling` simultaneously if you need both types of analysis. + +### Downloading the Profile + +After executing transactions and scripts, download the profile from: + +``` +http://localhost:8080/emulator/computationProfile +``` + +This downloads a `profile.pprof` file containing the aggregated computation profile. + +Using curl: + +```bash +curl -o profile.pprof http://localhost:8080/emulator/computationProfile +``` + +### Viewing Profiles with pprof + +Open the profile in an interactive web interface: + +```bash +pprof -http=:8081 profile.pprof +``` + +Then navigate to `http://localhost:8081` in your browser. + +#### Available Views + +The pprof web interface provides several visualization options: + +| View | Description | +|------|-------------| +| **Flame Graph** | Visual representation of call stacks with computation costs | +| **Graph** | Directed graph showing call relationships | +| **Top** | List of functions sorted by computation usage | +| **Source** | Source code annotated with computation costs | +| **Peek** | Callers and callees of selected functions | + +### Viewing Source Code in pprof + +To see Cadence source code annotated with computation costs: + +1. **Download all deployed contracts**: + + ```bash + curl -o contracts.zip http://localhost:8080/emulator/allContracts + ``` + +2. **Extract the ZIP file into a `contracts` folder**: + + ```bash + mkdir -p contracts + unzip contracts.zip -d contracts + ``` + +3. **Run pprof with the source path**: + + ```bash + pprof -source_path=contracts -http=:8081 profile.pprof + ``` + +Now when you view the "Source" tab in pprof, you'll see your Cadence code with line-by-line computation annotations. + +### Resetting Computation Profiles + +To clear the accumulated profile data (useful between test runs): + +```bash +curl -X PUT http://localhost:8080/emulator/computationProfile/reset +``` + +## Using Source File Pragmas + +The `#sourceFile` pragma improves report readability by associating your code with meaningful file paths. Without it, reports show generic identifiers. + +### Usage + +Add the pragma at the beginning of your transaction or script: + +```cadence +#sourceFile("transactions/transfer_tokens.cdc") + +transaction(amount: UFix64, recipient: Address) { + prepare(signer: auth(Storage) &Account) { + // Transfer logic + } +} +``` + +For scripts: + +```cadence +#sourceFile("scripts/get_balance.cdc") + +access(all) fun main(address: Address): UFix64 { + return getAccount(address).balance +} +``` + +### Benefits + +- Reports show file paths instead of generic IDs +- Easier to correlate computation costs with source files +- Better integration with pprof source views +- Useful for tracking costs across multiple files in a project + +## Practical Examples + +### Profiling a Simple Transaction + +Let's profile a simple NFT minting transaction. + +**1. Start the emulator with profiling enabled:** + +```bash +flow emulator --computation-profiling --computation-reporting +``` + +**2. Create a transaction file (`transactions/mint_nft.cdc`):** + +```cadence +#sourceFile("transactions/mint_nft.cdc") + +import NonFungibleToken from 0xf8d6e0586b0a20c7 +import ExampleNFT from 0xf8d6e0586b0a20c7 + +transaction { + prepare(signer: auth(Storage) &Account) { + let collection = signer.storage.borrow<&ExampleNFT.Collection>( + from: ExampleNFT.CollectionStoragePath + ) ?? panic("Could not borrow collection") + + collection.deposit(token: <- ExampleNFT.mintNFT()) + } +} +``` + +**3. Execute the transaction:** + +```bash +flow transactions send transactions/mint_nft.cdc +``` + +**4. View the computation report:** + +```bash +curl http://localhost:8080/emulator/computationReport | jq +``` + +**5. Analyze with pprof:** + +```bash +curl -o profile.pprof http://localhost:8080/emulator/computationProfile +pprof -http=:8081 profile.pprof +``` + +### Identifying Performance Bottlenecks + +Consider a script that iterates over a large collection: + +```cadence +#sourceFile("scripts/find_expensive.cdc") + +access(all) fun main(address: Address): [UInt64] { + let account = getAccount(address) + let collection = account.capabilities.borrow<&{NonFungibleToken.Collection}>( + /public/NFTCollection + ) ?? panic("Could not borrow collection") + + let ids = collection.getIDs() + var result: [UInt64] = [] + + // Potentially expensive loop + for id in ids { + let nft = collection.borrowNFT(id) + if nft != nil { + result.append(id) + } + } + + return result +} +``` + +After profiling, you might see high values for: +- `Loop`: Many iterations +- `FunctionInvocation`: Repeated `borrowNFT` calls +- `GetValue`: Multiple storage reads + +**Optimization strategies:** +- Use pagination to limit iterations per call +- Cache results when possible +- Consider restructuring data for more efficient access + +### Comparing Computation Costs + +You can compare two implementation approaches by: + +**1. Reset the report between tests:** + +```bash +curl -X PUT http://localhost:8080/emulator/computationProfile/reset +``` + +**2. Run implementation A and record the computation:** + +```bash +flow transactions send approach_a.cdc +curl http://localhost:8080/emulator/computationReport > report_a.json +``` + +**3. Reset and test implementation B:** + +```bash +curl -X PUT http://localhost:8080/emulator/computationProfile/reset +flow transactions send approach_b.cdc +curl http://localhost:8080/emulator/computationReport > report_b.json +``` + +**4. Compare the `computation` values in both reports.** + +## Best Practices + +1. **Profile early and often**: Don't wait until production to understand your computation costs. + +2. **Use the right tool for the job**: + - **Computation Reporting**: Quick checks, automated tests, CI/CD pipelines + - **Computation Profiling**: Deep analysis, visual exploration, optimization work + +3. **Reset between isolated tests**: Always reset profiles when comparing different implementations or testing in isolation. + +4. **Use `#sourceFile` consistently**: Add pragmas to all your transactions and scripts for better debugging and reporting. + +5. **Consider compute limits**: Be aware of the emulator's compute limits: + - `--transaction-max-compute-limit` (default: 9999) + - `--script-compute-limit` (default: 100000) + +6. **Profile realistic scenarios**: Test with realistic data volumes and usage patterns. + +7. **Monitor expensive operations**: Pay attention to high-cost operations like: + - Large loops + - Frequent storage reads/writes (`GetValue`, `SetValue`) + - Cryptographic operations (`Hash`, `VerifySignature`) + - Event emissions (`EmitEvent`) + +## API Reference + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/emulator/computationReport` | GET | View computation report (JSON) | +| `/emulator/computationProfile` | GET | Download pprof profile | +| `/emulator/computationProfile/reset` | PUT | Reset computation profile | +| `/emulator/allContracts` | GET | Download all deployed contracts (ZIP) | + +### Example API Calls + +```bash +# Get computation report +curl http://localhost:8080/emulator/computationReport + +# Download pprof profile +curl -o profile.pprof http://localhost:8080/emulator/computationProfile + +# Reset computation profile +curl -X PUT http://localhost:8080/emulator/computationProfile/reset + +# Download all contracts +curl -o contracts.zip http://localhost:8080/emulator/allContracts +``` + +## Troubleshooting + +### Profile endpoint returns 404 + +**Problem**: Accessing `/emulator/computationProfile` returns a 404 error. + +**Solution**: Make sure you started the emulator with `--computation-profiling`: + +```bash +flow emulator --computation-profiling +``` + +### Empty profile + +**Problem**: The downloaded profile is empty or has no useful data. + +**Solution**: Make sure you've executed at least one transaction or script after starting the emulator. The profile only contains data for executed code. + +### Source code not showing in pprof + +**Problem**: The pprof source view doesn't display your Cadence code. + +**Solution**: +1. Download the contracts ZIP: `curl -o contracts.zip http://localhost:8080/emulator/allContracts` +2. Extract to a `contracts` folder in your working directory +3. Run pprof with the source path: `pprof -source_path=contracts -http=:8081 profile.pprof` + +### High memory usage + +**Problem**: The emulator uses increasing memory over time. + +**Solution**: Periodically reset computation profiles to free accumulated data: + +```bash +curl -X PUT http://localhost:8080/emulator/computationProfile/reset +``` + +### Reports not showing file paths + +**Problem**: The `path` field in reports is empty. + +**Solution**: Add the `#sourceFile` pragma to your transactions and scripts: + +```cadence +#sourceFile("path/to/your/file.cdc") +``` + +## Related Features + +### Code Coverage Reporting + +The emulator also supports Cadence code coverage reporting, which complements computation profiling: + +```bash +flow emulator --coverage-reporting +``` + +View coverage at: `http://localhost:8080/emulator/codeCoverage` + +Learn more in the [README](../README.md#cadence-code-coverage). + +### Debugger + +For step-through debugging of Cadence code, use the `#debug()` pragma: + +```cadence +#debug() + +transaction { + prepare(signer: &Account) { + // Execution pauses here for debugging + } +} +``` + +This works with VSCode and Flow CLI debugging tools. From 4513583224f2c834fc881c783552fa5221bf6b28 Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:43:33 -0800 Subject: [PATCH 03/12] Change link --- docs/build/cadence/advanced-concepts/computation-profiling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 3eb89c63b7..f3153dbf76 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -57,7 +57,7 @@ The Flow Emulator provides two complementary tools for this purpose: ## Prerequisites -1. **Flow CLI** installed ([installation guide](https://docs.onflow.org/flow-cli/install/)) +1. **Flow CLI** installed ([installation guide](../../tools/flow-cli/install.md)) 2. **[pprof tool](https://github.com/google/pprof)** (for computation profiling): From 531a08a67f1b065eddeb9cbf753930185926fc17 Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:47:09 -0800 Subject: [PATCH 04/12] Add forking bubble --- .../cadence/advanced-concepts/computation-profiling.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index f3153dbf76..86b11562b0 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -77,6 +77,12 @@ Start the emulator with the `--computation-reporting` flag: flow emulator --computation-reporting ``` +:::info + +For more accurate computation numbers that reflect real network conditions, consider using [emulator fork testing](../../../blockchain-development-tutorials/cadence/emulator-fork-testing/index.md). Forking allows you to profile against actual Mainnet or Testnet state without requiring a full emulator environment setup. + +::: + ### Viewing Computation Reports Once enabled, access the computation report at: From f990ebb8b77af0938f9c438f5aa371f4de9a2d8c Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:51:13 -0800 Subject: [PATCH 05/12] Add to emulator page --- docs/build/cadence/advanced-concepts/computation-profiling.md | 2 +- docs/build/tools/emulator/index.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 86b11562b0..9afa06d6d9 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -486,7 +486,7 @@ flow emulator --coverage-reporting View coverage at: `http://localhost:8080/emulator/codeCoverage` -Learn more in the [README](../README.md#cadence-code-coverage). +Learn more in the [Flow Emulator documentation](../../tools/emulator/index.md). ### Debugger diff --git a/docs/build/tools/emulator/index.md b/docs/build/tools/emulator/index.md index 812a20f1e8..d278f1d38d 100644 --- a/docs/build/tools/emulator/index.md +++ b/docs/build/tools/emulator/index.md @@ -171,6 +171,7 @@ flow emulator --help ## Debugging and Testing - **Code Coverage**: Add `--coverage-reporting` flag and visit `http://localhost:8080/emulator/codeCoverage` +- **Computation Profiling**: Add `--computation-profiling` and/or `--computation-reporting` flags to analyze computational costs and identify performance bottlenecks in your Cadence code. See the [Cadence Computation Profiling guide] for detailed instructions. - **Debugging**: Use `#debugger()` pragma in Cadence code for breakpoints - **Fork mode note**: When you use `flow emulator --fork`, only Flow chain state is available. External oracles/APIs and cross-chain reads are not live; mock these or run local stub services for E2E. @@ -232,3 +233,4 @@ To learn more about how to use the Emulator, have a look at the [public GitHub r [Create Emulator Snapshot]: ../flow-cli/utils/snapshot-save.md [public GitHub repository]: https://github.com/onflow/flow-emulator [Interactive Testing with Forked Emulator]: ../../../blockchain-development-tutorials/cadence/emulator-fork-testing/index.md +[Cadence Computation Profiling guide]: ../../cadence/advanced-concepts/computation-profiling.md From a013b89c3b482abd9816361804e9258749f7147b Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:56:31 -0800 Subject: [PATCH 06/12] Remove TOC --- .../computation-profiling.md | 23 ------------------- 1 file changed, 23 deletions(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 9afa06d6d9..8ee22694c8 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -17,29 +17,6 @@ sidebar_position: 1 This guide provides comprehensive instructions for using the computation profiling and reporting features in the Flow Emulator. These tools help Cadence developers analyze and optimize their smart contracts by understanding computational costs and identifying performance bottlenecks. -## Table of Contents - -- [Introduction](#introduction) -- [Prerequisites](#prerequisites) -- [Computation Reporting](#computation-reporting) - - [Enabling Computation Reporting](#enabling-computation-reporting) - - [Viewing Computation Reports](#viewing-computation-reports) -- [Computation Profiling (pprof)](#computation-profiling-pprof) - - [Enabling Computation Profiling](#enabling-computation-profiling) - - [Downloading the Profile](#downloading-the-profile) - - [Viewing Profiles with pprof](#viewing-profiles-with-pprof) - - [Viewing Source Code in pprof](#viewing-source-code-in-pprof) - - [Resetting Computation Profiles](#resetting-computation-profiles) -- [Using Source File Pragmas](#using-source-file-pragmas) -- [Practical Examples](#practical-examples) - - [Profiling a Simple Transaction](#profiling-a-simple-transaction) - - [Identifying Performance Bottlenecks](#identifying-performance-bottlenecks) - - [Comparing Computation Costs](#comparing-computation-costs) -- [Best Practices](#best-practices) -- [API Reference](#api-reference) -- [Troubleshooting](#troubleshooting) -- [Related Features](#related-features) - ## Introduction When developing smart contracts on Flow, understanding computational costs is essential for: From cd64838863957c0d84042e27ba83b427874bdfe3 Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:57:01 -0800 Subject: [PATCH 07/12] Change to overview --- docs/build/cadence/advanced-concepts/computation-profiling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 8ee22694c8..2a9896f0f1 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -17,7 +17,7 @@ sidebar_position: 1 This guide provides comprehensive instructions for using the computation profiling and reporting features in the Flow Emulator. These tools help Cadence developers analyze and optimize their smart contracts by understanding computational costs and identifying performance bottlenecks. -## Introduction +## Overview When developing smart contracts on Flow, understanding computational costs is essential for: From e10c513879fe81d40c04b310497eb87cddb38b0f Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:59:29 -0800 Subject: [PATCH 08/12] Remove --- .../computation-profiling.md | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 2a9896f0f1..f358840949 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -355,30 +355,6 @@ curl http://localhost:8080/emulator/computationReport > report_b.json **4. Compare the `computation` values in both reports.** -## Best Practices - -1. **Profile early and often**: Don't wait until production to understand your computation costs. - -2. **Use the right tool for the job**: - - **Computation Reporting**: Quick checks, automated tests, CI/CD pipelines - - **Computation Profiling**: Deep analysis, visual exploration, optimization work - -3. **Reset between isolated tests**: Always reset profiles when comparing different implementations or testing in isolation. - -4. **Use `#sourceFile` consistently**: Add pragmas to all your transactions and scripts for better debugging and reporting. - -5. **Consider compute limits**: Be aware of the emulator's compute limits: - - `--transaction-max-compute-limit` (default: 9999) - - `--script-compute-limit` (default: 100000) - -6. **Profile realistic scenarios**: Test with realistic data volumes and usage patterns. - -7. **Monitor expensive operations**: Pay attention to high-cost operations like: - - Large loops - - Frequent storage reads/writes (`GetValue`, `SetValue`) - - Cryptographic operations (`Hash`, `VerifySignature`) - - Event emissions (`EmitEvent`) - ## API Reference | Endpoint | Method | Description | From d1f1200b606f488a0813b1a77a929dc88dc7225f Mon Sep 17 00:00:00 2001 From: Chase Fleming Date: Thu, 8 Jan 2026 09:30:44 -0800 Subject: [PATCH 09/12] Update docs/build/cadence/advanced-concepts/computation-profiling.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Müller --- docs/build/cadence/advanced-concepts/computation-profiling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index f358840949..fa7e49aff3 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -30,7 +30,7 @@ The Flow Emulator provides two complementary tools for this purpose: | Feature | Output | Best For | |---------|--------|----------| | **Computation Reporting** | JSON report with detailed intensities | Quick numerical analysis, CI/CD integration, automated testing | -| **Computation Profiling** | pprof-compatible flame graphs | Visual analysis, deep-dive debugging, call stack exploration | +| **Computation Profiling** | pprof profile | Visual analysis (e.g. flame graphs), deep-dive debugging, call stack exploration | ## Prerequisites From fe71ddd0eca59c97c362580f2044c6ea7f342f96 Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Thu, 8 Jan 2026 12:56:52 -0800 Subject: [PATCH 10/12] Move pprof --- .../cadence/advanced-concepts/computation-profiling.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index fa7e49aff3..085e45f346 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -36,12 +36,6 @@ The Flow Emulator provides two complementary tools for this purpose: 1. **Flow CLI** installed ([installation guide](../../tools/flow-cli/install.md)) -2. **[pprof tool](https://github.com/google/pprof)** (for computation profiling): - - ```bash - go install github.com/google/pprof@latest - ``` - ## Computation Reporting Computation reporting provides a JSON-based view of computational costs for all executed transactions and scripts. @@ -124,6 +118,10 @@ The total `computation` value is calculated by multiplying each intensity by its Computation profiling generates pprof-compatible profiles that can be visualized as flame graphs, providing a powerful way to understand your code's execution patterns. +### Installing pprof + +To visualize computation profiles, you'll need the [pprof tool](https://github.com/google/pprof). See the [pprof installation guide](https://github.com/google/pprof#building-pprof) for instructions. + ### Enabling Computation Profiling Start the emulator with the `--computation-profiling` flag: From 265336de0879b2dfe2d7d7248780ece41968f6be Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Thu, 8 Jan 2026 13:14:02 -0800 Subject: [PATCH 11/12] Change source file to computation only --- .../advanced-concepts/computation-profiling.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 085e45f346..c87ed77236 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -205,7 +205,9 @@ curl -X PUT http://localhost:8080/emulator/computationProfile/reset ## Using Source File Pragmas -The `#sourceFile` pragma improves report readability by associating your code with meaningful file paths. Without it, reports show generic identifiers. +The `#sourceFile` pragma improves computation report readability by associating your code with meaningful file paths. Without it, reports show generic identifiers. + +> **Note**: The `#sourceFile` pragma currently only affects **Computation Reporting** (JSON reports). It does not change filenames in **Computation Profiling** (pprof profiles). ### Usage @@ -233,9 +235,8 @@ access(all) fun main(address: Address): UFix64 { ### Benefits -- Reports show file paths instead of generic IDs +- Computation reports show file paths instead of generic IDs - Easier to correlate computation costs with source files -- Better integration with pprof source views - Useful for tracking costs across multiple files in a project ## Practical Examples @@ -415,9 +416,9 @@ flow emulator --computation-profiling curl -X PUT http://localhost:8080/emulator/computationProfile/reset ``` -### Reports not showing file paths +### Computation reports not showing file paths -**Problem**: The `path` field in reports is empty. +**Problem**: The `path` field in computation reports is empty. **Solution**: Add the `#sourceFile` pragma to your transactions and scripts: From c380a0bb589b4a5122c9fb99748282184a4069d1 Mon Sep 17 00:00:00 2001 From: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Date: Thu, 8 Jan 2026 13:21:13 -0800 Subject: [PATCH 12/12] Compare language --- .../computation-profiling.md | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index c87ed77236..63d8575508 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -329,19 +329,19 @@ After profiling, you might see high values for: ### Comparing Computation Costs -You can compare two implementation approaches by: +You can compare two implementation approaches by downloading and comparing profiles: -**1. Reset the report between tests:** +**1. Reset the profile:** ```bash curl -X PUT http://localhost:8080/emulator/computationProfile/reset ``` -**2. Run implementation A and record the computation:** +**2. Run implementation A and save the profile:** ```bash flow transactions send approach_a.cdc -curl http://localhost:8080/emulator/computationReport > report_a.json +curl -o profile_a.pprof http://localhost:8080/emulator/computationProfile ``` **3. Reset and test implementation B:** @@ -349,10 +349,20 @@ curl http://localhost:8080/emulator/computationReport > report_a.json ```bash curl -X PUT http://localhost:8080/emulator/computationProfile/reset flow transactions send approach_b.cdc -curl http://localhost:8080/emulator/computationReport > report_b.json +curl -o profile_b.pprof http://localhost:8080/emulator/computationProfile ``` -**4. Compare the `computation` values in both reports.** +**4. Compare using pprof:** + +```bash +# View profile A +pprof -top profile_a.pprof + +# View profile B +pprof -top profile_b.pprof +``` + +The `-top` view shows total computation, making it easy to compare the two approaches. ## API Reference