Package 'proffer'

proffer: profile R code with pprof

Description

It can be challenging to find sources of slowness in large workflows, and the proffer package can help. Proffer runs R code and displays summaries to show where the code is slowest. Proffer leverages the pprof utility to create highly efficient, clear, easy-to-read interactive displays that help users find ways to reduce runtime. The package also contains helpers to convert profiling data to and from pprof format and visualize existing profiling data files. For documentation, visit https://r-prof.github.io/proffer/.

Author(s)

William Michael Landau [email protected]

References

https://github.com/r-prof/proffer

Examples

# TBD
if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
# Start a pprof virtual server in the background.
px <- pprof(replicate(1e2, sample.int(1e4)))
# Terminate the server.
px$kill()
}

---

Profile R code and visualize with pprof.

Description

Run R code and display profiling results in a local interactive pprof server. Results are collected with record_pprof().

Usage

pprof(
  expr,
  seconds_timeout = Inf,
  host = "localhost",
  port = proffer::random_port(),
  browse = interactive(),
  verbose = TRUE,
  ...
)

Arguments

expr	R code to run and profile.
seconds_timeout	Maximum number of seconds of elapsed time to profile expr. When the timeout is reached, proffer stops running expr and returns the profiling samples taken during the seconds_timeout time window.
host	Host name. Set to "localhost" to view locally or "0.0.0.0" to view from another machine. If you view from another machine, the printed out URL will not be valid. For example, if pprof() or serve_pprof() prints "http://0.0.0.0:8080", then you need to replace 0.0.0.0 with your computer's name or IP address, e.g. "http://my_computer.com:8080".
port	Port number for hosting the local pprof server. Chosen randomly by default.
browse	Logical, whether to open a browser to view the pprof server.
verbose	Logical, whether to print console messages such as the URL of the local pprof server.
...	Additional arguments passed on to Rprof() via record_pprof().

Value

A processx::process$new() handle. Use this handle to take down the server with ⁠$kill()⁠.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
# Start a pprof virtual server in the background.
px <- pprof(replicate(1e2, sample.int(1e4)))
# Terminate the server.
px$kill()
}

---

Verify pprof installation

Description

Check if pprof and its dependencies are installed.

Usage

pprof_sitrep()

Examples

pprof_sitrep()

---

Choose a random free TCP port.

Description

Choose a random free TCP port.

Usage

random_port(lower = 49152L, upper = 65535L)

Arguments

lower	Integer of length 1, lower bound of the port number.
upper	Integer of length 1, upper bound of the port number.

Details

This function is a simple wrapper around parallelly::freePort() with the default port range covering ephemeral ports only.

Value

Port number, positive integer of length 1.

Examples

random_port()

---

Profile R code and record pprof samples.

Description

Run R code and record pprof samples. Profiles are recorded with record_rprof() and then converted with to_pprof().

Usage

record_pprof(expr, seconds_timeout = Inf, pprof = tempfile(), ...)

Arguments

expr	An R expression to profile.
seconds_timeout	Maximum number of seconds of elapsed time to profile expr. When the timeout is reached, proffer stops running expr and returns the profiling samples taken during the seconds_timeout time window.
pprof	Path to a file with pprof samples. Also returned from the function.
...	Additional arguments passed on to Rprof().

Value

Path to a file with pprof samples.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
# Returns a path to pprof samples.
record_pprof(replicate(1e2, sample.int(1e4)))
}

---

Profile R code and record Rprof samples.

Description

Run R code and record Rprof samples.

Usage

record_rprof(expr, seconds_timeout = Inf, rprof = tempfile(), ...)

Arguments

expr	An R expression to profile.
seconds_timeout	Maximum number of seconds of elapsed time to profile expr. When the timeout is reached, proffer stops running expr and returns the profiling samples taken during the seconds_timeout time window.
rprof	Path to a file with Rprof samples. Also returned from the function.
...	Additional arguments passed on to Rprof().

Value

Path to a file with Rprof samples.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
# Returns a path to Rprof samples.
record_rprof(replicate(1e2, sample.int(1e4)))
}

---

Visualize profiling data with pprof.

Description

Visualize profiling data with pprof.

Usage

serve_pprof(
  pprof,
  host = "localhost",
  port = proffer::random_port(),
  browse = interactive(),
  verbose = TRUE
)

Arguments

pprof	Path to pprof samples.
host	Host name. Set to "localhost" to view locally or "0.0.0.0" to view from another machine. If you view from another machine, the printed out URL will not be valid. For example, if pprof() or serve_pprof() prints "http://0.0.0.0:8080", then you need to replace 0.0.0.0 with your computer's name or IP address, e.g. "http://my_computer.com:8080".
port	Port number for hosting the local pprof server. Chosen randomly by default.
browse	Logical, whether to open a browser to view the pprof server.
verbose	Logical, whether to print console messages such as the URL of the local pprof server.

Details

Uses a local interactive server. Navigate a browser to a URL in the message. The server starts in a background process

Value

A processx::process$new() handle. Use this handle to take down the server with ⁠$kill()⁠.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
pprof <- record_pprof(replicate(1e2, sample.int(1e4)))
# Start a pprof virtual server in the background.
px <- serve_pprof(pprof)
# Terminate the server.
px$kill()
}

---

Visualize Rprof() output with pprof.

Description

Use pprof to visualize profiling data produced by Rprof() or record_rprof().

Usage

serve_rprof(
  rprof,
  host = "localhost",
  port = proffer::random_port(),
  browse = interactive(),
  verbose = TRUE
)

Arguments

rprof	Path to profiling samples generated by Rprof() or record_rprof().
host	Host name. Set to "localhost" to view locally or "0.0.0.0" to view from another machine. If you view from another machine, the printed out URL will not be valid. For example, if pprof() or serve_pprof() prints "http://0.0.0.0:8080", then you need to replace 0.0.0.0 with your computer's name or IP address, e.g. "http://my_computer.com:8080".
port	Port number for hosting the local pprof server. Chosen randomly by default.
browse	Logical, whether to open a browser to view the pprof server.
verbose	Logical, whether to print console messages such as the URL of the local pprof server.

Details

Uses a local interactive server. Navigate a browser to a URL in the message. The server starts in a background process

Value

A processx::process$new() handle. Use this handle to take down the server with ⁠$kill()⁠.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
rprof <- record_rprof(replicate(1e2, sample.int(1e4)))
# Start a pprof virtual server in the background.
px <- serve_rprof(rprof)
# Terminate the server.
px$kill()
}

---

Test pprof()

Description

Do a test run of pprof() to verify that the system dependencies like pprof work as expected.

Usage

test_pprof(
  host = "localhost",
  port = proffer::random_port(),
  browse = interactive(),
  verbose = TRUE
)

Arguments

host	Host name. Set to "localhost" to view locally or "0.0.0.0" to view from another machine. If you view from another machine, the printed out URL will not be valid. For example, if pprof() or serve_pprof() prints "http://0.0.0.0:8080", then you need to replace 0.0.0.0 with your computer's name or IP address, e.g. "http://my_computer.com:8080".
port	Port number for hosting the local pprof server. Chosen randomly by default.
browse	Logical, whether to open a browser to view the pprof server.
verbose	Logical, whether to print console messages such as the URL of the local pprof server.

Details

See https://github.com/r-prof/proffer#installation for setup instructions.

See Also

pprof()

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
test_pprof()
}

---

Convert Rprof samples to pprof format.

Description

Convert Rprof samples to pprof format.

Usage

to_pprof(rprof, pprof = tempfile())

Arguments

rprof	Path to Rprof samples.
pprof	Path to pprof samples.

Value

Path to pprof samples.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
rprof <- record_rprof(replicate(1e2, sample.int(1e4)))
to_pprof(rprof)
}

---

Convert pprof samples to Rprof format.

Description

Convert pprof samples to Rprof format.

Usage

to_rprof(pprof, rprof = tempfile())

Arguments

pprof	Path to pprof samples.
rprof	Path to Rprof samples.

Value

Path to pprof samples.

Examples

if (identical(Sys.getenv("PROFFER_EXAMPLES"), "true")) {
pprof <- record_pprof(replicate(1e2, sample.int(1e4)))
to_rprof(pprof)
}

---