From 10ca860c354a22c234c97097b6f4b96417485532 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Mon, 26 Jan 2026 09:21:51 -0800 Subject: [PATCH] Add `flow transactions profile` docs --- .../computation-profiling.md | 49 +++- docs/build/tools/flow-cli/commands.md | 15 +- docs/build/tools/flow-cli/index.md | 1 + .../transactions/profile-transactions.md | 262 ++++++++++++++++++ 4 files changed, 321 insertions(+), 6 deletions(-) create mode 100644 docs/build/tools/flow-cli/transactions/profile-transactions.md diff --git a/docs/build/cadence/advanced-concepts/computation-profiling.md b/docs/build/cadence/advanced-concepts/computation-profiling.md index 0e4ded3c0f..d76dbf58a3 100644 --- a/docs/build/cadence/advanced-concepts/computation-profiling.md +++ b/docs/build/cadence/advanced-concepts/computation-profiling.md @@ -25,12 +25,13 @@ When developing smart contracts on Flow, understanding computational costs is es - **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: +The Flow CLI provides three complementary approaches for profiling computation: -| Feature | Output | Best For | -|---------|--------|----------| -| **Computation Reporting** | JSON report with detailed intensities | Quick numerical analysis, CI/CD integration, automated testing | -| **Computation Profiling** | pprof profile | Visual analysis (e.g. flame graphs), deep-dive debugging, call stack exploration | +| Approach | Output | Best For | +|----------|--------|----------| +| **Transaction Profiling** (`flow transactions profile`) | pprof profile for sealed transactions | Analyzing production transactions on mainnet/testnet | +| **Emulator Computation Reporting** (`flow emulator --computation-reporting`) | JSON report with detailed intensities | Quick numerical analysis, CI/CD integration, automated testing | +| **Emulator Computation Profiling** (`flow emulator --computation-profiling`) | pprof profile for development | Visual analysis during development, flame graphs, call stack exploration | :::note @@ -38,6 +39,44 @@ Before getting started, make sure you have the [Flow CLI installed](../../tools/ ::: +## Transaction Profiling + +For analyzing sealed transactions on any Flow network (mainnet, testnet, or emulator), use the `flow transactions profile` command. This is particularly useful for: + +- **Production Analysis**: Profile real transactions on mainnet to understand actual performance +- **Debugging High Costs**: Investigate why a specific transaction used more computation than expected +- **Post-Deployment Optimization**: Analyze live transactions to identify optimization opportunities + +### Basic Usage + +```bash +# Profile a mainnet transaction +flow transactions profile 07a8...b433 --network mainnet + +# Profile with custom output location +flow transactions profile 0xabc123 --network testnet --output my-profile.pb.gz +``` + +### Analyzing Transaction Profiles + +The command generates a pprof profile that can be analyzed with standard tools: + +```bash +# Interactive web interface +go tool pprof -http=:8080 profile-07a8b433.pb.gz + +# Command-line analysis +go tool pprof -top profile-07a8b433.pb.gz +``` + +📖 **[Learn more about transaction profiling](../../tools/flow-cli/transactions/profile-transactions.md)** + +:::info + +Transaction profiling works with sealed transactions on any network, while emulator profiling (described below) is designed for development and provides aggregated profiles across multiple executions. + +::: + ## Computation Reporting Computation reporting provides a JSON-based view of computational costs for all executed transactions and scripts. diff --git a/docs/build/tools/flow-cli/commands.md b/docs/build/tools/flow-cli/commands.md index 9ab0baf34e..a3442333f1 100644 --- a/docs/build/tools/flow-cli/commands.md +++ b/docs/build/tools/flow-cli/commands.md @@ -232,7 +232,20 @@ flow transactions get-system latest 07a8...b433 flow transactions get-system 12345 ``` -📖 **[Learn more about scripts](./scripts/execute-scripts.md)** | **[Learn more about transactions](./transactions/send-transactions.md)** +### Profile Transaction Performance + +```bash +# Profile a mainnet transaction +flow transactions profile 07a8...b433 --network mainnet + +# Profile with custom output location +flow transactions profile 0xabc123 --network testnet --output my-profile.pb.gz + +# Analyze profile with pprof +go tool pprof -http=:8080 profile-07a8b433.pb.gz +``` + +📖 **[Learn more about scripts](./scripts/execute-scripts.md)** | **[Learn more about transactions](./transactions/send-transactions.md)** | **[Learn more about transaction profiling](./transactions/profile-transactions.md)** ## Dependency Management diff --git a/docs/build/tools/flow-cli/index.md b/docs/build/tools/flow-cli/index.md index de8056d7fc..4993be5797 100644 --- a/docs/build/tools/flow-cli/index.md +++ b/docs/build/tools/flow-cli/index.md @@ -14,6 +14,7 @@ With Flow CLI, developers can: - **Send Transactions**: Build, sign, and submit transactions to the Flow network, allowing for contract interaction and fund transfers. - **Query Chain State**: Retrieve data from the Flow blockchain, including account balances, event logs, and the status of specific transactions. - **Deploy Smart Contracts**: Easily deploy and update Cadence smart contracts on any Flow environment (emulator, testnet, or mainnet). +- **Profile Transaction Performance**: Generate detailed computational profiles of sealed transactions to optimize gas costs and identify performance bottlenecks. - **Use the Emulator:** Set up a local Flow blockchain instance with the Flow emulator to test and debug smart contracts in a development environment before deploying them on the network. - **Test with Fork Mode**: Use [fork testing](fork-testing.md) to run tests and development environments against a local copy of mainnet or testnet state, giving you access to real contracts and data without affecting production. - **Interact with the [Flow Access API](/http-api)**: Automate complex workflows using configuration files and command-line scripting, which allows for greater flexibility in continuous integration (CI) or custom development tools. diff --git a/docs/build/tools/flow-cli/transactions/profile-transactions.md b/docs/build/tools/flow-cli/transactions/profile-transactions.md new file mode 100644 index 0000000000..a3c6516f38 --- /dev/null +++ b/docs/build/tools/flow-cli/transactions/profile-transactions.md @@ -0,0 +1,262 @@ +--- +title: Profile a Transaction +description: How to profile the computational performance of a Flow transaction +sidebar_position: 9 +keywords: + - flow cli + - transactions + - profiling + - performance + - optimization + - computation + - pprof + - gas optimization + - cadence profiling +--- + +The Flow CLI provides a command to profile the computational performance of sealed transactions on any Flow network. This diagnostic tool generates detailed CPU profiles in the industry-standard `pprof` format, allowing you to analyze exactly where computation is being spent during transaction execution. + +The command works by forking the blockchain state and replaying the transaction in an isolated environment, ensuring accurate profiling results that match the original execution. + +```shell +flow transactions profile --network [flags] +``` + +## Use Cases + +Transaction profiling helps developers: + +- **Optimize Transaction Costs**: Identify computational bottlenecks and optimize gas-heavy operations +- **Debug High Gas Usage**: Understand why a transaction consumed more computation than expected +- **Analyze Production Transactions**: Profile real transactions on mainnet or testnet to understand actual performance +- **Compare Implementations**: Evaluate different approaches by comparing their computational profiles +- **Find Performance Issues**: Trace computation usage through contract calls and dependencies + +## Example Usage + +Profile a mainnet transaction: + +```shell +> flow transactions profile 07a8...b433 --network mainnet + +Transaction Profiling Report +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Transaction ID: 07a8...b433 +Network: mainnet +Block Height: 12345678 +Status: SEALED +Events emitted: 5 +Computation: 1234 + +Profile saved: profile-07a8b433.pb.gz + +Analyze with: + go tool pprof -http=:8080 profile-07a8b433.pb.gz +``` + +Profile with custom output location: + +```shell +> flow transactions profile 0xabc123 --network testnet --output my-profile.pb.gz + +Profile saved: my-profile.pb.gz +``` + +Profile an emulator transaction: + +```shell +> flow transactions profile 0xdef456 --network emulator +``` + +## Analyzing Profile Data + +The generated `.pb.gz` file can be analyzed using Go's pprof tools. If you don't have Go installed, see the [Go installation guide](https://go.dev/doc/install). + +### Interactive Web Interface + +Open the profile in an interactive web interface: + +```bash +go tool pprof -http=:8080 profile-07a8b433.pb.gz +``` + +Then navigate to `http://localhost:8080` in your browser. + +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 | + +### Command-Line Analysis + +View top computation consumers: + +```bash +go tool pprof -top profile-07a8b433.pb.gz +``` + +List all functions with costs: + +```bash +go tool pprof -list=. profile-07a8b433.pb.gz +``` + +Generate a flame graph image: + +```bash +go tool pprof -png profile-07a8b433.pb.gz > profile.png +``` + +For comprehensive information on analyzing computation profiles, see the [Cadence Computation Profiling guide](../../../cadence/advanced-concepts/computation-profiling.md). + +## How It Works + +The profiling process: + +1. **Fetches the Transaction**: Retrieves the target sealed transaction by ID from the specified network +2. **Forks Blockchain State**: Creates a fork of the blockchain state from the block immediately before the transaction's block (uses the same forking mechanism as [Fork Testing](../fork-testing.md)) +3. **Replays Execution**: Replays all prior transactions in the same block to recreate the exact state +4. **Profiles Target Transaction**: Executes the target transaction with Cadence runtime profiling enabled +5. **Exports Profile**: Saves the profiling data to a pprof-compatible file + +This ensures the profile accurately reflects the transaction's execution in its original context. + +:::info +The transaction profiling command uses Flow's state forking capabilities under the hood to create an accurate execution environment. Learn more about state forking in the [Fork Testing guide](../fork-testing.md). +::: + +## Arguments + +### Transaction ID + +- Name: `` +- Valid Input: transaction ID (with or without `0x` prefix) + +The transaction ID to profile. The transaction must be sealed. + +## Flags + +### Network + +- Flag: `--network` +- Short Flag: `-n` +- Valid inputs: the name of a network defined in `flow.json` +- **Required** + +Specify which network the transaction was executed on (e.g., `mainnet`, `testnet`, `emulator`). + +### Output + +- Flag: `--output` +- Short Flag: `-o` +- Valid inputs: valid file path +- Default: `profile-{tx_id_prefix}.pb.gz` + +Custom output file path for the profile data. The file will be saved in compressed pprof format (`.pb.gz`). + +### Host + +- Flag: `--host` +- Valid inputs: an IP address or hostname +- Default: `127.0.0.1:3569` (Flow Emulator) + +Specify the hostname of the Access API that will be used to fetch transaction data. This flag overrides any host defined by the `--network` flag. + +### Network Key + +- Flag: `--network-key` +- Valid inputs: A valid network public key of the host in hex string format + +Specify the network public key of the Access API that will be used to create a secure GRPC client when executing the command. + +### Filter + +- Flag: `--filter` +- Short Flag: `-x` +- Valid inputs: a case-sensitive name of the result property + +Specify any property name from the result you want to return as the only value. + +### Output Format + +- Flag: `--output` +- Short Flag: `-o` +- Valid inputs: `json`, `inline` + +Specify the format of the command results displayed in the console. + +### Save + +- Flag: `--save` +- Short Flag: `-s` +- Valid inputs: a path in the current filesystem + +Specify the filename where you want the result summary to be saved. + +### Log + +- Flag: `--log` +- Short Flag: `-l` +- Valid inputs: `none`, `error`, `debug` +- Default: `info` + +Specify the log level. Control how much output you want to see during command execution. + +### Configuration + +- Flag: `--config-path` +- Short Flag: `-f` +- Valid inputs: a path in the current filesystem +- Default: `flow.json` + +Specify the path to the `flow.json` configuration file. + +### Version Check + +- Flag: `--skip-version-check` +- Default: `false` + +Skip version check during start up to speed up process for slow connections. + +## Requirements + +### Transaction Must Be Sealed + +Only sealed transactions can be profiled. Attempting to profile a pending or finalized transaction will result in an error. + +```shell +Error: transaction is not sealed (status: PENDING) +``` + +Wait for the transaction to be sealed before profiling, or use a different transaction. + +### Network Configuration + +The network must be properly configured in your `flow.json` file: + +```json +{ + "networks": { + "mainnet": "access.mainnet.nodes.onflow.org:9000", + "testnet": "access.devnet.nodes.onflow.org:9000" + } +} +``` + +### Go Toolchain (for analysis) + +To analyze the generated profile files, you need Go installed on your system. The `pprof` tool is included in the standard Go distribution. + +Install Go from: https://go.dev/doc/install + +## Related Documentation + +- **[Cadence Computation Profiling](../../../cadence/advanced-concepts/computation-profiling.md)** - Comprehensive guide on profiling and optimization +- **[Fork Testing Guide](../fork-testing.md)** - Learn more about the state forking capabilities used by this command +- **[Testing Strategy](../../../cadence/smart-contracts/testing-strategy.md)** - How profiling fits into your overall testing and optimization workflow +- **[Transaction Fees](../../../cadence/basics/fees.md)** - Understanding computation costs and fee optimization