Add flow transactions profile docs

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

@@ -25,19 +25,58 @@ 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
 
 Before getting started, make sure you have the [Flow CLI installed](../../tools/flow-cli/install.md).
 
 :::
 
+## 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.

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
 

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.

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

@@ -0,0 +1,264 @@
+---
+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.
+
+:::info
+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).
+:::
+
+```shell
+flow transactions profile <tx_id> --network <network_name> [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: `<tx_id>`
+- 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