github.com/pyroscope-io/pyroscope@v0.37.3-0.20230725203016-5f6947968bd0/examples/adhoc/README.md (about)

     1  ## Adhoc mode examples
     2  
     3  Pyroscope provides three options for using the "adhoc" mode, depending on whether you have the Pyroscope SDK installed or not. Choose the appropriate method based on your setup.
     4  
     5  ### Option 1: Push mode (with SDK installed)
     6  If your application already uses an agent or has integration with the Pyroscope HTTP API, you can use push mode
     7  to profile the application without any additional configuration changes.
     8  
     9  #### Golang Adhoc (Push Mode)
    10  If the application to profile is already using an agent or has some integration with the HTTP API,
    11  push mode can be used to profile the application without any configuration change.
    12  
    13  ```
    14  # no spy is supported, --push is not needed (but can still be provided):
    15  pyroscope adhoc go run adhoc-push.go
    16  ```
    17  
    18  #### Python adhoc (using pip package)
    19  ```
    20  # pyspy is autodetected, --push is mandatory.
    21  pyroscope adhoc --push python adhoc-push.py
    22  ```
    23  
    24  ### Option 2: Push Mode (no SDK installed -- Pyroscope sidecar)
    25  
    26  If you don't have the Pyroscope SDK installed and want to profile a Python or Ruby application, you can still push data
    27  to the Pyroscope server using the adhoc mode as a sidecar.
    28  
    29  #### Python adhoc (no pip package -- Pyroscope sidecar)
    30  For languages with a supported spy and no other pyroscope integration, this is the easiest way to get profiling data.
    31  For example, this method will work for python or ruby _without_ the pip/gem instrumented in the code.
    32  For this you will need to use the `pyroscope-cli` from the [pyroscope-rs](https://github.com/grafana/pyroscope-rs/releases/tag/cli-0.2.7) project.
    33  
    34  **Note: this is different than using the pyroscope binary, `./pyroscope`, itself.**
    35  
    36  Profile a script using adhoc
    37  ```
    38  pyroscope adhoc --push pyroscope-cli exec --spy-name=pyspy main.py
    39  ```
    40  
    41  Attach to a process and profile it using `pyroscope-cli`
    42  ```
    43  sudo pyroscope adhoc --push pyroscope-cli connect --spy-name=pyspy --pid=<pid>
    44  ```
    45  
    46  ```
    47  ```
    48  
    49  ### Option 3: Pull Mode
    50  
    51  If the application to profile supports pull-mode, that is, it's already running a HTTP server
    52  and serving profiling data in a supported format, like `pprof`,
    53  pull-mode can be used to to profile the application without any configuration change,
    54  as long as the HTTP endpoint is reachable for pyroscope.
    55  
    56  In this mode, pyroscope can either launch the application if needed or just gather the data of an already running application:
    57  
    58  ```
    59  # Launch and profile the application
    60  pyroscope adhoc --url localhost:6060 go run adhoc-pull.go
    61  ```
    62  
    63  ```
    64  # Lauch the application first
    65  go run adhoc-pull.go &
    66  # Profile the running application.
    67  # Note that currently pyroscope will be running until you interrupt it.
    68  pyroscope adhoc --url localhost:6060
    69  ```