Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add esm examples to node:trace_events #56514

Merged
merged 1 commit into from
Jan 10, 2025
Merged

doc: add esm examples to node:trace_events #56514

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 102 additions & 19 deletions doc/api/tracing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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()`
Expand Down Expand Up @@ -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();
Expand All @@ -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('node:inspector');
Expand Down
Loading