Skip to content

Commit

Permalink
Update adhoc readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Rperry2174 committed Jul 6, 2023
1 parent 40e0742 commit 32d2a9e
Showing 1 changed file with 19 additions and 21 deletions.
40 changes: 19 additions & 21 deletions examples/adhoc/README.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,50 @@
## Adhoc mode examples

These examples showcase the different running modes of `pyroscope adhoc`.
Check [adhoc documentation](https://pyroscope.io/docs/agent-configuration-adhoc) for complete information about what modes are supported by each language.
Pyroscope provides two 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.

Note: The example programs are toy examples but they share some interesting properties: their running time should take around 1 minute, and their profiling data should change slightly from run to run (making them good examples for comparison / diff mode visualizations).
### Option 1: Push mode (with SDK installed)
If your application already uses an agent or has integration with the Pyroscope HTTP API, you can use push mode
to profile the application without any additional configuration changes.

### Push Mode
#### Golang Adhoc (Push Mode)
If the application to profile is already using an agent or has some integration with the HTTP API,
push mode can be used to profile the application without any configuration change.

#### Golang adhoc (push)
```
# no spy is supported, --push is not needed (but can still be provided):
pyroscope adhoc go run adhoc-push.go
```

#### Python adhoc (using pip package)
```
# pyspy is autodetected, --push is mandatory.
# Note that you need pyroscope-io >= 0.6.0 for this to work.
pyroscope adhoc --push python adhoc-push.py
```

### Option 2: Push Mode (no SDK installed -- Pyroscope sidecar)

If you don't have the Pyroscope SDK installed and want to profile a Python or Ruby application, you can still push data
to the Pyroscope server using the adhoc mode as a sidecar.

### Exec mode
#### Python adhoc (no pip package -- Pyroscope sidecar)
For languages with a supported spy and no other pyroscope integration, this is the easiest way to get profiling data.
For example, this method will work for python or ruby _without_ the pip/gem instrumented in the code.

Profile a script using adhoc
```
# Run with spy-name autodetected.
pyroscope adhoc python adhoc-spy.py
# Alternatively, specify the spy-name if it cannot be autodetected.
pyroscope adhoc --spy-name pyspy ./adhoc-spy.py
./bin/pyroscope adhoc --push ~/Downloads/pyroscope-cli exec --spy-name=pyspy examples/python/simple/main.py
```

### Connect mode
#### Profile a process that is already running

If the profiled process is already running, it's possible to attach to it instead, indicating its PID through the `--pid` flag:
Attach to and profile a process using adhoc
```
sudo ./pyroscope-cli connect --pid=[369936] --spy-name=pyspy --server-address="http://localhost:4100"
```

Using docker:
```
# Run the program normally, in the background. It should give the PID as output.
python adhoc-spy.py &
# => [1] 841690
# Use adhoc to attach to the running command.
# Note that the --spy-name is now mandatory as it cannot be inferred.
# Also, pyroscope needs to be launched as root to be able to trace the running process.
sudo pyroscope adhoc --spy-name pyspy --pid 841690
docker run --rm -ti --privileged --pid=host pyroscope/pyroscope-rs-cli:0.2.7-457bb15 connect --pid=369936 --spy-name=pyspy --server-address="http://localhost:4100"
```

### Pull mode
Expand Down

0 comments on commit 32d2a9e

Please sign in to comment.