doc/man7/openssl-qlog.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 openssl-qlog - OpenSSL qlog tracing functionality

 =head1 DESCRIPTION

 OpenSSL has unstable support for generating logs in the qlog logging format,
 which can be used to obtain diagnostic data for QUIC connections. The data
 generated includes information on packets sent and received and the frames
 contained within them, as well as loss detection and other events.

 The qlog output generated by OpenSSL can be used to obtain diagnostic
 visualisations of a given QUIC connection using tools such as B<qvis>.

 B<WARNING:> The output of OpenSSL's qlog functionality uses an unstable format
 based on a draft specification. qlog output is not subject to any format
 stability or compatibility guarantees at this time, and B<will> change in
 incompatible ways in future versions of OpenSSL. See B<FORMAT STABILITY> below
 for details.

 =head1 USAGE

 When OpenSSL is built with qlog support, qlog is enabled at run time by setting
 the standard B<QLOGDIR> environment variable to point to a directory where qlog
 files should be written. Once set, any QUIC connection established by OpenSSL
 will have a qlog file written automatically to the specified directory.

 Log files are generated in the I<.sqlog> format based on JSON-SEQ (RFC 7464).

 The filenames of generated log files under the specified B<QLOGDIR> use the
 following structure:

     {connection_odcid}_{vantage_point_type}.sqlog

 where B<{connection_odcid}> is the lowercase hexadecimal encoding of a QUIC
 connection's Original Destination Connection ID, which is the Destination
 Connection ID used in the header of the first Initial packet sent as part of the
 connection process, and B<{vantage_point_type}> is either C<client> or
 C<server>, reflecting the perspective of the endpoint producing the qlog output.

 The qlog functionality can be disabled at OpenSSL build time using the
 I<no-unstable-qlog> configure flag.

 =head1 SUPPORTED EVENT TYPES

 The following event types are currently supported:

 =over 4

 =item B<connectivity:connection_started>

 =item B<connectivity:connection_state_updated>

 =item B<connectivity:connection_closed>

 =item B<transport:parameters_set>

 =item B<transport:packet_sent>

 =item B<transport:packet_received>

 =item B<recovery:packet_lost>

 =back

 =head1 FILTERS

 By default, all supported event types are logged. The B<OSSL_QFILTER>
 environment variable can be used to configure a filter specification which
 determines which event types are to be logged. Each event type can be turned on
 and off individually. The filter specification is a space-separated list of
 terms listing event types to enable or disable. The terms are applied in order,
 thus the effects of later terms override the effects of earlier terms.

 =head2 Examples

 Here are some example filter specifications:

 =over 4

 =item C<*> (or C<+*>)

 Enable all supported qlog event types.

 =item C<-*>

 Disable all qlog event types.

 =item C<* -transport:packet_received>

 Enable all qlog event types, but disable the B<transport:packet_received> event
 type.

 =item C<-* transport:packet_sent>

 Disable all qlog event types, except for the B<transport:packet_sent> event type.

 =item C<-* connectivity:* transport:parameters_set>

 Disable all qlog event types, except for B<transport:parameters_set> and all
 supported event types in the B<connectivity> category.

 =back

 =head2 Filter Syntax Specification

 Formally, the format of the filter specification in ABNF is as follows:

     filter              = *filter-term

     filter-term         = add-sub-term

     add-sub-term        = ["-" / "+"] specifier

     specifier           = global-specifier / qualified-specifier

     global-specifier    = wildcard

     qualified-specifier = component-specifier ":" component-specifier

     component-specifier = name / wildcard

     wildcard            = "*"

     name                = 1*(ALPHA / DIGIT / "_" / "-")

 Filter terms are interpreted as follows:

 =over 4

 =item C<+*> (or C<*>)

 Enables all event types.

 =item C<-*>

 Disables all event types.

 =item C<+foo:*> (or C<foo:*>)

 Enables all event types in the B<foo> category.

 =item C<-foo:*>

 Disables all event types in the B<foo> category.

 =item C<+foo:bar> (or C<foo:bar>)

 Enables a specific event type B<foo:bar>.

 =item C<-foo:bar>

 Disables a specific event type B<foo:bar>.

 =back

 Partial wildcard matches are not supported at this time.

 =head2 Default Configuration

 If the B<OSSL_QFILTER> environment variable is not set or set to the empty
 string, this is equivalent to enabling all event types (i.e., it is equivalent
 to a filter of C<*>). Note that the B<QLOGDIR> environment variable must also be
 set to enable qlog.

 =head1 FORMAT STABILITY

 The OpenSSL qlog functionality currently implements a draft version of the qlog
 specification. Future revisions to the qlog specification in advance of formal
 standardisation are expected to introduce incompatible and breaking changes to
 the qlog format. The OpenSSL qlog functionality will transition to producing
 output in this format in the future once standardisation is complete.

 Because of this, the qlog output of OpenSSL B<will> change in incompatible and
 breaking ways in the future, including in non-major releases of OpenSSL. The
 qlog output of OpenSSL is considered unstable and not subject to any format
 stability or compatibility guarantees at this time.

 Users of the OpenSSL qlog functionality must be aware that the output may change
 arbitrarily between releases and that the preservation of compatibility with any
 given tool between releases is not guaranteed.

 =head2 Aims

 The OpenSSL draft qlog functionality is primarily intended for use in
 conjunction with the qvis tool L<https://qvis.quictools.info/>. In terms of
 format compatibility, the output format of the OpenSSL qlog functionality is
 expected to track what is supported by qvis. As such, future changes to the
 output of the OpenSSL qlog functionality are expected to track changes in qvis
 as they occur, and reflect the versions of qlog currently supported by qvis.

 This means that prior to the finalisation of the qlog standard, in the event of
 a disparity between the current draft and what qvis supports, the OpenSSL qlog
 functionality will generally aim for qvis compatibility over compliance with the
 latest draft.

 As such, OpenSSL's qlog functionality currently implements qlog version 0.3 as
 defined in B<draft-ietf-quic-qlog-main-schema-05> and
 B<draft-ietf-quic-qlog-quic-events-04>. These revisions are intentionally used
 instead of more recent revisions due to their qvis compatibility.

 =head1 LIMITATIONS

 The OpenSSL implementation of qlog currently has the following limitations:

 =over 4

 =item

 Not all event types defined by the draft specification are implemented.

 =item

 Only the JSON-SEQ (B<.sqlog>) output format is supported.

 =item

 Only the B<QLOGDIR> environment variable is supported for configuring the qlog
 output directory. The standard B<QLOGFILE> environment variable is not
 supported.

 =item

 There is no API for programmatically enabling or controlling the qlog
 functionality.

 =back

 =head1 SEE ALSO

 L<openssl-quic(7)>, L<openssl-env(7)>

 =head1 HISTORY

 This functionality was added in OpenSSL 3.3.

 =head1 COPYRIGHT

 Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.

 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.

 =cut
	=pod

	=head1 NAME

	openssl-qlog - OpenSSL qlog tracing functionality

	=head1 DESCRIPTION

	OpenSSL has unstable support for generating logs in the qlog logging format,
	which can be used to obtain diagnostic data for QUIC connections. The data
	generated includes information on packets sent and received and the frames
	contained within them, as well as loss detection and other events.

	The qlog output generated by OpenSSL can be used to obtain diagnostic
	visualisations of a given QUIC connection using tools such as B<qvis>.

	B<WARNING:> The output of OpenSSL's qlog functionality uses an unstable format
	based on a draft specification. qlog output is not subject to any format
	stability or compatibility guarantees at this time, and B<will> change in
	incompatible ways in future versions of OpenSSL. See B<FORMAT STABILITY> below
	for details.

	=head1 USAGE

	When OpenSSL is built with qlog support, qlog is enabled at run time by setting
	the standard B<QLOGDIR> environment variable to point to a directory where qlog
	files should be written. Once set, any QUIC connection established by OpenSSL
	will have a qlog file written automatically to the specified directory.

	Log files are generated in the I<.sqlog> format based on JSON-SEQ (RFC 7464).

	The filenames of generated log files under the specified B<QLOGDIR> use the
	following structure:

	{connection_odcid}_{vantage_point_type}.sqlog

	where B<{connection_odcid}> is the lowercase hexadecimal encoding of a QUIC
	connection's Original Destination Connection ID, which is the Destination
	Connection ID used in the header of the first Initial packet sent as part of the
	connection process, and B<{vantage_point_type}> is either C<client> or
	C<server>, reflecting the perspective of the endpoint producing the qlog output.

	The qlog functionality can be disabled at OpenSSL build time using the
	I<no-unstable-qlog> configure flag.

	=head1 SUPPORTED EVENT TYPES

	The following event types are currently supported:

	=over 4

	=item B<connectivity:connection_started>

	=item B<connectivity:connection_state_updated>

	=item B<connectivity:connection_closed>

	=item B<transport:parameters_set>

	=item B<transport:packet_sent>

	=item B<transport:packet_received>

	=item B<recovery:packet_lost>

	=back

	=head1 FILTERS

	By default, all supported event types are logged. The B<OSSL_QFILTER>
	environment variable can be used to configure a filter specification which
	determines which event types are to be logged. Each event type can be turned on
	and off individually. The filter specification is a space-separated list of
	terms listing event types to enable or disable. The terms are applied in order,
	thus the effects of later terms override the effects of earlier terms.

	=head2 Examples

	Here are some example filter specifications:

	=over 4

	=item C<> (or C<+>)

	Enable all supported qlog event types.

	=item C<-*>

	Disable all qlog event types.

	=item C<* -transport:packet_received>

	Enable all qlog event types, but disable the B<transport:packet_received> event
	type.

	=item C<-* transport:packet_sent>

	Disable all qlog event types, except for the B<transport:packet_sent> event type.

	=item C<-* connectivity:* transport:parameters_set>

	Disable all qlog event types, except for B<transport:parameters_set> and all
	supported event types in the B<connectivity> category.

	=back

	=head2 Filter Syntax Specification

	Formally, the format of the filter specification in ABNF is as follows:

	filter = *filter-term

	filter-term = add-sub-term

	add-sub-term = ["-" / "+"] specifier

	specifier = global-specifier / qualified-specifier

	global-specifier = wildcard

	qualified-specifier = component-specifier ":" component-specifier

	component-specifier = name / wildcard

	wildcard = "*"

	name = 1*(ALPHA / DIGIT / "_" / "-")

	Filter terms are interpreted as follows:

	=over 4

	=item C<+> (or C<>)

	Enables all event types.

	=item C<-*>

	Disables all event types.

	=item C<+foo:> (or C<foo:>)

	Enables all event types in the B<foo> category.

	=item C<-foo:*>

	Disables all event types in the B<foo> category.

	=item C<+foo:bar> (or C<foo:bar>)

	Enables a specific event type B<foo:bar>.

	=item C<-foo:bar>

	Disables a specific event type B<foo:bar>.

	=back

	Partial wildcard matches are not supported at this time.

	=head2 Default Configuration

	If the B<OSSL_QFILTER> environment variable is not set or set to the empty
	string, this is equivalent to enabling all event types (i.e., it is equivalent
	to a filter of C<*>). Note that the B<QLOGDIR> environment variable must also be
	set to enable qlog.

	=head1 FORMAT STABILITY

	The OpenSSL qlog functionality currently implements a draft version of the qlog
	specification. Future revisions to the qlog specification in advance of formal
	standardisation are expected to introduce incompatible and breaking changes to
	the qlog format. The OpenSSL qlog functionality will transition to producing
	output in this format in the future once standardisation is complete.

	Because of this, the qlog output of OpenSSL B<will> change in incompatible and
	breaking ways in the future, including in non-major releases of OpenSSL. The
	qlog output of OpenSSL is considered unstable and not subject to any format
	stability or compatibility guarantees at this time.

	Users of the OpenSSL qlog functionality must be aware that the output may change
	arbitrarily between releases and that the preservation of compatibility with any
	given tool between releases is not guaranteed.

	=head2 Aims

	The OpenSSL draft qlog functionality is primarily intended for use in
	conjunction with the qvis tool L<https://qvis.quictools.info/>. In terms of
	format compatibility, the output format of the OpenSSL qlog functionality is
	expected to track what is supported by qvis. As such, future changes to the
	output of the OpenSSL qlog functionality are expected to track changes in qvis
	as they occur, and reflect the versions of qlog currently supported by qvis.

	This means that prior to the finalisation of the qlog standard, in the event of
	a disparity between the current draft and what qvis supports, the OpenSSL qlog
	functionality will generally aim for qvis compatibility over compliance with the
	latest draft.

	As such, OpenSSL's qlog functionality currently implements qlog version 0.3 as
	defined in B<draft-ietf-quic-qlog-main-schema-05> and
	B<draft-ietf-quic-qlog-quic-events-04>. These revisions are intentionally used
	instead of more recent revisions due to their qvis compatibility.

	=head1 LIMITATIONS

	The OpenSSL implementation of qlog currently has the following limitations:

	=over 4

	=item

	Not all event types defined by the draft specification are implemented.

	=item

	Only the JSON-SEQ (B<.sqlog>) output format is supported.

	=item

	Only the B<QLOGDIR> environment variable is supported for configuring the qlog
	output directory. The standard B<QLOGFILE> environment variable is not
	supported.

	=item

	There is no API for programmatically enabling or controlling the qlog
	functionality.

	=back

	=head1 SEE ALSO

	L<openssl-quic(7)>, L<openssl-env(7)>

	=head1 HISTORY

	This functionality was added in OpenSSL 3.3.

	=head1 COPYRIGHT

	Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.

	Licensed under the Apache License 2.0 (the "License"). You may not use
	this file except in compliance with the License. You can obtain a copy
	in the file LICENSE in the source distribution or at
	L<https://www.openssl.org/source/license.html>.

	=cut