README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# debrief <a href="https://r-lib.github.io/debrief/"><img src="man/figures/logo.png" align="right" height="139" alt="debrief website" /></a>

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/debrief)](https://CRAN.R-project.org/package=debrief)
[![R-CMD-check](https://github.com/r-lib/debrief/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/debrief/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/r-lib/debrief/graph/badge.svg)](https://app.codecov.io/gh/r-lib/debrief)
<!-- badges: end -->

debrief provides text-based summaries and analysis tools for [profvis](https://rstudio.github.io/profvis/) profiling output. It's designed for terminal workflows and AI agent consumption, offering views including hotspot analysis, call trees, source context, caller/callee relationships, and memory allocation breakdowns.

## Installation

You can install the development version of debrief from [GitHub](https://github.com/) with:

``` r
# install.packages("pak")
pak::pak("r-lib/debrief")
```

## Quick Start

```r
library(profvis)
library(debrief)

# Profile some code
p <- profvis({
  # your code here
})

# Get help on available functions
pv_help()

# Start with a summary
pv_print_debrief(p)
```

## Typical Workflow

debrief is designed for iterative profiling. Each function prints "Next steps" suggestions to guide you deeper:
```
1. pv_print_debrief(p)
 -> Overview: identifies hot functions and lines

2. pv_focus(p, "hot_function")
 -> Deep dive: time breakdown, callers, callees, source

3. pv_hot_lines(p)
 -> Exact lines: find the specific code consuming time

4. pv_source_context(p, "file.R")
 -> Code view: see source with profiling data overlay

5. pv_suggestions(p)
 -> Actions: get specific optimization recommendations
```

The `pv_help()` function lists all available functions by category.

## Example

First, create a profvis profile of some code. To get source references in the
profile, write your code to a file and source it with `keep.source = TRUE`:

```{r example}
library(profvis)
library(debrief)

# Write functions to a temp file for source references
example_code <- '
process_data <- function(n) {
  raw <- generate_data(n)
  cleaned <- clean_data(raw)
  summarize_data(cleaned)
}

generate_data <- function(n) {
  x <- rnorm(n)
  y <- runif(n)
  data.frame(x = x, y = y, z = x * y)
}

clean_data <- function(df) {
  df <- df[complete.cases(df), ]
  df$x_scaled <- scale(df$x)
  df$category <- cut(df$y, breaks = 5)
  df
}

summarize_data <- function(df) {
  list(
    means = colMeans(df[, c("x", "y", "z")]),
    sds = apply(df[, c("x", "y", "z")], 2, sd),
    counts = table(df$category),
    text = paste(round(df$x, 2), collapse = ", ")
  )
}
'

writeLines(example_code, "analysis.R")
source("analysis.R", keep.source = TRUE)

# Profile the data pipeline
p <- profvis({
  results <- lapply(1:5, function(i) process_data(1e5))
})

unlink("analysis.R")
```

### Quick Summary

Get a comprehensive overview with `pv_print_debrief()`:

```{r summary}
pv_print_debrief(p)
```

### Time Analysis

Analyze where time is spent:

```{r time}
# Self-time: time spent directly in each function
pv_self_time(p)

# Total time: time spent in function + all its callees
pv_total_time(p)

# Filter to significant functions only
pv_self_time(p, min_pct = 5) # >= 5% of time
```

### Hot Spots

Find the hottest lines and call paths:

```{r hotspots}
# Hot source lines with context
pv_print_hot_lines(p, n = 5, context = 3)

# Hot call paths
pv_print_hot_paths(p, n = 10)
```

### Function Analysis

Deep dive into a specific function:

```{r focus}
pv_focus(p, "clean_data")
```

### Call Relationships

Understand who calls what:

```{r calls}
# Who calls this function?
pv_callers(p, "clean_data")

# What does this function call?
pv_callees(p, "process_data")

# Full caller/callee analysis
pv_print_callers_callees(p, "summarize_data")
```

### Memory Analysis

Track memory allocations:

```{r memory}
# Memory by function
pv_print_memory(p, n = 10, by = "function")

# Memory by source line
pv_print_memory(p, n = 10, by = "line")
```

### Text-based Flame Graph

Visualize the call tree:

```{r flame}
pv_flame(p, width = 70, min_pct = 2)
```

### Compare Profiles

Measure optimization impact:

```{r compare}
# Approach 1: Growing vectors in a loop (slow)
p_slow <- profvis({
  result <- c()
  for (i in 1:20000) {
    result <- c(result, sqrt(i) * log(i))
  }
})

# Approach 2: Vectorized with memory allocation
p_fast <- profvis({
  x <- rnorm(5e6)
  y <- cumsum(x)
  z <- paste(head(round(x, 2), 50000), collapse = ", ")
})

# Compare two profiles
pv_print_compare(p_slow, p_fast)

# Approach 3: Data frame operations
p_dataframe <- profvis({
  df <- data.frame(
    a = rnorm(1e6),
    b = runif(1e6),
    c = sample(letters, 1e6, replace = TRUE)
  )
  df$d <- df$a * df$b
  result <- aggregate(d ~ c, data = df, FUN = mean)
})

# Compare all three approaches
pv_print_compare_many(
  growing_vector = p_slow,
  vectorized = p_fast,
  dataframe_ops = p_dataframe
)
```

### Diagnostics

Detect GC pressure and get optimization suggestions:

```{r diagnostics}
# Detect GC pressure (indicates memory allocation issues)
pv_print_gc_pressure(p)

# Get actionable optimization suggestions
pv_print_suggestions(p)
```

### Export for AI Agents

Export structured data for programmatic access:

```{r export}
# Export as R list for programmatic access
results <- pv_to_list(p)
names(results)

# Data frame of functions by self-time
results$self_time
```

## Available Functions

| Category | Functions |
|----------|-----------|
| Overview | `pv_help()`, `pv_debrief()`, `pv_print_debrief()`, `pv_example()` |
| Time Analysis | `pv_self_time()`, `pv_total_time()` |
| Hot Spots | `pv_hot_lines()`, `pv_hot_paths()`, `pv_worst_line()`, `pv_print_hot_lines()`, `pv_print_hot_paths()` |
| Memory | `pv_memory()`, `pv_memory_lines()`, `pv_print_memory()` |
| Call Analysis | `pv_callers()`, `pv_callees()`, `pv_call_depth()`, `pv_call_stats()` |
| Function Analysis | `pv_focus()`, `pv_recursive()` |
| Source Context | `pv_source_context()`, `pv_file_summary()` |
| Visualization | `pv_flame()`, `pv_flame_condense()` |
| Comparison | `pv_compare()`, `pv_print_compare()`, `pv_compare_many()`, `pv_print_compare_many()` |
| Diagnostics | `pv_gc_pressure()`, `pv_suggestions()` |
| Export | `pv_to_json()`, `pv_to_list()` |

### Filtering Support

Time and hot spot functions support filtering:

```r
# Filter by percentage threshold
pv_self_time(p, min_pct = 5)
pv_hot_lines(p, min_pct = 10)

# Filter by time threshold
pv_self_time(p, min_time_ms = 100)

# Limit number of results
pv_self_time(p, n = 10)

# Combine filters
pv_hot_lines(p, n = 5, min_pct = 2, min_time_ms = 10)
```