doc: add esm examples to node:trace_events

mfdebian · marco-ippolito · commit ff8af5804659 · 2025-03-06T13:38:08.000+01:00
PR-URL: #56514 Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/doc/api/tracing.md b/doc/api/tracing.md
@@ -69,9 +69,19 @@ node --trace-event-categories v8,node,node.async_hooks
 
 Alternatively, trace events may be enabled using the `node:trace_events` module:
 
-```js
-const trace_events = require('node:trace_events');
-const tracing = trace_events.createTracing({ categories: ['node.perf'] });
+```mjs
+import { createTracing } from 'node:trace_events';
+const tracing = createTracing({ categories: ['node.perf'] });
+tracing.enable();  // Enable trace event capture for the 'node.perf' category
+
+// do work
+
+tracing.disable();  // Disable trace event capture for the 'node.perf' category
+```
+
+```cjs
+const { createTracing } = require('node:trace_events');
+const tracing = createTracing({ categories: ['node.perf'] });
 tracing.enable();  // Enable trace event capture for the 'node.perf' category
 
 // do work
@@ -153,20 +163,36 @@ Disables this `Tracing` object.
 Only trace event categories _not_ covered by other enabled `Tracing` objects
 and _not_ specified by the `--trace-event-categories` flag will be disabled.
 
-```js
-const trace_events = require('node:trace_events');
-const t1 = trace_events.createTracing({ categories: ['node', 'v8'] });
-const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] });
+```mjs
+import { createTracing, getEnabledCategories } from 'node:trace_events';
+const t1 = createTracing({ categories: ['node', 'v8'] });
+const t2 = createTracing({ categories: ['node.perf', 'node'] });
+t1.enable();
+t2.enable();
+
+// Prints 'node,node.perf,v8'
+console.log(getEnabledCategories());
+
+t2.disable(); // Will only disable emission of the 'node.perf' category
+
+// Prints 'node,v8'
+console.log(getEnabledCategories());
+```
+
+```cjs
+const { createTracing, getEnabledCategories } = require('node:trace_events');
+const t1 = createTracing({ categories: ['node', 'v8'] });
+const t2 = createTracing({ categories: ['node.perf', 'node'] });
 t1.enable();
 t2.enable();
 
 // Prints 'node,node.perf,v8'
-console.log(trace_events.getEnabledCategories());
+console.log(getEnabledCategories());
 
 t2.disable(); // Will only disable emission of the 'node.perf' category
 
 // Prints 'node,v8'
-console.log(trace_events.getEnabledCategories());
+console.log(getEnabledCategories());
 ```
 
 #### `tracing.enable()`
@@ -200,10 +226,19 @@ added: v10.0.0
 
 Creates and returns a `Tracing` object for the given set of `categories`.
 
-```js
-const trace_events = require('node:trace_events');
+```mjs
+import { createTracing } from 'node:trace_events';
+const categories = ['node.perf', 'node.async_hooks'];
+const tracing = createTracing({ categories });
+tracing.enable();
+// do stuff
+tracing.disable();
+```
+
+```cjs
+const { createTracing } = require('node:trace_events');
 const categories = ['node.perf', 'node.async_hooks'];
-const tracing = trace_events.createTracing({ categories });
+const tracing = createTracing({ categories });
 tracing.enable();
 // do stuff
 tracing.disable();
@@ -226,23 +261,71 @@ Given the file `test.js` below, the command
 `node --trace-event-categories node.perf test.js` will print
 `'node.async_hooks,node.perf'` to the console.
 
-```js
-const trace_events = require('node:trace_events');
-const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] });
-const t2 = trace_events.createTracing({ categories: ['node.perf'] });
-const t3 = trace_events.createTracing({ categories: ['v8'] });
+```mjs
+import { createTracing, getEnabledCategories } from 'node:trace_events';
+const t1 = createTracing({ categories: ['node.async_hooks'] });
+const t2 = createTracing({ categories: ['node.perf'] });
+const t3 = createTracing({ categories: ['v8'] });
+
+t1.enable();
+t2.enable();
+
+console.log(getEnabledCategories());
+```
+
+```cjs
+const { createTracing, getEnabledCategories } = require('node:trace_events');
+const t1 = createTracing({ categories: ['node.async_hooks'] });
+const t2 = createTracing({ categories: ['node.perf'] });
+const t3 = createTracing({ categories: ['v8'] });
 
 t1.enable();
 t2.enable();
 
-console.log(trace_events.getEnabledCategories());
+console.log(getEnabledCategories());
 ```
 
 ## Examples
 
 ### Collect trace events data by inspector
 
-```js
+```mjs
+import { Session } from 'node:inspector';
+const session = new Session();
+session.connect();
+
+function post(message, data) {
+  return new Promise((resolve, reject) => {
+    session.post(message, data, (err, result) => {
+      if (err)
+        reject(new Error(JSON.stringify(err)));
+      else
+        resolve(result);
+    });
+  });
+}
+
+async function collect() {
+  const data = [];
+  session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));
+  session.on('NodeTracing.tracingComplete', () => {
+    // done
+  });
+  const traceConfig = { includedCategories: ['v8'] };
+  await post('NodeTracing.start', { traceConfig });
+  // do something
+  setTimeout(() => {
+    post('NodeTracing.stop').then(() => {
+      session.disconnect();
+      console.log(data);
+    });
+  }, 1000);
+}
+
+collect();
+```
+
+```cjs
 'use strict';
 
 const { Session } = require('inspector');
