~michaelforrest/use-case-mapper/trunk

The +debug+ helper will return a <pre>-tag that renders the object using the YAML format. This will generate human-readable data from any object. For example, if you have this code in a view:

<html>

<%= debug @post %>

Title:

<%=h @post.title %>

</html>

You'll see something like this:

<yaml>

--- !ruby/object:Post

attributes:

updated_at: 2008-09-05 22:55:47

body: It's a very helpful guide for debugging your Rails app.

title: Rails debugging guide

published: t

id: "1"

created_at: 2008-09-05 22:55:47

attributes_cache: {}

Title: Rails debugging guide

</yaml>

h4. +to_yaml+

Displaying an instance variable, or any other object or method, in yaml format can be achieved this way:

<html>

<%= simple_format @post.to_yaml %>

Title:

<%=h @post.title %>

</html>

The +to_yaml+ method converts the method to YAML format leaving it more readable, and then the +simple_format+ helper is used to render each line as in the console. This is how +debug+ method does its magic.

As a result of this, you will have something like this in your view:

<yaml>

--- !ruby/object:Post

attributes:

updated_at: 2008-09-05 22:55:47

body: It's a very helpful guide for debugging your Rails app.

title: Rails debugging guide

published: t

id: "1"

created_at: 2008-09-05 22:55:47

attributes_cache: {}

Title: Rails debugging guide

</yaml>

h4. +inspect+

Another useful method for displaying object values is +inspect+, especially when working with arrays or hashes. This will print the object value as a string. For example:

<html>

<%= [1, 2, 3, 4, 5].inspect %>

Title:

<%=h @post.title %>

</html>

Will be rendered as follows:

<pre>

[1, 2, 3, 4, 5]

Title: Rails debugging guide

</pre>

h4. Debugging JavaScript

100

101

Rails has built-in support to debug RJS, to active it, set +ActionView::Base.debug_rjs+ to _true_, this will specify whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it).

102

103

To enable it, add the following in the +Rails::Initializer do |config|+ block inside +environment.rb+:

104

105

<ruby>

106

config.action_view[:debug_rjs] = true

107

</ruby>

108

109

Or, at any time, setting +ActionView::Base.debug_rjs+ to _true_:

110

111

<ruby>

112

ActionView::Base.debug_rjs = true

113

</ruby>

114

115

TIP: For more information on debugging javascript refer to "Firebug":http://getfirebug.com/, the popular debugger for Firefox.

116

117

h3. The Logger

118

119

It can also be useful to save information to log files at runtime. Rails maintains a separate log file for each runtime environment.

120

121

h4. What is the Logger?

122

123

Rails makes use of Ruby's standard +logger+ to write log information. You can also substitute another logger such as +Log4R+ if you wish.

124

125

You can specify an alternative logger in your +environment.rb+ or any environment file:

126

127

<ruby>

128

ActiveRecord::Base.logger = Logger.new(STDOUT)

129

ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")

130

</ruby>

131

132

Or in the +Initializer+ section, add _any_ of the following

133

134

<ruby>

135

config.logger = Logger.new(STDOUT)

136

config.logger = Log4r::Logger.new("Application Log")

137

</ruby>

138

139

TIP: By default, each log is created under +RAILS_ROOT/log/+ and the log file name is +environment_name.log+.

140

141

h4. Log Levels

142

143

When something is logged it's printed into the corresponding log if the log level of the message is equal or higher than the configured log level. If you want to know the current log level you can call the +ActiveRecord::Base.logger.level+ method.

144

145

The available log levels are: +:debug+, +:info+, +:warn+, +:error+, and +:fatal+, corresponding to the log level numbers from 0 up to 4 respectively. To change the default log level, use

146

147

<ruby>

148

config.log_level = Logger::WARN # In any environment initializer, or

149

ActiveRecord::Base.logger.level = 0 # at any time

150

</ruby>

151

152

This is useful when you want to log under development or staging, but you don't want to flood your production log with unnecessary information.

153

154

TIP: The default Rails log level is +info+ in production mode and +debug+ in development and test mode.

155

156

h4. Sending Messages

157

158

To write in the current log use the +logger.(debug|info|warn|error|fatal)+ method from within a controller, model or mailer:

159

160

<ruby>

161

logger.debug "Person attributes hash: #{@person.attributes.inspect}"

162

logger.info "Processing the request..."

163

logger.fatal "Terminating application, raised unrecoverable error!!!"

164

</ruby>

165

166

Here's an example of a method instrumented with extra logging:

167

168

<ruby>

169

class PostsController < ApplicationController

170

# ...

171

172

def create

173

@post = Post.new(params[:post])

174

logger.debug "New post: #{@post.attributes.inspect}"

175

logger.debug "Post should be valid: #{@post.valid?}"

176

177

if @post.save

178

flash[:notice] = 'Post was successfully created.'

179

logger.debug "The post was saved and now is the user is going to be redirected..."

180

redirect_to(@post)

181

else

182

render :action => "new"

183

end

184

end

185

186

# ...

187

end

188

</ruby>

189

190

Here's an example of the log generated by this method:

191

192

<shell>

193

Processing PostsController#create (for 127.0.0.1 at 2008-09-08 11:52:54) [POST]

194

Session ID: BAh7BzoMY3NyZl9pZCIlMDY5MWU1M2I1ZDRjODBlMzkyMWI1OTg2NWQyNzViZjYiCmZsYXNoSUM6J0FjdGl

195

vbkNvbnRyb2xsZXI6OkZsYXNoOjpGbGFzaEhhc2h7AAY6CkB1c2VkewA=--b18cd92fba90eacf8137e5f6b3b06c4d724596a4

196

Parameters: {"commit"=>"Create", "post"=>{"title"=>"Debugging Rails",

197

"body"=>"I'm learning how to print in logs!!!", "published"=>"0"},

198

"authenticity_token"=>"2059c1286e93402e389127b1153204e0d1e275dd", "action"=>"create", "controller"=>"posts"}

199

New post: {"updated_at"=>nil, "title"=>"Debugging Rails", "body"=>"I'm learning how to print in logs!!!",

200

"published"=>false, "created_at"=>nil}

201

Post should be valid: true

202

Post Create (0.000443) INSERT INTO "posts" ("updated_at", "title", "body", "published",

203

"created_at") VALUES('2008-09-08 14:52:54', 'Debugging Rails',

204

'I''m learning how to print in logs!!!', 'f', '2008-09-08 14:52:54')

205

The post was saved and now is the user is going to be redirected...

206

Redirected to #<Post:0x20af760>

207

Completed in 0.01224 (81 reqs/sec) | DB: 0.00044 (3%) | 302 Found [http://localhost/posts]

208

</shell>

209

210

Adding extra logging like this makes it easy to search for unexpected or unusual behavior in your logs. If you add extra logging, be sure to make sensible use of log levels, to avoid filling your production logs with useless trivia.

211

212

h3. Debugging with +ruby-debug+

213

214

When your code is behaving in unexpected ways, you can try printing to logs or the console to diagnose the problem. Unfortunately, there are times when this sort of error tracking is not effective in finding the root cause of a problem. When you actually need to journey into your running source code, the debugger is your best companion.

215

216

The debugger can also help you if you want to learn about the Rails source code but don't know where to start. Just debug any request to your application and use this guide to learn how to move from the code you have written deeper into Rails code.

217

218

h4. Setup

219

220

The debugger used by Rails, +ruby-debug+, comes as a gem. To install it, just run:

221

222

<shell>

223

$ sudo gem install ruby-debug

224

</shell>

225

226

In case you want to download a particular version or get the source code, refer to the "project's page on rubyforge":http://rubyforge.org/projects/ruby-debug/.

227

228

Rails has had built-in support for ruby-debug since Rails 2.0. Inside any Rails application you can invoke the debugger by calling the +debugger+ method.

229

230

Here's an example:

231

232

<ruby>

233

class PeopleController < ApplicationController

234

def new

235

debugger

236

@person = Person.new

237

end

238

end

239

</ruby>

240

241

If you see the message in the console or logs:

242

243

<shell>

244

***** Debugger requested, but was not available: Start server with --debugger to enable *****

245

</shell>

246

247

Make sure you have started your web server with the option +--debugger+:

248

249

<shell>

250

~/PathTo/rails_project$ script/server --debugger

251

=> Booting Mongrel (use 'script/server webrick' to force WEBrick)

252

=> Rails 2.2.0 application starting on http://0.0.0.0:3000

253

=> Debugger enabled

254

...

255

</shell>

256

257

TIP: In development mode, you can dynamically +require \'ruby-debug\'+ instead of restarting the server, if it was started without +--debugger+.

258

259

In order to use Rails debugging you'll need to be running either *WEBrick* or *Mongrel*. For the moment, no alternative servers are supported.

260

261

h4. The Shell

262

263

As soon as your application calls the +debugger+ method, the debugger will be started in a debugger shell inside the terminal window where you launched your application server, and you will be placed at ruby-debug's prompt +(rdb:n)+. The _n_ is the thread number. The prompt will also show you the next line of code that is waiting to run.

264

265

If you got there by a browser request, the browser tab containing the request will be hung until the debugger has finished and the trace has finished processing the entire request.

266

267

For example:

268

269

<shell>

270

@posts = Post.find(:all)

271

(rdb:7)

272

</shell>

273

274

Now it's time to explore and dig into your application. A good place to start is by asking the debugger for help... so type: +help+ (You didn't see that coming, right?)

275

276

<shell>

277

(rdb:7) help

278

ruby-debug help v0.10.2

279

Type 'help <command-name>' for help on a specific command

280

281

Available commands:

282

backtrace delete enable help next quit show trace

283

break disable eval info p reload source undisplay

284

catch display exit irb pp restart step up

285

condition down finish list ps save thread var

286

continue edit frame method putl set tmate where

287

</shell>

288

289

TIP: To view the help menu for any command use +help <command-name>+ in active debug mode. For example: _+help var+_

290

291

The next command to learn is one of the most useful: +list+. You can also abbreviate ruby-debug commands by supplying just enough letters to distinguish them from other commands, so you can also use +l+ for the +list+ command.

292

293

This command shows you where you are in the code by printing 10 lines centered around the current line; the current line in this particular case is line 6 and is marked by +=>+.

294

295

<shell>

296

(rdb:7) list

297

[1, 10] in /PathToProject/posts_controller.rb

298

1 class PostsController < ApplicationController

299

2 # GET /posts

300

3 # GET /posts.xml

301

4 def index

302

5 debugger

303

=> 6 @posts = Post.find(:all)

304

305

8 respond_to do |format|

306

9 format.html # index.html.erb

307

10 format.xml { render :xml => @posts }

308

</shell>

309

310

If you repeat the +list+ command, this time using just +l+, the next ten lines of the file will be printed out.

311

312

<shell>

313

(rdb:7) l

314

[11, 20] in /PathTo/project/app/controllers/posts_controller.rb

315

11 end

316

12 end

317

318

14 # GET /posts/1

319

15 # GET /posts/1.xml

320

16 def show

321

17 @post = Post.find(params[:id])

322

323

19 respond_to do |format|

324

20 format.html # show.html.erb

325

</shell>

326

327

And so on until the end of the current file. When the end of file is reached, the +list+ command will start again from the beginning of the file and continue again up to the end, treating the file as a circular buffer.

328

329

h4. The Context

330

331

When you start debugging your application, you will be placed in different contexts as you go through the different parts of the stack.

332

333

ruby-debug creates a content when a stopping point or an event is reached. The context has information about the suspended program which enables a debugger to inspect the frame stack, evaluate variables from the perspective of the debugged program, and contains information about the place where the debugged program is stopped.

334

335

At any time you can call the +backtrace+ command (or its alias +where+) to print the backtrace of the application. This can be very helpful to know how you got where you are. If you ever wondered about how you got somewhere in your code, then +backtrace+ will supply the answer.

336

337

<shell>

338

(rdb:5) where

339

#0 PostsController.index

340

at line /PathTo/project/app/controllers/posts_controller.rb:6

341

#1 Kernel.send

342

at line /PathTo/project/vendor/rails/actionpack/lib/action_controller/base.rb:1175

343

#2 ActionController::Base.perform_action_without_filters

344

at line /PathTo/project/vendor/rails/actionpack/lib/action_controller/base.rb:1175

345

#3 ActionController::Filters::InstanceMethods.call_filters(chain#ActionController::Fil...,...)

346

at line /PathTo/project/vendor/rails/actionpack/lib/action_controller/filters.rb:617

347

...

348

</shell>

349

350

You move anywhere you want in this trace (thus changing the context) by using the +frame _n_+ command, where _n_ is the specified frame number.

351

352

<shell>

353

(rdb:5) frame 2

354

#2 ActionController::Base.perform_action_without_filters

355

at line /PathTo/project/vendor/rails/actionpack/lib/action_controller/base.rb:1175

356

</shell>

357

358

The available variables are the same as if you were running the code line by line. After all, that's what debugging is.

359

360

Moving up and down the stack frame: You can use +up [n]+ (+u+ for abbreviated) and +down [n]+ commands in order to change the context _n_ frames up or down the stack respectively. _n_ defaults to one. Up in this case is towards higher-numbered stack frames, and down is towards lower-numbered stack frames.

361

362

h4. Threads

363

364

The debugger can list, stop, resume and switch between running threads by using the command +thread+ (or the abbreviated +th+). This command has a handful of options:

365

366

* +thread+ shows the current thread.

367

* +thread list+ is used to list all threads and their statuses. The plus + character and the number indicates the current thread of execution.

368

* +thread stop _n_+ stop thread _n_.

369

* +thread resume _n_+ resumes thread _n_.

370

* +thread switch _n_+ switches the current thread context to _n_.

371

372

This command is very helpful, among other occasions, when you are debugging concurrent threads and need to verify that there are no race conditions in your code.

373

374

h4. Inspecting Variables

375

376

Any expression can be evaluated in the current context. To evaluate an expression, just type it!

377

378

This example shows how you can print the instance_variables defined within the current context:

379

380

<shell>

381

@posts = Post.find(:all)

382

(rdb:11) instance_variables

383

["@_response", "@action_name", "@url", "@_session", "@_cookies", "@performed_render", "@_flash", "@template", "@_params", "@before_filter_chain_aborted", "@request_origin", "@_headers", "@performed_redirect", "@_request"]

384

</shell>

385

386

As you may have figured out, all of the variables that you can access from a controller are displayed. This list is dynamically updated as you execute code. For example, run the next line using +next+ (you'll learn more about this command later in this guide).

387

388

<shell>

389

(rdb:11) next

390

Processing PostsController#index (for 127.0.0.1 at 2008-09-04 19:51:34) [GET]

391

Session ID: BAh7BiIKZmxhc2hJQzonQWN0aW9uQ29udHJvbGxlcjo6Rmxhc2g6OkZsYXNoSGFzaHsABjoKQHVzZWR7AA==--b16e91b992453a8cc201694d660147bba8b0fd0e

392

Parameters: {"action"=>"index", "controller"=>"posts"}

393

/PathToProject/posts_controller.rb:8

394

respond_to do |format|

395

</shell>

396

397

And then ask again for the instance_variables:

398

399

<shell>

400

(rdb:11) instance_variables.include? "@posts"

401

true

402

</shell>

403

404

Now +@posts+ is a included in the instance variables, because the line defining it was executed.

405

406

TIP: You can also step into *irb* mode with the command +irb+ (of course!). This way an irb session will be started within the context you invoked it. But be warned: this is an experimental feature.

407

408

The +var+ method is the most convenient way to show variables and their values:

409

410

<shell>

411

var

412

(rdb:1) v[ar] const <object> show constants of object

413

(rdb:1) v[ar] g[lobal] show global variables

414

(rdb:1) v[ar] i[nstance] <object> show instance variables of object

415

(rdb:1) v[ar] l[ocal] show local variables

416

</shell>

417

418

This is a great way to inspect the values of the current context variables. For example:

419

420

<shell>

421

(rdb:9) var local

422

__dbg_verbose_save => false

423

</shell>

424

425

You can also inspect for an object method this way:

426

427

<shell>

428

(rdb:9) var instance Post.new

429

@attributes = {"updated_at"=>nil, "body"=>nil, "title"=>nil, "published"=>nil, "created_at"...

430

@attributes_cache = {}

431

@new_record = true

432

</shell>

433

434

TIP: The commands +p+ (print) and +pp+ (pretty print) can be used to evaluate Ruby expressions and display the value of variables to the console.

435

436

You can use also +display+ to start watching variables. This is a good way of tracking the values of a variable while the execution goes on.

437

438

<shell>

439

(rdb:1) display @recent_comments

440

1: @recent_comments =

441

</shell>

442

443

The variables inside the displaying list will be printed with their values after you move in the stack. To stop displaying a variable use +undisplay _n_+ where _n_ is the variable number (1 in the last example).

444

445

h4. Step by Step

446

447

Now you should know where you are in the running trace and be able to print the available variables. But lets continue and move on with the application execution.

448

449

Use +step+ (abbreviated +s+) to continue running your program until the next logical stopping point and return control to ruby-debug.

450

451

TIP: You can also use +step+ _n_+ and +step- _n_+ to move forward or backward _n_ steps respectively.

452

453

You may also use +next+ which is similar to step, but function or method calls that appear within the line of code are executed without stopping. As with step, you may use plus sign to move _n_ steps.

454

455

The difference between +next+ and +step+ is that +step+ stops at the next line of code executed, doing just a single step, while +next+ moves to the next line without descending inside methods.

456

457

For example, consider this block of code with an included +debugger+ statement:

458

459

<ruby>

460

class Author < ActiveRecord::Base

461

has_one :editorial

462

has_many :comments

463

464

def find_recent_comments(limit = 10)

465

debugger

466

@recent_comments ||= comments.find(

467

:all,

468

:conditions => ["created_at > ?", 1.week.ago],

469

:limit => limit

470

)

471

end

472

end

473

</ruby>

474

475

TIP: You can use ruby-debug while using script/console. Just remember to +require "ruby-debug"+ before calling the +debugger+ method.

476

477

<shell>

478

/PathTo/project $ script/console

479

Loading development environment (Rails 2.1.0)

480

>> require "ruby-debug"

481

=> []

482

>> author = Author.first

483

=> #<Author id: 1, first_name: "Bob", last_name: "Smith", created_at: "2008-07-31 12:46:10", updated_at: "2008-07-31 12:46:10">

484

>> author.find_recent_comments

485

/PathTo/project/app/models/author.rb:11

486

)

487

</shell>

488

489

With the code stopped, take a look around:

490

491

<shell>

492

(rdb:1) list

493

[6, 15] in /PathTo/project/app/models/author.rb

494

6 debugger

495

7 @recent_comments ||= comments.find(

496

8 :all,

497

9 :conditions => ["created_at > ?", 1.week.ago],

498

10 :limit => limit

499

=> 11 )

500

12 end

501

13 end

502

</shell>

503

504

You are at the end of the line, but... was this line executed? You can inspect the instance variables.

505

506

<shell>

507

(rdb:1) var instance

508

@attributes = {"updated_at"=>"2008-07-31 12:46:10", "id"=>"1", "first_name"=>"Bob", "las...

509

@attributes_cache = {}

510

</shell>

511

512

+@recent_comments+ hasn't been defined yet, so it's clear that this line hasn't been executed yet. Use the +next+ command to move on in the code:

513

514

<shell>

515

(rdb:1) next

516

/PathTo/project/app/models/author.rb:12

517

@recent_comments

518

(rdb:1) var instance

519

@attributes = {"updated_at"=>"2008-07-31 12:46:10", "id"=>"1", "first_name"=>"Bob", "las...

520

@attributes_cache = {}

521

@comments = []

522

@recent_comments = []

523

</shell>

524

525

Now you can see that the +@comments+ relationship was loaded and @recent_comments defined because the line was executed.

526

527

If you want to go deeper into the stack trace you can move single +steps+, through your calling methods and into Rails code. This is one of the best ways to find bugs in your code, or perhaps in Ruby or Rails.

528

529

h4. Breakpoints

530

531

A breakpoint makes your application stop whenever a certain point in the program is reached. The debugger shell is invoked in that line.

532

533

You can add breakpoints dynamically with the command +break+ (or just +b+). There are 3 possible ways of adding breakpoints manually:

534

535

* +break line+: set breakpoint in the _line_ in the current source file.

536

* +break file:line [if expression]+: set breakpoint in the _line_ number inside the _file_. If an _expression_ is given it must evaluated to _true_ to fire up the debugger.

537

* +break class(.|\#)method [if expression]+: set breakpoint in _method_ (. and \# for class and instance method respectively) defined in _class_. The _expression_ works the same way as with file:line.

538

539

<shell>

540

(rdb:5) break 10

541

Breakpoint 1 file /PathTo/project/vendor/rails/actionpack/lib/action_controller/filters.rb, line 10

542

</shell>

543

544

Use +info breakpoints _n_+ or +info break _n_+ to list breakpoints. If you supply a number, it lists that breakpoint. Otherwise it lists all breakpoints.

545

546

<shell>

547

(rdb:5) info breakpoints

548

Num Enb What

549

1 y at filters.rb:10

550

</shell>

551

552

To delete breakpoints: use the command +delete _n_+ to remove the breakpoint number _n_. If no number is specified, it deletes all breakpoints that are currently active..

553

554

<shell>

555

(rdb:5) delete 1

556

(rdb:5) info breakpoints

557

No breakpoints.

558

</shell>

559

560

You can also enable or disable breakpoints:

561

562

* +enable breakpoints+: allow a list _breakpoints_ or all of them if no list is specified, to stop your program. This is the default state when you create a breakpoint.

563

* +disable breakpoints+: the _breakpoints_ will have no effect on your program.

564

565

h4. Catching Exceptions

566

567

The command +catch exception-name+ (or just +cat exception-name+) can be used to intercept an exception of type _exception-name_ when there would otherwise be is no handler for it.

568

569

To list all active catchpoints use +catch+.

570

571

h4. Resuming Execution

572

573

There are two ways to resume execution of an application that is stopped in the debugger:

574

575

* +continue+ [line-specification] (or +c+): resume program execution, at the address where your script last stopped; any breakpoints set at that address are bypassed. The optional argument line-specification allows you to specify a line number to set a one-time breakpoint which is deleted when that breakpoint is reached.

576

* +finish+ [frame-number] (or +fin+): execute until the selected stack frame returns. If no frame number is given, the application will run until the currently selected frame returns. The currently selected frame starts out the most-recent frame or 0 if no frame positioning (e.g up, down or frame) has been performed. If a frame number is given it will run until the specified frame returns.

577

578

h4. Editing

579

580

Two commands allow you to open code from the debugger into an editor:

581

582

* +edit [file:line]+: edit _file_ using the editor specified by the EDITOR environment variable. A specific _line_ can also be given.

583

* +tmate _n_+ (abbreviated +tm+): open the current file in TextMate. It uses n-th frame if _n_ is specified.

584

585

h4. Quitting

586

587

To exit the debugger, use the +quit+ command (abbreviated +q+), or its alias +exit+.

588

589

A simple quit tries to terminate all threads in effect. Therefore your server will be stopped and you will have to start it again.

590

591

h4. Settings

592

593

There are some settings that can be configured in ruby-debug to make it easier to debug your code. Here are a few of the available options:

594

595

* +set reload+: Reload source code when changed.

596

* +set autolist+: Execute +list+ command on every breakpoint.

597

* +set listsize _n_+: Set number of source lines to list by default to _n_.

598

* +set forcestep+: Make sure the +next+ and +step+ commands always move to a new line

599

600

You can see the full list by using +help set+. Use +help set _subcommand_+ to learn about a particular +set+ command.

601

602

TIP: You can include any number of these configuration lines inside a +.rdebugrc+ file in your HOME directory. ruby-debug will read this file every time it is loaded. and configure itself accordingly.

603

604

Here's a good start for an +.rdebugrc+:

605

606

<shell>

607

set autolist

608

set forcestep

609

set listsize 25

610

</shell>

611

612

h3. Debugging Memory Leaks

613

614

A Ruby application (on Rails or not), can leak memory - either in the Ruby code or at the C code level.

615

616

In this section, you will learn how to find and fix such leaks by using Bleak House and Valgrind debugging tools.

617

618

h4. BleakHouse

619

620

"BleakHouse":http://github.com/fauna/bleak_house/tree/master is a library for finding memory leaks.

621

622

If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere. Leaks like this can grow slowly and your application will consume more and more memory, gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.

623

624

To install it run:

625

626

<shell>

627

sudo gem install bleak_house

628

</shell>

629

630

Then setup your application for profiling. Then add the following at the bottom of config/environment.rb:

631

632

<ruby>

633

require 'bleak_house' if ENV['BLEAK_HOUSE']

634

</ruby>

635

636

Start a server instance with BleakHouse integration:

637

638

<shell>

639

RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house ./script/server

640

</shell>

641

642

Make sure to run a couple hundred requests to get better data samples, then press +CTRL-C+. The server will stop and Bleak House will produce a dumpfile in +/tmp+:

643

644

<shell>

645

** BleakHouse: working...

646

** BleakHouse: complete

647

** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.

648

</shell>

649

650

To analyze it, just run the listed command. The top 20 leakiest lines will be listed:

651

652

<shell>

653

191691 total objects

654

Final heap size 191691 filled, 220961 free

655

Displaying top 20 most common line/class pairs

656

89513 __null__:__null__:__node__

657

41438 __null__:__null__:String

658

2348 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:Array

659

1508 /opt/local//lib/ruby/gems/1.8/specifications/gettext-1.90.0.gemspec:14:String

660

1021 /opt/local//lib/ruby/gems/1.8/specifications/heel-0.2.0.gemspec:14:String

661

951 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:111:String

662

935 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:String

663

834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array

664

...

665

</shell>

666

667

This way you can find where your application is leaking memory and fix it.

668

669

If "BleakHouse":http://github.com/fauna/bleak_house/tree/master doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter. In that case, try using Valgrind to investigate further.

670

671

h4. Valgrind

672

673

"Valgrind":http://valgrind.org/ is a Linux-only application for detecting C-based memory leaks and race conditions.

674

675

There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls +malloc()+ but is doesn't properly call +free()+, this memory won't be available until the app terminates.

676

677

For further information on how to install Valgrind and use with Ruby, refer to "Valgrind and Ruby":http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/ by Evan Weaver.

678

679

h3. Plugins for Debugging

680

681

There are some Rails plugins to help you to find errors and debug your application. Here is a list of useful plugins for debugging:

682

683

* "Footnotes":http://github.com/drnic/rails-footnotes/tree/master: Every Rails page has footnotes that give request information and link back to your source via TextMate.

684

* "Query Trace":http://github.com/ntalbott/query_trace/tree/master: Adds query origin tracing to your logs.

685

* "Query Stats":http://github.com/dan-manges/query_stats/tree/master: A Rails plugin to track database queries.

686

* "Query Reviewer":http://code.google.com/p/query-reviewer/: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of warnings for each query that it analyzed.

687

* "Exception Notifier":http://github.com/rails/exception_notification/tree/master: Provides a mailer object and a default set of templates for sending email notifications when errors occur in a Rails application.

688

* "Exception Logger":http://github.com/defunkt/exception_logger/tree/master: Logs your Rails exceptions in the database and provides a funky web interface to manage them.

689

690

h3. References

691

692

* "ruby-debug Homepage":http://www.datanoise.com/ruby-debug

693

* "Article: Debugging a Rails application with ruby-debug":http://www.sitepoint.com/article/debug-rails-app-ruby-debug/

694

* "ruby-debug Basics screencast":http://brian.maybeyoureinsane.net/blog/2007/05/07/ruby-debug-basics-screencast/

695

* "Ryan Bate's ruby-debug screencast":http://railscasts.com/episodes/54-debugging-with-ruby-debug

696

* "Ryan Bate's stack trace screencast":http://railscasts.com/episodes/24-the-stack-trace

697

* "Ryan Bate's logger screencast":http://railscasts.com/episodes/56-the-logger

698

* "Debugging with ruby-debug":http://bashdb.sourceforge.net/ruby-debug.html

699

* "ruby-debug cheat sheet":http://cheat.errtheblog.com/s/rdebug/

700

* "Ruby on Rails Wiki: How to Configure Logging":http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging

701

* "Bleak House Documentation":http://blog.evanweaver.com/files/doc/fauna/bleak_house/files/README.html

702

703

h3. Changelog

704

705

"Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/5

706

707

* November 3, 2008: Accepted for publication. Added RJS, memory leaks and plugins chapters by "Emilio Tagua":credits.html#miloops

708

* October 19, 2008: Copy editing pass by "Mike Gunderloy":credits.html#mgunderloy

709

* September 16, 2008: initial version by "Emilio Tagua":credits.html#miloops

Older »