Skip to content

Commit fef1fb9

Browse files
jribbinkjribbink
authored
Add flow transactions profile docs (#1645)
1 parent c00d74a commit fef1fb9

File tree

4 files changed

+323
-6
lines changed

4 files changed

+323
-6
lines changed

‎docs/build/cadence/advanced-concepts/computation-profiling.md‎

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,19 +25,58 @@ When developing smart contracts on Flow, understanding computational costs is es
2525
- **Cost Awareness**: Understand how much computation your transactions and scripts consume
2626
- **Bottleneck Identification**: Pinpoint exactly where your code spends the most resources
2727

28-
The Flow Emulator provides two complementary tools for this purpose:
28+
The Flow CLI provides three complementary approaches for profiling computation:
2929

30-
| Feature | Output | Best For |
31-
|---------|--------|----------|
32-
| **Computation Reporting** | JSON report with detailed intensities | Quick numerical analysis, CI/CD integration, automated testing |
33-
| **Computation Profiling** | pprof profile | Visual analysis (e.g. flame graphs), deep-dive debugging, call stack exploration |
30+
| Approach | Output | Best For |
31+
|----------|--------|----------|
32+
| **Transaction Profiling** (`flow transactions profile`) | pprof profile for sealed transactions | Analyzing production transactions on mainnet/testnet |
33+
| **Emulator Computation Reporting** (`flow emulator --computation-reporting`) | JSON report with detailed intensities | Quick numerical analysis, CI/CD integration, automated testing |
34+
| **Emulator Computation Profiling** (`flow emulator --computation-profiling`) | pprof profile for development | Visual analysis during development, flame graphs, call stack exploration |
3435

3536
:::note
3637

3738
Before getting started, make sure you have the [Flow CLI installed](../../tools/flow-cli/install.md).
3839

3940
:::
4041

42+
## Transaction Profiling
43+
44+
For analyzing sealed transactions on any Flow network (mainnet, testnet, or emulator), use the `flow transactions profile` command. This is particularly useful for:
45+
46+
- **Production Analysis**: Profile real transactions on mainnet to understand actual performance
47+
- **Debugging High Costs**: Investigate why a specific transaction used more computation than expected
48+
- **Post-Deployment Optimization**: Analyze live transactions to identify optimization opportunities
49+
50+
### Basic Usage
51+
52+
```bash
53+
# Profile a mainnet transaction
54+
flow transactions profile 07a8...b433 --network mainnet
55+
56+
# Profile with custom output location
57+
flow transactions profile 0xabc123 --network testnet --output my-profile.pb.gz
58+
```
59+
60+
### Analyzing Transaction Profiles
61+
62+
The command generates a pprof profile that can be analyzed with standard tools:
63+
64+
```bash
65+
# Interactive web interface
66+
go tool pprof -http=:8080 profile-07a8b433.pb.gz
67+
68+
# Command-line analysis
69+
go tool pprof -top profile-07a8b433.pb.gz
70+
```
71+
72+
📖 **[Learn more about transaction profiling](../../tools/flow-cli/transactions/profile-transactions.md)**
73+
74+
:::info
75+
76+
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.
77+
78+
:::
79+
4180
## Computation Reporting
4281

4382
Computation reporting provides a JSON-based view of computational costs for all executed transactions and scripts.

‎docs/build/tools/flow-cli/commands.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,20 @@ flow transactions get-system latest 07a8...b433
232232
flow transactions get-system 12345
233233
```
234234

235-
📖 **[Learn more about scripts](./scripts/execute-scripts.md)** | **[Learn more about transactions](./transactions/send-transactions.md)**
235+
### Profile Transaction Performance
236+
237+
```bash
238+
# Profile a mainnet transaction
239+
flow transactions profile 07a8...b433 --network mainnet
240+
241+
# Profile with custom output location
242+
flow transactions profile 0xabc123 --network testnet --output my-profile.pb.gz
243+
244+
# Analyze profile with pprof
245+
go tool pprof -http=:8080 profile-07a8b433.pb.gz
246+
```
247+
248+
📖 **[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)**
236249

237250
## Dependency Management
238251

‎docs/build/tools/flow-cli/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ With Flow CLI, developers can:
1414
- **Send Transactions**: Build, sign, and submit transactions to the Flow network, allowing for contract interaction and fund transfers.
1515
- **Query Chain State**: Retrieve data from the Flow blockchain, including account balances, event logs, and the status of specific transactions.
1616
- **Deploy Smart Contracts**: Easily deploy and update Cadence smart contracts on any Flow environment (emulator, testnet, or mainnet).
17+
- **Profile Transaction Performance**: Generate detailed computational profiles of sealed transactions to optimize gas costs and identify performance bottlenecks.
1718
- **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.
1819
- **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.
1920
- **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.

‎docs/build/tools/flow-cli/transactions/profile-transactions.md‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
---
2+
title: Profile a Transaction
3+
description: How to profile the computational performance of a Flow transaction
4+
sidebar_position: 9
5+
keywords:
6+
- flow cli
7+
- transactions
8+
- profiling
9+
- performance
10+
- optimization
11+
- computation
12+
- pprof
13+
- gas optimization
14+
- cadence profiling
15+
---
16+
17+
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.
18+
19+
:::info
20+
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. Learn more about state forking in the [Fork Testing guide](../fork-testing.md).
21+
:::
22+
23+
```shell
24+
flow transactions profile <tx_id> --network <network_name> [flags]
25+
```
26+
27+
## Use Cases
28+
29+
Transaction profiling helps developers:
30+
31+
- **Optimize Transaction Costs**: Identify computational bottlenecks and optimize gas-heavy operations
32+
- **Debug High Gas Usage**: Understand why a transaction consumed more computation than expected
33+
- **Analyze Production Transactions**: Profile real transactions on mainnet or testnet to understand actual performance
34+
- **Compare Implementations**: Evaluate different approaches by comparing their computational profiles
35+
- **Find Performance Issues**: Trace computation usage through contract calls and dependencies
36+
37+
## Example Usage
38+
39+
Profile a mainnet transaction:
40+
41+
```shell
42+
> flow transactions profile 07a8...b433 --network mainnet
43+
44+
Transaction Profiling Report
45+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
46+
47+
Transaction ID: 07a8...b433
48+
Network: mainnet
49+
Block Height: 12345678
50+
Status: SEALED
51+
Events emitted: 5
52+
Computation: 1234
53+
54+
Profile saved: profile-07a8b433.pb.gz
55+
56+
Analyze with:
57+
go tool pprof -http=:8080 profile-07a8b433.pb.gz
58+
```
59+
60+
Profile with custom output location:
61+
62+
```shell
63+
> flow transactions profile 0xabc123 --network testnet --output my-profile.pb.gz
64+
65+
Profile saved: my-profile.pb.gz
66+
```
67+
68+
Profile an emulator transaction:
69+
70+
```shell
71+
> flow transactions profile 0xdef456 --network emulator
72+
```
73+
74+
## Analyzing Profile Data
75+
76+
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).
77+
78+
### Interactive Web Interface
79+
80+
Open the profile in an interactive web interface:
81+
82+
```bash
83+
go tool pprof -http=:8080 profile-07a8b433.pb.gz
84+
```
85+
86+
Then navigate to `http://localhost:8080` in your browser.
87+
88+
The pprof web interface provides several visualization options:
89+
90+
| View | Description |
91+
|------|-------------|
92+
| **Flame Graph** | Visual representation of call stacks with computation costs |
93+
| **Graph** | Directed graph showing call relationships |
94+
| **Top** | List of functions sorted by computation usage |
95+
| **Source** | Source code annotated with computation costs |
96+
97+
### Command-Line Analysis
98+
99+
View top computation consumers:
100+
101+
```bash
102+
go tool pprof -top profile-07a8b433.pb.gz
103+
```
104+
105+
List all functions with costs:
106+
107+
```bash
108+
go tool pprof -list=. profile-07a8b433.pb.gz
109+
```
110+
111+
Generate a flame graph image:
112+
113+
```bash
114+
go tool pprof -png profile-07a8b433.pb.gz > profile.png
115+
```
116+
117+
For comprehensive information on analyzing computation profiles, see the [Cadence Computation Profiling guide](../../../cadence/advanced-concepts/computation-profiling.md).
118+
119+
## How It Works
120+
121+
The profiling process:
122+
123+
1. **Fetches the Transaction**: Retrieves the target sealed transaction by ID from the specified network
124+
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))
125+
3. **Replays Execution**: Replays all prior transactions in the same block to recreate the exact state
126+
4. **Profiles Target Transaction**: Executes the target transaction with Cadence runtime profiling enabled
127+
5. **Exports Profile**: Saves the profiling data to a pprof-compatible file
128+
129+
This ensures the profile accurately reflects the transaction's execution in its original context.
130+
131+
:::info
132+
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).
133+
:::
134+
135+
## Arguments
136+
137+
### Transaction ID
138+
139+
- Name: `<tx_id>`
140+
- Valid Input: transaction ID (with or without `0x` prefix)
141+
142+
The transaction ID to profile. The transaction must be sealed.
143+
144+
## Flags
145+
146+
### Network
147+
148+
- Flag: `--network`
149+
- Short Flag: `-n`
150+
- Valid inputs: the name of a network defined in `flow.json`
151+
- **Required**
152+
153+
Specify which network the transaction was executed on (e.g., `mainnet`, `testnet`, `emulator`).
154+
155+
### Output
156+
157+
- Flag: `--output`
158+
- Short Flag: `-o`
159+
- Valid inputs: valid file path
160+
- Default: `profile-{tx_id_prefix}.pb.gz`
161+
162+
Custom output file path for the profile data. The file will be saved in compressed pprof format (`.pb.gz`).
163+
164+
### Host
165+
166+
- Flag: `--host`
167+
- Valid inputs: an IP address or hostname
168+
- Default: `127.0.0.1:3569` (Flow Emulator)
169+
170+
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.
171+
172+
### Network Key
173+
174+
- Flag: `--network-key`
175+
- Valid inputs: A valid network public key of the host in hex string format
176+
177+
Specify the network public key of the Access API that will be used to create a secure GRPC client when executing the command.
178+
179+
### Filter
180+
181+
- Flag: `--filter`
182+
- Short Flag: `-x`
183+
- Valid inputs: a case-sensitive name of the result property
184+
185+
Specify any property name from the result you want to return as the only value.
186+
187+
### Output Format
188+
189+
- Flag: `--output`
190+
- Short Flag: `-o`
191+
- Valid inputs: `json`, `inline`
192+
193+
Specify the format of the command results displayed in the console.
194+
195+
### Save
196+
197+
- Flag: `--save`
198+
- Short Flag: `-s`
199+
- Valid inputs: a path in the current filesystem
200+
201+
Specify the filename where you want the result summary to be saved.
202+
203+
### Log
204+
205+
- Flag: `--log`
206+
- Short Flag: `-l`
207+
- Valid inputs: `none`, `error`, `debug`
208+
- Default: `info`
209+
210+
Specify the log level. Control how much output you want to see during command execution.
211+
212+
### Configuration
213+
214+
- Flag: `--config-path`
215+
- Short Flag: `-f`
216+
- Valid inputs: a path in the current filesystem
217+
- Default: `flow.json`
218+
219+
Specify the path to the `flow.json` configuration file.
220+
221+
### Version Check
222+
223+
- Flag: `--skip-version-check`
224+
- Default: `false`
225+
226+
Skip version check during start up to speed up process for slow connections.
227+
228+
## Requirements
229+
230+
### Transaction Must Be Sealed
231+
232+
Only sealed transactions can be profiled. Attempting to profile a pending or finalized transaction will result in an error.
233+
234+
```shell
235+
Error: transaction is not sealed (status: PENDING)
236+
```
237+
238+
Wait for the transaction to be sealed before profiling, or use a different transaction.
239+
240+
### Network Configuration
241+
242+
The network must be properly configured in your `flow.json` file:
243+
244+
```json
245+
{
246+
"networks": {
247+
"mainnet": "access.mainnet.nodes.onflow.org:9000",
248+
"testnet": "access.devnet.nodes.onflow.org:9000"
249+
}
250+
}
251+
```
252+
253+
### Go Toolchain (for analysis)
254+
255+
To analyze the generated profile files, you need Go installed on your system. The `pprof` tool is included in the standard Go distribution.
256+
257+
Install Go from: https://go.dev/doc/install
258+
259+
## Related Documentation
260+
261+
- **[Cadence Computation Profiling](../../../cadence/advanced-concepts/computation-profiling.md)** - Comprehensive guide on profiling and optimization
262+
- **[Fork Testing Guide](../fork-testing.md)** - Learn more about the state forking capabilities used by this command
263+
- **[Testing Strategy](../../../cadence/smart-contracts/testing-strategy.md)** - How profiling fits into your overall testing and optimization workflow
264+
- **[Transaction Fees](../../../cadence/basics/fees.md)** - Understanding computation costs and fee optimization

0 commit comments

Comments
 (0)