Skip to content

Commit

Permalink
doc: add report version and history section
Browse files Browse the repository at this point in the history
PR-URL: #56130
Backport-PR-URL: #56055
Refs: #56068
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
PR-URL: #55697
  • Loading branch information
legendecas authored and aduh95 committed Dec 10, 2024
1 parent 803cc3b commit ba63702
Showing 1 changed file with 108 additions and 22 deletions.
130 changes: 108 additions & 22 deletions doc/api/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -345,28 +345,6 @@ is provided below for reference.
"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 @@ -599,11 +577,119 @@ includes the date, time, PID, and a sequence number. The sequence number helps
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: REPLACEME
pr-url: https://github.com/nodejs/node/pull/55697

Check warning on line 594 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 658 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 683 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

0 comments on commit ba63702

Please sign in to comment.