# Install EZLogs in this Rails app

Install the `ez_logs_agent` gem. EZLogs turns HTTP requests, background jobs and database changes into a plain-English activity log. Follow these steps exactly, change nothing else, then do the verify step.

## 1. Add the gem

Needs Ruby >= 3.1.0. Add this to the `Gemfile`:

```ruby
gem 'ez_logs_agent', '~> 0.2.3'
```

Then run:

```bash
bundle install
```

## 2. Run the generator

```bash
rails generate ez_logs_agent:install
```

It creates `config/initializers/ez_logs_agent.rb`, which already reads the key from the environment:

```ruby
config.project_token = ENV["EZLOGS_API_KEY"]
```

Keep that line. Do not paste the key into the file. The agent sends to app.ezlogs.io by default.

## 3. Set the environment variables

Set this for development and in the production host's settings. Never commit the key.

For development, put it in `.env` and make sure `.env` is in `.gitignore`. Rails does not read `.env` on its own: if the `Gemfile` has no `dotenv-rails` (or `dotenv`), add `gem "dotenv-rails", groups: [:development, :test]` and run `bundle install`.

```bash
EZLOGS_API_KEY=ezl_your_api_key_here
```

If the key above is still `ezl_your_api_key_here`, stop and ask me for my EZLogs API key (Settings → API keys at app.ezlogs.io). Never invent one.

## 4. Who did it (optional)

If the app uses Devise, uncomment the `actor_from_request` block in the initializer. The Devise example is already there.

## 5. Names (optional)

Records are titled with their `name`, then `title`, then `number` attribute, else `#id`. To name other models, set `config.display_name_for = { "Order" => :number }` in the initializer. Use direct attributes only, never associations. Names show on shared links, so ask me before naming people (e.g. `"User" => :email`).

## 6. Verify

```bash
rails ez_logs_agent:test_connection
```

Run it in a new terminal (or with the `EZLOGS_` variables unset), without exporting any variables by hand, so it reads the settings the app really uses.

- It must print `✅ All checks passed!`.
- If it prints `HTTP 401`, the key is wrong or revoked. Fix `EZLOGS_API_KEY` and run it again.
- If it says `project_token is required`, `EZLOGS_API_KEY` is not loaded (see step 3). Do not paste the key into the initializer.
- Then restart the Rails server. The latest boot in `log/development.log` must show `[EzLogsAgent] capturing → app.ezlogs.io (key ezl_XXXXXXXX…)`; `not capturing: project_token missing` means the key is not loaded.
- Open one page or submit one form in the app. It appears in EZLogs within a few seconds.

Tell me which steps you did and paste the test output and the `[EzLogsAgent]` line.

Reference: https://github.com/dezsirazvan/ez_logs_agent#readme
