# Ruby on Rails

Packrat monitors your Ruby on Rails application deploys, creating a verification plan and validating that it performs as intended in production. This guide walks through the Packrat setup for a Rails application.

The `packrat-rails` gem sets up OpenTelemetry in your app and sends its exceptions, traces and logs to
Packrat. It supports Rails 7.1 and newer.

> **Already running Datadog's tracer?** Dual-ship from the [Datadog Agent](https://packrat.sh/docs/datadog).

## Prerequisites

1. [Sign up for Packrat](https://packrat.sh/start). It's free.
2. Copy your ingest key from the setup page. It starts with `packrat_ingest_`.
3. Install the Packrat CLI and sign in, so you can check what Packrat receives:

   ```sh
   curl -fsSL https://packrat.sh/cli | sh
   packrat login
   ```

## Install the gem

### 1. Add packrat-rails

```sh
bundle add packrat-rails
```

### 2. Run the generator

```sh
bin/rails generate packrat --ingest-key=packrat_ingest_…
```

The generator creates `config/initializers/packrat.rb`:

```ruby
Packrat.configure do |config|
  config.ingest_key = ENV.fetch("PACKRAT_INGEST_KEY", "packrat_ingest_…")
end
```

An ingest key can only send data, so you can commit the file. To keep the key out of the repository,
run the generator without `--ingest-key` and set a `PACKRAT_INGEST_KEY` environment variable where the app runs.

The generator also adds the [Packrat plugin for Claude Code](https://packrat.sh/docs/claude-code-plugin)
to your repository's `.claude/settings.json`. Commit the file, and anyone who opens Claude Code in the
repository gets the plugin. To skip this, pass `--no-claude-code`.

### 3. Restart the app

When the app boots, the gem writes one line to the Rails log. It names the service and environment
your data arrives under:

```
Packrat: sending traces and logs for shop/production to https://ingest.packrat.sh (rack, action_pack, active_job, active_record, net_http, pg, logger)
```

The gem sends nothing from the test environment.

## Check it works

Load a page. The first request reaches your setup screen within about a minute.

Run `packrat status` with your app's name, as `<service>/<environment>`:

```sh
packrat status --app shop/production
```

The output lists each signal (exceptions, traces, logs, metrics and replays), the sources that send
it, when each source last sent, and whether Packrat keeps it. A signal with no source hasn't arrived
yet. To see the names your apps report under, run `packrat apps`.

If nothing arrives, the [quickstart](https://packrat.sh/docs/quickstart#not-seeing-data) lists what
usually causes it.

## Configuration

`Packrat.configure` sets the ingest key. Everything else is an environment variable:

| Variable                        | Default                                               | Note                                                                         |
| ------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
| `PACKRAT_INGEST_KEY`            | `config.ingest_key`                                   | Wins over the initializer. With neither, the gem sends nothing               |
| `PACKRAT_DISABLED`              | unset                                                 | `1` turns the gem off. The app boots as if the gem were not installed        |
| `PACKRAT_OTEL_INSTRUMENTATIONS` | the list below                                        | Comma-separated names to add. A leading `-` removes one                      |

The gem installs these instrumentations: `rack`, `action_pack`, `action_view`, `active_job`,
`active_record`, `net_http`, `pg`, `mysql2`, `sidekiq`, `redis`, `aws_sdk`, `concurrent_ruby`,
`rake` and `logger`. One for a library your app doesn't use installs nothing. For example,
`PACKRAT_OTEL_INSTRUMENTATIONS=faraday,-action_view` adds Faraday (add
`opentelemetry-instrumentation-faraday` to your bundle too) and removes Action View.

Your app's name in Packrat is `<service>/<environment>`:

- **Service:** `OTEL_SERVICE_NAME`, else `service.name` in `OTEL_RESOURCE_ATTRIBUTES`, else the
  application's module name (`Shop::Application` is `shop`).
- **Environment:** `Rails.env`, unless `OTEL_RESOURCE_ATTRIBUTES` names one.
- **Version:** `BUILD_COMMIT`, `HEROKU_SLUG_COMMIT` or `SOURCE_VERSION`. Packrat matches it to your
  deploys.

A standard `OTEL_*` variable that you set always wins over the gem's value.

## Beside other tools

- **Sentry:** both run, and the gem doesn't change Sentry. If Sentry also
  [dual-ships to Packrat](https://packrat.sh/docs/sentry#on-your-rails-server), Packrat keeps
  exceptions and traces from whichever source sent them first. `packrat status` shows which.
- **Your own OpenTelemetry setup:** the gem leaves it as it is and adds a second exporter, to
  Packrat. If your exporter already sends to Packrat, the gem adds nothing.
- **Session replays** come from Sentry's browser SDK, whatever runs on your server. Follow the
  [Sentry browser guide](https://packrat.sh/docs/sentry#in-the-browser).

To configure OpenTelemetry yourself instead of using the gem, follow the Rails tab of the
[OpenTelemetry guide](https://packrat.sh/docs/opentelemetry?framework=rails).

---

## Agent instructions

This page is part of the Packrat documentation, published as plain markdown for coding agents: add `.md` to any docs address, or read the index at https://packrat.sh/docs/llms.txt. This page: https://packrat.sh/docs/ruby-on-rails.md.

Before wiring Packrat into an app, ask the developer for the URL of their setup page at https://packrat.sh/orgs, and read it with `packrat open <URL>`. It has the steps and the org's ingest key.