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.

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 report version section #56130

Merged
merged 1 commit into from
Dec 6, 2024
Merged
Changes from all commits
Commits
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
130 changes: 108 additions & 22 deletions doc/api/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -347,28 +347,6 @@
"writeQueueSize": 0,
"readable": true,
"writable": true
},
{
"type": "tcp",
"is_active": true,
"is_referenced": true,
"address": "0x000055e70fcd68c8",
"localEndpoint": {
"host": "ip6-localhost",
"ip6": "::1",
"port": 52266
},
"remoteEndpoint": {
"host": "ip6-localhost",
"ip6": "::1",
"port": 38573
},
"sendBufferSize": 2626560,
"recvBufferSize": 131072,
"fd": 25,
"writeQueueSize": 0,
"readable": false,
"writable": false
}
],
"workers": [],
Expand Down Expand Up @@ -601,11 +579,119 @@
in associating the report dump with the runtime state if generated multiple
times for the same Node.js process.

## Report Version

Diagnostic report has an associated single-digit version number (`report.header.reportVersion`),
uniquely representing the report format. The version number is bumped
when new key is added or removed, or the data type of a value is changed.
Report version definitions are consistent across LTS releases.

### Version history

#### Version 4

<!-- YAML
changes:
- version: v23.3.0
pr-url: https://github.com/nodejs/node/pull/55697

Check warning on line 596 in doc/api/report.md

View workflow job for this annotation

GitHub Actions / lint-pr-url

pr-url doesn't match the URL of the current PR.
description: Added `--report-exclude-env` option for excluding environment variables from report generation.
-->

New fields `ipv4` and `ipv6` are added to `tcp` and `udp` libuv handles endpoints. Examples:

```json
{
"libuv": [
{
"type": "tcp",
"is_active": true,
"is_referenced": true,
"address": "0x000055e70fcb85d8",
"localEndpoint": {
"host": "localhost",
"ip4": "127.0.0.1", // new key
"port": 48986
},
"remoteEndpoint": {
"host": "localhost",
"ip4": "127.0.0.1", // new key
"port": 38573
},
"sendBufferSize": 2626560,
"recvBufferSize": 131072,
"fd": 24,
"writeQueueSize": 0,
"readable": true,
"writable": true
},
{
"type": "tcp",
"is_active": true,
"is_referenced": true,
"address": "0x000055e70fcd68c8",
"localEndpoint": {
"host": "ip6-localhost",
"ip6": "::1", // new key
"port": 52266
},
"remoteEndpoint": {
"host": "ip6-localhost",
"ip6": "::1", // new key
"port": 38573
},
"sendBufferSize": 2626560,
"recvBufferSize": 131072,
"fd": 25,
"writeQueueSize": 0,
"readable": false,
"writable": false
}
]
}
```

#### Version 3

<!-- YAML
changes:
- version:
- v19.1.0
- v18.13.0
pr-url: https://github.com/nodejs/node/pull/45254

Check warning on line 660 in doc/api/report.md

View workflow job for this annotation

GitHub Actions / lint-pr-url

pr-url doesn't match the URL of the current PR.
description: Add more memory info.
-->

The following memory usage keys are added to the `resourceUsage` section.

```json
{
"resourceUsage": {
"rss": "35766272",
"free_memory": "1598337024",
"total_memory": "17179869184",
"available_memory": "1598337024",
"constrained_memory": "36624662528"
}
}
```

#### Version 2

<!-- YAML
changes:
- version:
- v13.9.0
- v12.16.2
pr-url: https://github.com/nodejs/node/pull/31386

Check warning on line 685 in doc/api/report.md

View workflow job for this annotation

GitHub Actions / lint-pr-url

pr-url doesn't match the URL of the current PR.
description: Workers are now included in the report.
-->

Added [`Worker`][] support. Refer to [Interaction with workers](#interaction-with-workers) section for more details.

#### Version 1

This is the first version of the diagnostic report.

## Configuration

Additional runtime configuration of report generation is available via
Expand Down
Loading