QLOG support (headers) More...

#include <glib.h>
#include <jansson.h>
#include "refcount.h"
#include "mutex.h"

Include dependency graph for qlog.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	imquic_qlog
	QLOG instance. More...

Macros
QLOG properties definitions
#define	IMQUIC_QLOG_TRIGGER_INTERNAL_ERROR "internal_error"
	Trigger definitions.

#define	IMQUIC_QLOG_TRIGGER_REJECTED "rejected"

#define	IMQUIC_QLOG_TRIGGER_UNSUPPORTED "unsupported"

#define	IMQUIC_QLOG_TRIGGER_INVALID "invalid"

#define	IMQUIC_QLOG_TRIGGER_DUPLICATE "duplicate"

#define	IMQUIC_QLOG_TRIGGER_CONNECTION_UNKNOWN "connection_unknown"

#define	IMQUIC_QLOG_TRIGGER_DECRYPTION_FAILURE "decryption_failure"

#define	IMQUIC_QLOG_TRIGGER_KEY_UNAVAILABLE "key_unavailable"

#define	IMQUIC_QLOG_TRIGGER_GENERAL "general"

Functions
gboolean	imquic_qlog_is_supported (void)
	Helper method to check if QLOG is supported at runtime.

QLOG events tracing
json_t *	imquic_qlog_event_prepare (const char *name)
	Helper to create a new QLOG event by name.

json_t *	imquic_qlog_event_add_data (json_t *event)
	Helper to add a `data` object to an event and return a pointer to it.

void	imquic_qlog_event_add_raw (json_t parent, const char name, uint8_t *bytes, size_t length)
	Helper to add/append a `raw` object to the specified object or array.

void	imquic_qlog_event_add_path_endpoint_info (json_t parent, const char name, const char *ip, uint16_t port)
	Helper to add/append a PathEndpointInfo object to the specified object or array.

void	imquic_qlog_append_event (imquic_qlog qlog, json_t event)
	Helper to add a complete event object to an existing QLOG instance.

void	imquic_qlog_connection_started (imquic_qlog qlog, const char local_ip, uint16_t local_port, const char *remote_ip, uint16_t remote_port)
	Add a `connection_started` event.

void	imquic_qlog_connection_closed (imquic_qlog qlog, gboolean local, uint32_t cc_code, uint32_t app_code, const char reason)
	Add a `connection_closed` event.

void	imquic_qlog_version_information (imquic_qlog *qlog, uint32_t version, uint32_t chosen)
	Add a `version_information` event.

void	imquic_qlog_alpn_information (imquic_qlog qlog, uint8_t server_alpn, size_t server_alpn_len, uint8_t client_alpn, size_t client_alpn_len, char chosen)
	Add a `alpn_information` event.

json_t *	imquic_qlog_prepare_parameters_set (imquic_qlog *qlog, gboolean local, gboolean resumption, gboolean early_data)
	Prepare a `parameters_set` object, but don't add it yet.

void	imquic_qlog_parameters_set (imquic_qlog qlog, json_t params)
	Add a `parameters_set` event.

json_t *	imquic_qlog_prepare_packet_header (const char type, void scid, void *dcid)
	Prepare a `header` object, but don't add it yet.

json_t *	imquic_qlog_prepare_packet_frame (const char *type)
	Prepare a `frames` object, but don't add it yet.

void	imquic_qlog_packet_sent (imquic_qlog qlog, json_t header, json_t *frames, uint32_t id, size_t length)
	Add a `packet_sent` event.

void	imquic_qlog_packet_received (imquic_qlog qlog, json_t header, json_t *frames, uint32_t id, size_t length)
	Add a `packet_received` event.

void	imquic_qlog_packet_dropped (imquic_qlog qlog, json_t header, uint32_t id, size_t length, const char *trigger)
	Add a `packet_dropped` event.

void	imquic_qlog_udp_datagrams_sent (imquic_qlog *qlog, uint32_t id, size_t length)
	Add a `udp_datagrams_sent` event.

void	imquic_qlog_udp_datagrams_received (imquic_qlog *qlog, uint32_t id, size_t length)
	Add a `udp_datagrams_received` event.

void	imquic_qlog_udp_datagrams_dropped (imquic_qlog *qlog, uint32_t id, size_t length)
	Add a `udp_datagrams_dropped` event.

void	imquic_qlog_stream_state_updated (imquic_qlog qlog, uint64_t id, const char type, const char side, const char state)
	Add a `stream_state_updated` event.

void	imquic_qlog_key_updated (imquic_qlog qlog, const char type, uint8_t *key, size_t key_len, uint64_t key_phase)
	Add a `key_updated` event.

QLOG management
typedef struct imquic_qlog	imquic_qlog
	QLOG instance.

imquic_qlog *	imquic_qlog_create (char id, gboolean sequential, gboolean is_server, char filename, gboolean quic, gboolean http3, gboolean roq, gboolean moq)
	Helper method to initialize a new QLOG instance.

void	imquic_qlog_set_odcid (imquic_qlog qlog, void odcid)
	Set/update the Original Destination Connection ID.

int	imquic_qlog_save_to_file (imquic_qlog *qlog)
	Save the current status of the QLOG structure to JSON.

void	imquic_qlog_destroy (imquic_qlog *qlog)
	Helper method to destroy an existing QLOG instance.

Detailed Description

QLOG support (headers)

Author: Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Copyright: MIT License

Implementation of QLOG support (JSON serialization) via the Jansson library.

Note: Jansson is an optional dependency, meaning that the functionality exposed by this code may not be available at runtime. When attempting to enable QLOG usage in that case, a warning will be shown on the console.

Macro Definition Documentation

◆ IMQUIC_QLOG_TRIGGER_CONNECTION_UNKNOWN

#define IMQUIC_QLOG_TRIGGER_CONNECTION_UNKNOWN "connection_unknown"

◆ IMQUIC_QLOG_TRIGGER_DECRYPTION_FAILURE

#define IMQUIC_QLOG_TRIGGER_DECRYPTION_FAILURE "decryption_failure"

◆ IMQUIC_QLOG_TRIGGER_DUPLICATE

#define IMQUIC_QLOG_TRIGGER_DUPLICATE "duplicate"

◆ IMQUIC_QLOG_TRIGGER_GENERAL

#define IMQUIC_QLOG_TRIGGER_GENERAL "general"

◆ IMQUIC_QLOG_TRIGGER_INTERNAL_ERROR

#define IMQUIC_QLOG_TRIGGER_INTERNAL_ERROR "internal_error"

Trigger definitions.

◆ IMQUIC_QLOG_TRIGGER_INVALID

#define IMQUIC_QLOG_TRIGGER_INVALID "invalid"

◆ IMQUIC_QLOG_TRIGGER_KEY_UNAVAILABLE

#define IMQUIC_QLOG_TRIGGER_KEY_UNAVAILABLE "key_unavailable"

◆ IMQUIC_QLOG_TRIGGER_REJECTED

#define IMQUIC_QLOG_TRIGGER_REJECTED "rejected"

◆ IMQUIC_QLOG_TRIGGER_UNSUPPORTED

#define IMQUIC_QLOG_TRIGGER_UNSUPPORTED "unsupported"

Typedef Documentation

◆ imquic_qlog

typedef struct imquic_qlog imquic_qlog

QLOG instance.

Function Documentation

◆ imquic_qlog_alpn_information()

void imquic_qlog_alpn_information	(	imquic_qlog *	qlog,
		uint8_t *	server_alpn,
		size_t	server_alpn_len,
		uint8_t *	client_alpn,
		size_t	client_alpn_len,
		char *	chosen )

Add a alpn_information event.

Parameters

qlog	The imquic_qlog instance to add the event to
server_alpn	The buffer containing the list of server ALPNs, if any
server_alpn_len	The size of the server ALPN buffer
client_alpn	The buffer containing the list of client ALPNs, if any
client_alpn_len	The size of the client ALPN buffer
chosen	The chosen ALPN

◆ imquic_qlog_append_event()

void imquic_qlog_append_event	(	imquic_qlog *	qlog,
		json_t *	event )

Helper to add a complete event object to an existing QLOG instance.

Parameters

qlog	The imquic_qlog instance to add the event to
event	The event to add to the QLOG instance

◆ imquic_qlog_connection_closed()

void imquic_qlog_connection_closed	(	imquic_qlog *	qlog,
		gboolean	local,
		uint32_t	cc_code,
		uint32_t	app_code,
		const char *	reason )

Add a connection_closed event.

Parameters

qlog	The imquic_qlog instance to add the event to
local	Whether this is a local or remote event
cc_code	The connection code in the Connection Close message, if any
app_code	The application code in the Connection Close message, if any
reason	The reason text in the Connection Close message, if any

◆ imquic_qlog_connection_started()

void imquic_qlog_connection_started	(	imquic_qlog *	qlog,
		const char *	local_ip,
		uint16_t	local_port,
		const char *	remote_ip,
		uint16_t	remote_port )

Add a connection_started event.

Parameters

qlog	The imquic_qlog instance to add the event to
local_ip	The local address the connection
local_port	The local port the connection
remote_ip	The remote address the connection
remote_port	The remote port the connection

◆ imquic_qlog_create()

imquic_qlog * imquic_qlog_create	(	char *	id,
		gboolean	sequential,
		gboolean	is_server,
		char *	filename,
		gboolean	quic,
		gboolean	http3,
		gboolean	roq,
		gboolean	moq )

Helper method to initialize a new QLOG instance.

Note: This method will try to create the file right away, and will fail and give up immediately if that doesn't succeed for whatever reason. It will not create the folders part of the filename if the related folders don't exist already, which means those should be created by the application using the library, in case

Parameters

id	ID of the log (ends in the title property)
sequential	Whether sequential JSON should be used, instead of regular JSON
is_server	Whether this is for a client or server connection
filename	Path to where the JSON file should be saved
quic	Whether QUIC events should be added to the QLOG
http3	Whether HTTP/3 events should be added to the QLOG
roq	Whether RoQ events should be added to the QLOG
moq	Whether MoQT events should be added to the QLOG

Returns: A pointer to a new imquic_qlog instance, if successful, or NULL otherwise

◆ imquic_qlog_destroy()

void imquic_qlog_destroy ( imquic_qlog * qlog )

Helper method to destroy an existing QLOG instance.

Note: Destroying the instance will write the file to disk

Parameters

qlog	The imquic_qlog instance to destroy

◆ imquic_qlog_event_add_data()

json_t * imquic_qlog_event_add_data ( json_t * event )

Helper to add a data object to an event and return a pointer to it.

Parameters

event The event to add the data object to

Returns: A pointer to the data object, if successful, or NULL otherwise

◆ imquic_qlog_event_add_path_endpoint_info()

void imquic_qlog_event_add_path_endpoint_info	(	json_t *	parent,
		const char *	name,
		const char *	ip,
		uint16_t	port )

Helper to add/append a PathEndpointInfo object to the specified object or array.

Note: The method automatically fills in either the v4 or v6 info by looking at the address

Parameters

parent	The object or array to add/append the info to
name	Name to give to the object, if the parent is an object (ignored for arrays)
ip	The IP address
port	The port

◆ imquic_qlog_event_add_raw()

void imquic_qlog_event_add_raw	(	json_t *	parent,
		const char *	name,
		uint8_t *	bytes,
		size_t	length )

Helper to add/append a raw object to the specified object or array.

Parameters

parent	The object or array to add/append the raw info to
name	Name to give to the raw object, if the parent is an object (ignored for arrays)
bytes	The content of the raw data, if needed
length	The size of the raw data

◆ imquic_qlog_event_prepare()

json_t * imquic_qlog_event_prepare ( const char * name )

Helper to create a new QLOG event by name.

Note: This automatically fills in the time property

Parameters

name	The name of the event

Returns: An event instance to fill in before appending it, if successful, or NULL otherwise

◆ imquic_qlog_is_supported()

gboolean imquic_qlog_is_supported ( void )

Helper method to check if QLOG is supported at runtime.

Returns: TRUE if supported, FALSE otherwise

◆ imquic_qlog_key_updated()

void imquic_qlog_key_updated	(	imquic_qlog *	qlog,
		const char *	type,
		uint8_t *	key,
		size_t	key_len,
		uint64_t	key_phase )

Add a key_updated event.

Parameters

qlog	The imquic_qlog instance to add the event to
type	The key type
key	Pointer to the key value
key_len	Size of the key value
key_phase	The key phase

◆ imquic_qlog_packet_dropped()

void imquic_qlog_packet_dropped	(	imquic_qlog *	qlog,
		json_t *	header,
		uint32_t	id,
		size_t	length,
		const char *	trigger )

Add a packet_dropped event.

Parameters

qlog	The imquic_qlog instance to add the event to
header	The QUIC packet header info, if any
id	The ID of the datagram, if any
length	The size of the datagram that was received
trigger	What caused the packet to be dropped

◆ imquic_qlog_packet_received()

void imquic_qlog_packet_received	(	imquic_qlog *	qlog,
		json_t *	header,
		json_t *	frames,
		uint32_t	id,
		size_t	length )

Add a packet_received event.

Parameters

qlog	The imquic_qlog instance to add the event to
header	The QUIC packet header info
frames	The QUIC packet frames, if any
id	The ID of the datagram, if any
length	The size of the datagram that was received

◆ imquic_qlog_packet_sent()

void imquic_qlog_packet_sent	(	imquic_qlog *	qlog,
		json_t *	header,
		json_t *	frames,
		uint32_t	id,
		size_t	length )

Add a packet_sent event.

Parameters

qlog	The imquic_qlog instance to add the event to
header	The QUIC packet header info, if any
frames	The QUIC packet frames, if any
id	The ID of the datagram, if any
length	The size of the datagram that was sent

◆ imquic_qlog_parameters_set()

void imquic_qlog_parameters_set	(	imquic_qlog *	qlog,
		json_t *	params )

Add a parameters_set event.

Parameters

qlog	The imquic_qlog instance to add the event to
params	Pointer to a previously filled parameters set data object

◆ imquic_qlog_prepare_packet_frame()

json_t * imquic_qlog_prepare_packet_frame ( const char * type )

Prepare a frames object, but don't add it yet.

Note: This is needed to prepare an object that can be filled in externally, and then be passed to events that involve packets

Parameters

type	The frame type

Returns: A pointer to the new object, if successful, or NULL otherwise

◆ imquic_qlog_prepare_packet_header()

json_t * imquic_qlog_prepare_packet_header	(	const char *	type,
		void *	scid,
		void *	dcid )

Prepare a header object, but don't add it yet.

Note: This is needed to prepare an object that calls that can be filled in externally, and then be passed to events that involve packets

Parameters

type	The packet type
scid	Opaque pointer to the source imquic_connection_id, if any
dcid	Opaque pointer to the destination imquic_connection_id, if any

Returns: A pointer to the header object, if successful, or NULL otherwise

◆ imquic_qlog_prepare_parameters_set()

json_t * imquic_qlog_prepare_parameters_set	(	imquic_qlog *	qlog,
		gboolean	local,
		gboolean	resumption,
		gboolean	early_data )

Prepare a parameters_set object, but don't add it yet.

Note: This is needed to prepare an object that calls that can be filled in externally, and then be passed to imquic_qlog_parameters_set

Parameters

qlog	The imquic_qlog instance to prepare the data for
local	Whether this is a local or remote parameters set
resumption	Whether the `resumption_allowed` property should be set to TRUE
early_data	Whether the `early_data_enabled` property should be set to TRUE

Returns: A pointer to the parameters set object, if successful, or NULL otherwise

◆ imquic_qlog_save_to_file()

int imquic_qlog_save_to_file ( imquic_qlog * qlog )

Save the current status of the QLOG structure to JSON.

Note: This does not close the file, as other events may arrive later. This function is called automatically before destroying the instance

Parameters

qlog	The imquic_qlog instance to save to file

Returns: 0 if successful, a negative integer otherwise

◆ imquic_qlog_set_odcid()

void imquic_qlog_set_odcid	(	imquic_qlog *	qlog,
		void *	odcid )

Set/update the Original Destination Connection ID.

Parameters

qlog	The imquic_qlog instance to update
odcid	The Original Destination Connection ID to write, as a imquic_connection_id instance

◆ imquic_qlog_stream_state_updated()

void imquic_qlog_stream_state_updated	(	imquic_qlog *	qlog,
		uint64_t	id,
		const char *	type,
		const char *	side,
		const char *	state )

Add a stream_state_updated event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the stream
type	The stream type (bidirectional/unidirectional), if any
side	The stream side (sending/receiving), if any
state	The new stream state, if any

◆ imquic_qlog_udp_datagrams_dropped()

void imquic_qlog_udp_datagrams_dropped	(	imquic_qlog *	qlog,
		uint32_t	id,
		size_t	length )

Add a udp_datagrams_dropped event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the datagram, if any
length	The size of the datagram that was dropped

◆ imquic_qlog_udp_datagrams_received()

void imquic_qlog_udp_datagrams_received	(	imquic_qlog *	qlog,
		uint32_t	id,
		size_t	length )

Add a udp_datagrams_received event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the datagram, if any
length	The size of the datagram that was sent

◆ imquic_qlog_udp_datagrams_sent()

void imquic_qlog_udp_datagrams_sent	(	imquic_qlog *	qlog,
		uint32_t	id,
		size_t	length )

Add a udp_datagrams_sent event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the datagram, if any
length	The size of the datagram that was sent

◆ imquic_qlog_version_information()

void imquic_qlog_version_information	(	imquic_qlog *	qlog,
		uint32_t	version,
		uint32_t	chosen )

Add a version_information event.

Parameters

qlog	The imquic_qlog instance to add the event to
version	The version we support (just one, right now)
chosen	The chosen version

Data Structures

Macros

Functions

QLOG management

Detailed Description

Macro Definition Documentation

◆ IMQUIC_QLOG_TRIGGER_CONNECTION_UNKNOWN

◆ IMQUIC_QLOG_TRIGGER_DECRYPTION_FAILURE

◆ IMQUIC_QLOG_TRIGGER_DUPLICATE

◆ IMQUIC_QLOG_TRIGGER_GENERAL

◆ IMQUIC_QLOG_TRIGGER_INTERNAL_ERROR

◆ IMQUIC_QLOG_TRIGGER_INVALID

◆ IMQUIC_QLOG_TRIGGER_KEY_UNAVAILABLE

◆ IMQUIC_QLOG_TRIGGER_REJECTED

◆ IMQUIC_QLOG_TRIGGER_UNSUPPORTED

Typedef Documentation

◆ imquic_qlog

Function Documentation

◆ imquic_qlog_alpn_information()

◆ imquic_qlog_append_event()

◆ imquic_qlog_connection_closed()

◆ imquic_qlog_connection_started()

◆ imquic_qlog_create()

◆ imquic_qlog_destroy()

◆ imquic_qlog_event_add_data()

◆ imquic_qlog_event_add_path_endpoint_info()

◆ imquic_qlog_event_add_raw()

◆ imquic_qlog_event_prepare()

◆ imquic_qlog_is_supported()

◆ imquic_qlog_key_updated()

◆ imquic_qlog_packet_dropped()

◆ imquic_qlog_packet_received()

◆ imquic_qlog_packet_sent()

◆ imquic_qlog_parameters_set()

◆ imquic_qlog_prepare_packet_frame()

◆ imquic_qlog_prepare_packet_header()

◆ imquic_qlog_prepare_parameters_set()

◆ imquic_qlog_save_to_file()

◆ imquic_qlog_set_odcid()

◆ imquic_qlog_stream_state_updated()

◆ imquic_qlog_udp_datagrams_dropped()

◆ imquic_qlog_udp_datagrams_received()

◆ imquic_qlog_udp_datagrams_sent()

◆ imquic_qlog_version_information()