◐ Shell
clean mode source ↗

doc: add esm examples to node:trace_events · nodejs/node@ff8af58

@@ -69,9 +69,19 @@ node --trace-event-categories v8,node,node.async_hooks

69697070

Alternatively, trace events may be enabled using the `node:trace_events` module:

717172-

```js

73-

const trace_events = require('node:trace_events');

74-

const tracing = trace_events.createTracing({ categories: ['node.perf'] });

72+

```mjs

73+

import { createTracing } from 'node:trace_events';

74+

const tracing = createTracing({ categories: ['node.perf'] });

75+

tracing.enable(); // Enable trace event capture for the 'node.perf' category

76+77+

// do work

78+79+

tracing.disable(); // Disable trace event capture for the 'node.perf' category

80+

```

81+82+

```cjs

83+

const { createTracing } = require('node:trace_events');

84+

const tracing = createTracing({ categories: ['node.perf'] });

7585

tracing.enable(); // Enable trace event capture for the 'node.perf' category

76867787

// do work

@@ -153,20 +163,36 @@ Disables this `Tracing` object.

153163

Only trace event categories _not_ covered by other enabled `Tracing` objects

154164

and _not_ specified by the `--trace-event-categories` flag will be disabled.

155165156-

```js

157-

const trace_events = require('node:trace_events');

158-

const t1 = trace_events.createTracing({ categories: ['node', 'v8'] });

159-

const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] });

166+

```mjs

167+

import { createTracing, getEnabledCategories } from 'node:trace_events';

168+

const t1 = createTracing({ categories: ['node', 'v8'] });

169+

const t2 = createTracing({ categories: ['node.perf', 'node'] });

170+

t1.enable();

171+

t2.enable();

172+173+

// Prints 'node,node.perf,v8'

174+

console.log(getEnabledCategories());

175+176+

t2.disable(); // Will only disable emission of the 'node.perf' category

177+178+

// Prints 'node,v8'

179+

console.log(getEnabledCategories());

180+

```

181+182+

```cjs

183+

const { createTracing, getEnabledCategories } = require('node:trace_events');

184+

const t1 = createTracing({ categories: ['node', 'v8'] });

185+

const t2 = createTracing({ categories: ['node.perf', 'node'] });

160186

t1.enable();

161187

t2.enable();

162188163189

// Prints 'node,node.perf,v8'

164-

console.log(trace_events.getEnabledCategories());

190+

console.log(getEnabledCategories());

165191166192

t2.disable(); // Will only disable emission of the 'node.perf' category

167193168194

// Prints 'node,v8'

169-

console.log(trace_events.getEnabledCategories());

195+

console.log(getEnabledCategories());

170196

```

171197172198

#### `tracing.enable()`

@@ -200,10 +226,19 @@ added: v10.0.0

200226201227

Creates and returns a `Tracing` object for the given set of `categories`.

202228203-

```js

204-

const trace_events = require('node:trace_events');

229+

```mjs

230+

import { createTracing } from 'node:trace_events';

231+

const categories = ['node.perf', 'node.async_hooks'];

232+

const tracing = createTracing({ categories });

233+

tracing.enable();

234+

// do stuff

235+

tracing.disable();

236+

```

237+238+

```cjs

239+

const { createTracing } = require('node:trace_events');

205240

const categories = ['node.perf', 'node.async_hooks'];

206-

const tracing = trace_events.createTracing({ categories });

241+

const tracing = createTracing({ categories });

207242

tracing.enable();

208243

// do stuff

209244

tracing.disable();

@@ -226,23 +261,71 @@ Given the file `test.js` below, the command

226261

`node --trace-event-categories node.perf test.js` will print

227262

`'node.async_hooks,node.perf'` to the console.

228263229-

```js

230-

const trace_events = require('node:trace_events');

231-

const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] });

232-

const t2 = trace_events.createTracing({ categories: ['node.perf'] });

233-

const t3 = trace_events.createTracing({ categories: ['v8'] });

264+

```mjs

265+

import { createTracing, getEnabledCategories } from 'node:trace_events';

266+

const t1 = createTracing({ categories: ['node.async_hooks'] });

267+

const t2 = createTracing({ categories: ['node.perf'] });

268+

const t3 = createTracing({ categories: ['v8'] });

269+270+

t1.enable();

271+

t2.enable();

272+273+

console.log(getEnabledCategories());

274+

```

275+276+

```cjs

277+

const { createTracing, getEnabledCategories } = require('node:trace_events');

278+

const t1 = createTracing({ categories: ['node.async_hooks'] });

279+

const t2 = createTracing({ categories: ['node.perf'] });

280+

const t3 = createTracing({ categories: ['v8'] });

234281235282

t1.enable();

236283

t2.enable();

237284238-

console.log(trace_events.getEnabledCategories());

285+

console.log(getEnabledCategories());

239286

```

240287241288

## Examples

242289243290

### Collect trace events data by inspector

244291245-

```js

292+

```mjs

293+

import { Session } from 'node:inspector';

294+

const session = new Session();

295+

session.connect();

296+297+

function post(message, data) {

298+

return new Promise((resolve, reject) => {

299+

session.post(message, data, (err, result) => {

300+

if (err)

301+

reject(new Error(JSON.stringify(err)));

302+

else

303+

resolve(result);

304+

});

305+

});

306+

}

307+308+

async function collect() {

309+

const data = [];

310+

session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));

311+

session.on('NodeTracing.tracingComplete', () => {

312+

// done

313+

});

314+

const traceConfig = { includedCategories: ['v8'] };

315+

await post('NodeTracing.start', { traceConfig });

316+

// do something

317+

setTimeout(() => {

318+

post('NodeTracing.stop').then(() => {

319+

session.disconnect();

320+

console.log(data);

321+

});

322+

}, 1000);

323+

}

324+325+

collect();

326+

```

327+328+

```cjs

246329

'use strict';

247330248331

const { Session } = require('inspector');