Chapter 5

One command line for profiling, validation, and bindings.

rc has the Go profiler built in, runs the profilers of other languages as add-ons, validates any profile, and generates the binding packages that code declares against.

1. Get rc

Install it with Homebrew, with apt or dnf on Linux, download a release from runtimeconditions/rc-cli, or build it from a checkout, which embeds the pinned core profile schema.

Homebrew
brew install runtimeconditions/tools/rc-cli
rc --version
Linux: apt, dnf, and yum
curl -fsSL https://runtimeconditions.io/packages/setup.sh | sudo sh
sudo apt install rc-cli     # Debian, Ubuntu
sudo dnf install rc-cli     # Fedora, RHEL, Rocky, AlmaLinux (yum on older systems)

The setup script only adds the signed Runtime Conditions package source for your distribution and prints the install command, and it needs sudo. It supports amd64 and arm64. The same source carries the Java and TypeScript profilers as rc-profiler-java and rc-profiler-typescript.

Build from source
go run ./scripts/build.go --output ./rc
./rc --version

Profiling Go needs a working Go toolchain and the workload's binding dependencies. The workload is analyzed, never executed.

2. Profile a Go workload

Built-in Go profiler
rc profile generate --dir ./service --out profile.yaml

# the same, with every option
rc profile go generate \
  --dir ./service \
  --name my-workload \
  --workload-uri https://example.com/my-workload \
  --workload-version 1.0.0 \
  --out profile.yaml

Without --out the profile is printed. A failed run leaves an existing output file unchanged. rc profile validate-extensions and rc profile validate-extension check the imported binding packages.

3. Validate any profile

A profile does not have to come from a profiler. Check one written by hand, or by an agent, against the core profile schema and the extensions it declares.

Validate
rc profile validate profile.yaml

Extension definitions are downloaded from their ids, or read from directories given with --catalog.

4. Other languages are add-ons

Go is built into rc. For every other language, rc profile <language> hands the work to a separate profiler and passes everything after the language name through unchanged, so each profiler keeps its own flags.

Run an add-on
rc profile java generate --project ./service --resolve-build-classpath --out profile.yaml
rc profile python generate --project ./service --name orders --workload-uri https://example.com/orders
rc profile typescript generate --project ./service --name orders --workload-uri https://example.com/orders

To find the add-on, rc looks for an executable on PATH. An environment variable can point to a specific file instead.

LanguageExecutable on PATHOr set
TypeScriptrc-profiler-typescript, then runtimeconditions-typescript-profilerRC_TYPESCRIPT_PROFILER
Javarc-profiler-javaRC_JAVA_PROFILER
Pythonruntimeconditions-python-profilerRC_PYTHON_PROFILER

Compatibility. rc runs an add-on only when its --version --json output lists the core profile schema that rc targets.

Java. The launcher picks the JDK, not rc: RC_JAVA_HOME, then JAVA_HOME, then a bundled runtime, then java on PATH. It needs JDK 17 or newer.

Python. The profiler finds the bindings in the environment it is installed in. Install it into the workload's virtual environment and put that environment's bin directory on PATH.

Check. rc plugins list shows each add-on's status, version and path.

5. Profilers and how to install them

Each profiler reads source without running it, checks the binding packages it finds, and writes the same profile for the same declarations. rc profile <language> runs the one you installed.

LanguageProfilerInstallNeeds
Go Built into rc (go-rc-profiler)
brew install runtimeconditions/tools/rc-cli
sudo apt install rc-cli
sudo dnf install rc-cli
A Go toolchain
Java java-rc-profiler rc-profiler-java
brew install runtimeconditions/tools/rc-profiler-java
sudo apt install rc-profiler-java
sudo dnf install rc-profiler-java
or the jar from its releases
JDK 17 or newer
Python runtimeconditions-profiler (source)
pip install runtimeconditions-profiler
in the workload's virtual environment
Python 3.11 or newer
TypeScript @runtimeconditions/typescript-profiler (source)
npm install --global @runtimeconditions/typescript-profiler
brew install runtimeconditions/tools/rc-profiler-typescript
sudo apt install rc-profiler-typescript
sudo dnf install rc-profiler-typescript
Node.js

apt is for Debian and Ubuntu, dnf for Fedora, RHEL, Rocky, and AlmaLinux; both need the package source from Get rc. The binding packages each profiler reads are listed on the Extensions page.

6. Generate and verify bindings

The binding commands resolve extension definitions, generate binding packages, and check that committed packages still match.

Binding commands
rc bindings resolve | normalize | generate | verify
rc bindings package | plan-release | check | update

generate writes into a new or empty directory. update verifies candidates before it changes committed bindings, and check compares regenerated content without changing it. Use --target package-key:language to limit the targets. Run rc bindings --help for the flags.