diff --git a/_includes/api/en/4x/app-instrument.md b/_includes/api/en/4x/app-instrument.md
new file mode 100644
index 0000000000..dbb5ff231c
--- /dev/null
+++ b/_includes/api/en/4x/app-instrument.md
@@ -0,0 +1,22 @@
+app.instrument(tracer)
+
+Add a tracer to the application object. This tracer will be activated each time
+the `trace` method of a response is called.
+
+A tracer is a function which takes an options object as argument. It has the
+following field:
+
+* `res`: Response that fired the tracing.
+* `req`: Request related to the response that fired the tracing.
+* `app`: Application object.
+* `event`: String sent by the response to name the event.
+* `date`: Date when the tracing occured.
+* `args`: Additional arguments provided by the tracing call.
+
+For example:
+
+```js
+app.instrument(function(options){
+ debug(options.event + ' ' + options.date + ' ' + options.argv[0]);
+});
+```
diff --git a/_includes/api/en/4x/app.md b/_includes/api/en/4x/app.md
index 1ae17699c7..573f0d8401 100644
--- a/_includes/api/en/4x/app.md
+++ b/_includes/api/en/4x/app.md
@@ -82,6 +82,10 @@ The Express application object can be referred from the [request object](#req) a
{% include api/en/4x/app-get-method.md %}
+
+ {% include api/en/4x/app-instrument.md %}
+
+
{% include api/en/4x/app-listen.md %}
diff --git a/_includes/api/en/4x/res-trace.md b/_includes/api/en/4x/res-trace.md
new file mode 100644
index 0000000000..bdea587dc3
--- /dev/null
+++ b/_includes/api/en/4x/res-trace.md
@@ -0,0 +1,15 @@
+res.trace(event [, parameters])
+
+Fire all tracers instrumented at the application level.
+
+Optional parameters:
+
+- `event`, name of the event to send to tracers.
+- `parameters`, additional parameters to send to tracers.
+
+```js
+app.get('/', function(req, res){
+ res.trace('index:visited', 'my-parameter');
+ res.render('index');
+});
+```
diff --git a/_includes/api/en/4x/res.md b/_includes/api/en/4x/res.md
index a04b360687..990296672b 100644
--- a/_includes/api/en/4x/res.md
+++ b/_includes/api/en/4x/res.md
@@ -121,6 +121,10 @@ and supports all [built-in fields and methods](https://nodejs.org/api/http.html#
{% include api/en/4x/res-type.md %}
+
+ {% include api/en/4x/res-trace.md %}
+
+
{% include api/en/4x/res-vary.md %}
diff --git a/en/guide/debugging.md b/en/guide/debugging.md
index 7b1630edb8..1fab462a4e 100755
--- a/en/guide/debugging.md
+++ b/en/guide/debugging.md
@@ -116,3 +116,142 @@ $ DEBUG=http,mail,express:* node index.js
For more information about `debug`, see the [debug](https://www.npmjs.com/package/debug).
+
+## Tracing
+
+Express offers tracing capabilities. It allows you to follow and inspect the
+behaviour of your controllers through the response object.
+It requires that you instrument your application with tracers. Then you can simply call a `trace` method on your response object each time you want to record something.
+
+### Example 1: add debug messages.
+
+```
+var express = require('express')
+var debug = require('debug')('trace:response')
+
+var app = express()
+
+app.instrument(function (options){
+ debug(options.date + ' ' + options.event)
+})
+
+app.get('/', function (req, res){
+ res.trace('index:hello')
+ res.send('hello world')
+})
+```
+
+### Example 2: Time interval
+
+In some cases you, may want to capture time spent on a specific request. Here
+is a way to do it through tracing.
+
+```
+var express = require('express');
+var debug = require('debug')('trace:response');
+
+var app = express();
+var responseTime = {};
+
+app.instrument(function (options){
+ if (options.event === 'duration:start') {
+ responseTime[options.res.id] = options.date;
+ } else if (options.event === 'duration:end') {
+ var interval = options.date - responseTime[options.res.id];
+ debug(options.req.path + ' - ' + interval + 'ms');
+ delete responseTime[options.res.id];
+ }
+})
+
+app.use(function(req, res, next){
+ res.id = Math.floor(Math.random() * 1000000);
+ res.trace('duration:start');
+ next();
+});
+
+app.get('/', function (req, res){
+ res.trace('index:hello');
+ res.send('hello world');
+ res.trace('duration:end');
+})
+```
+
+### Example 3: send information to dtrace.
+
+Dtrace is a common tool for tracing. It generates probes that will listen and
+report any event targeted to it. You can simply reach the probe via the trace
+function.
+
+```
+var express = require('express');
+var dtrace = require('dtrace-provider');
+
+var app = express();
+
+var dtp = dtrace.createDTraceProvider("nodeapp");
+var p1 = dtp.addProbe("probe1", "char *", "char *");
+var p2 = dtp.addProbe("probe2", "char *", "char *");
+dtp.enable();
+
+app.instrument(function (options){
+ dtp.fire("probe1", function(){
+ return [options.event, options.date];
+ });
+ dtp.fire("probe2", function(){
+ return [options.event, options.args[0]];
+ });
+});
+
+app.get('/', function (req, res){
+ res.trace('index:hello');
+ res.send('hello world');
+})
+
+app.listen(3000);
+```
+
+### Example 4: Send information to chrome tracer.
+
+You may want to use the chrome tracer to analyze only some response behaviour.
+
+```
+var express = require('./index');
+var app = express();
+
+var events = [];
+
+app.instrument(function (options){
+ if (options.event === 'start') {
+ events.push({
+ "name": options.args[0],
+ "cat": "PERF",
+ "ph": "B",
+ "pid": process.pid,
+ "ts": options.date.getTime()
+ });
+ } else if (options.event === 'end') {
+ events.push({
+ "name": options.args[0],
+ "cat": "PERF",
+ "ph": "E",
+ "pid": process.pid,
+ "ts": options.date.getTime()
+ });
+ }
+})
+
+app.get('/', function (req, res, next){
+ res.trace('start', 'index');
+ setTimeout(function () {
+ res.send('hello world');
+ res.trace('end');
+ }, Math.random() * 100);
+})
+
+process.on('SIGINT', function (){
+ require('fs').writeFileSync('./myfile', JSON.stringify(events));
+ process.exit(0);
+})
+
+app.listen(3000);
+```