Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update adhoc readme for more adhoc modes #1985

Merged
merged 11 commits into from
Jul 11, 2023
42 changes: 20 additions & 22 deletions examples/adhoc/README.md
Original file line number Diff line number Diff line change
@@ -1,55 +1,53 @@
## 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 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.

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.
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
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.

Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
Profile a script using adhoc
```
# Run with spy-name autodetected.
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
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
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
```

### 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"
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
```
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved

Using docker:
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
```
# 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"
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved
```

### Pull mode
### Option 2: Pull Mode
Rperry2174 marked this conversation as resolved.
Show resolved Hide resolved

If the application to profile supports pull-mode, that is, it's already running a HTTP server
and serving profiling data in a supported format, like `pprof`,
Expand Down