Doc(TSG): stream abortion and logging (#3986)

docs/Diagnostics.md

@@ -15,6 +15,14 @@ On Windows, MsQuic leverages manifested [ETW](https://docs.microsoft.com/en-us/w
 
 ### Linux
 
+#### stdout
+
+The easiest and quickest way to enable msquic logging is by compiling msquic with the following cmake arguments to direct the logs to standard output:
+
+```sh
+cmake -D QUIC_ENABLE_LOGGING=ON -D QUIC_LOGGING_TYPE=stdout ...
+```
+
 #### LTTng
 On Linux, MsQuic leverages [LTTng](https://lttng.org/features/) for its logging. Some dependencies, such as babeltrace, lttng, and clog2text_lttng are required. The simplest way to install all dependencies is by running `./scripts/prepare-machine.ps1 -ForTest`, but if you only want to collect the traces on the machine, the **minimal dependencies** are:
 

docs/TSG.md

@@ -5,24 +5,30 @@ This document is meant to be a step-by-step guide for trouble shooting any issue
 ## What kind of Issue are you having?
 
 1. [I am debugging a crash.](#debugging-a-crash)
-2. [Something is not functionally working as I expect.](#trouble-shooting-a-functional-issue)
-3. [Performance is not what I expect it to be.](#trouble-shooting-a-performance-issue)
+1. [Something is not functionally working as I expect.](#trouble-shooting-a-functional-issue)
+1. [Performance is not what I expect it to be.](#trouble-shooting-a-performance-issue)
 
 # Debugging a Crash
 
 > TODO
 
 # Trouble Shooting a Functional Issue
 
+1. [MsQuic logging?](#logging)
 1. [I am getting an error code I don't understand.](#understanding-error-codes)
-2. [The connection is unexpectedly shutting down.](#why-is-the-connection-shutting-down)
-3. [No application (stream) data seems to be flowing.](#why-isnt-application-data-flowing)
-4. [Why is this API failing?](#why-is-this-api-failing)
-5. [An MsQuic API is hanging.](#why-is-the-api-hanging-or-deadlocking)
-6. [I am having problems with SMB over QUIC.](#trouble-shooting-smb-over-quic-issues)
-7. [No credentials when loading a server certificate from PEM with Schannel.](#convert-pem-to-pkcs12-for-schannel)
-8. [TLS handshake fails in Chrome and Edge for HTTP/3 (including WebTransport) even though HTTP/1.1 and HTTP/2 work.](#using-a-self-signed-certificate-for-http3)
-9. [I need to get a packet capture](#collecting-a-packet-capture).
+1. [The connection is unexpectedly shutting down.](#why-is-the-connection-shutting-down)
+1. [The stream is aborted](#the-stream-is-aborted)
+1. [No application (stream) data seems to be flowing.](#why-isnt-application-data-flowing)
+1. [Why is this API failing?](#why-is-this-api-failing)
+1. [An MsQuic API is hanging.](#why-is-the-api-hanging-or-deadlocking)
+1. [I am having problems with SMB over QUIC.](#trouble-shooting-smb-over-quic-issues)
+1. [No credentials when loading a server certificate from PEM with Schannel.](#convert-pem-to-pkcs12-for-schannel)
+1. [TLS handshake fails in Chrome and Edge for HTTP/3 (including WebTransport) even though HTTP/1.1 and HTTP/2 work.](#using-a-self-signed-certificate-for-http3)
+1. [I need to get a packet capture](#collecting-a-packet-capture).
+
+## Logging
+
+See [Tracing](./Diagnostics.md#Built-in Tracing)
 
 ## Understanding Error Codes
 
@@ -76,6 +82,21 @@ As indicated in [Understanding shutdown by Transport](#understanding-shutdown-by
 
 The error code indicated in this event is completely application defined (type of `QUIC_UINT62`). The transport has no understanding of the meaning of this value. It never generates these error codes itself. So, to map these values to some meaning will require the application protocol documentation.
 
+## The stream is aborted.
+
+Stream abortion is stream terminated abruptly. 
+
+### Remote Stream is aborted by my side?
+
+symptom: Peer complains starting stream is failed due to remote abortion.
+
+The remote stream maybe aborted locally by
+
+- Local calls the [StreamShutdown](./api/StreamShutdown.md) with **abortive** flags
+- Local calls the [StreamClose](./api/StreamClose.md)
+- Local calls the [ConnectionShutdown](./api/ConnectionShutdown.md)
+- Connection callback handler returns the value other than `QUIC_STATUS_SUCCESS` for event: `QUIC_CONNECTION_EVENT_PEER_STREAM_STARTED` 
+
 ## Why isn't application data flowing?
 
 Application data is exchanged via [Streams](./Streams.md) and queued by the app via [StreamSend](./api/StreamSend.md). The act of queuing data doesn't mean it will be immediately sent to the peer. There are a number of things that can block or delay the exchange. The `QUIC_FLOW_BLOCK_REASON` enum in [quic_trace.h](../src/inc/quic_trace.h) contains the full list of reasons that data may be blocked. Below is a short explanation of each:
@@ -229,7 +250,15 @@ See [FlyByWireless.CustomCertificate.Generate()](https://github.com/wegylexy/web
 
 ### Linux Packet Capture
 
-> TODO
+``` sh
+# Capture from any interface, all the udp traffic on the host and write it to the msquic.pcap file 
+tcpdump -i any udp -w msquic.pcap
+```
+
+```sh 
+# wireshark to view it. (You need load SSLKEYLOGFILE for the session key to decrypt the session)
+wireshark ./msquic.pcap
+```
 
 ### Window Packet Capture