Logging

This is Dragons logging interface for the infrastructure API.

C Interface

Functions

dragonError_t dragon_logging_attr_init(dragonLoggingAttr_t *lattrs)
dragonError_t dragon_logging_init(dragonMemoryPoolDescr_t *mpool, const dragonC_UID_t l_uid, dragonLoggingAttr_t *lattrs, dragonLoggingDescr_t *logger)

Initialize the Logging channel to send/collect messages from varying processes/libraries.

Parameters:

  • mpool – Pointer to the memory pool the channel should use

  • l_uid – Unique identifier for the channel to be assigned

  • lattrs – (Optional) Custom attributes for the Logger NOT IMPLEMENTED

  • logger – Handle to the logger to be initialized

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_destroy(dragonLoggingDescr_t *logger, bool destroy_pool)

Destroy logging channel and memory pool.

Parameters:

logger – Handle to the logger to be destroyed

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_serialize(const dragonLoggingDescr_t *logger, dragonLoggingSerial_t *log_ser)

Serialize logging channel information for other processes to attach to.

Parameters:

  • logger – Handle to the logger to be serialized

  • log_ser – Serialized data output

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_serial_free(dragonLoggingSerial_t *log_ser)

Release local allocations for serialized data.

Parameters:

log_ser – Serialized data to free

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_attach(const dragonLoggingSerial_t *log_ser, dragonLoggingDescr_t *logger, dragonMemoryPoolDescr_t *mpool)

Attach to serialized logging channel.

Parameters:

  • log_ser – Serialized logging channel data to attach

  • logger – Handle to the logger

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_detach(dragonLoggingDescr_t *logger)
dragonError_t dragon_logging_put(const dragonLoggingDescr_t *logger, dragonLogPriority_t priority, char *log)

Insert a message with a given priority and a string to the logging channel.

Allocates necessary managed memory to insert the message and its priority level. If the logging channel is at capacity, will retrieve the next available message, discard it, and try again. If the second send attempt fails, returns with an error. Currently does not block.

Parameters:

  • logger – Handle to the logger

  • priority – Priority level of the message

  • log – Message log as a string

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_get(const dragonLoggingDescr_t *logger, dragonLogPriority_t priority, void **msg_out, timespec_t *timeout)

Retrieve the next available message if it is at least priority level.

Retrieve the next message if it is at least priority. Otherwise return DRAGON_LOGGING_LOW_PRIORITY_MSG If successful, will allocate memory in msg_out to copy data into. User is responsbile for freeing this. timeout can be specified to use blocking behavior, otherwise pass NULL for non-blocking

Parameters:

  • logger – Handle to the logger

  • priority – Minimum priority that the next message needs to meet to be returned

  • msg_out – Pointer to allocate and copy message data into

  • timeout – (Optional) How long to wait for the next message

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_get_priority(const dragonLoggingDescr_t *logger, dragonLogPriority_t priority, void **msg_out, timespec_t *timeout)

Retrieve the next available message of at least priority level.

Retrieve the next message of at least priority. Will continue to retrieve messages until priority is satisfied or no further logs are available. If successful, will allocate memory in msg_out to copy data into. User is responsbile for freeing this. timeout can be specified to use blocking behavior, otherwise pass NULL for non-blocking

Parameters:

  • logger – Handle to the logger

  • priority – Minimum priority that the next message needs to meet to be returned

  • msg_out – Pointer to allocate and copy message data into

  • timeout – (Optional) How long to wait for the next message

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_print(const dragonLoggingDescr_t *logger, dragonLogPriority_t priority, timespec_t *timeout)

Retrieve the next available message of at least priority level and print it.

Retrieve the next message of at least priority. Will continue to retrieve messages until priority is satisfied or no further logs are available. Upon success, print message to stdout. timeout can be specified to use blocking behavior, otherwise pass NULL for non-blocking

Parameters:

  • logger – Handle to the logger

  • priority – Minimum priority that the next message needs to meet to be returned

  • msg_out – Pointer to allocate and copy message data into

  • timeout – (Optional) How long to wait for the next message

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_get_str(const dragonLoggingDescr_t *logger, dragonLogPriority_t priority, char **out_str, timespec_t *timeout)

Retrieve the next available message of at least priority level and return string.

Retrieve the next message of at least priority. Will continue to retrieve messages until priority is satisfied or no further logs are available. Upon success, return string through out_str. User is responsbile for freeing out_str when done. timeout can be specified to use blocking behavior, otherwise pass NULL for non-blocking

Parameters:

  • logger – Handle to the logger

  • priority – Minimum priority that the next message needs to meet to be returned

  • msg_out – Pointer to allocate and copy message data into

  • timeout – (Optional) How long to wait for the next message

Returns:

DRAGON_SUCCESS or a Dragon Error code on failure

dragonError_t dragon_logging_count(const dragonLoggingDescr_t *logger, uint64_t *count)

Variables

static const char *dg_log_levels[] = {"[NOTSET]", "[DEBUG]", "[INFO]", "[WARN]", "[ERROR]", "[CRITICAL]"}

Cython Interface

class DragonLogger

Bases: object

Python interface to C-level Dragon logging infrastructure

__init__()

Create a DragonLogger instance for send/recv of infrastructure logs

Args:

mpool (MemoryPool): memory pool dedicated to logging infrastructure messages

lattrs (NULL, optional): Logging attributes. Not implemented

uid (default: 0): Unique ID to use for the logger.

If default is provided a semi-random value will be used starting at BASE_LOG_CUID (see facts.py)

mode (dragonLoggingMode, default: FIRST): What mode to run the logger in.

DRAGON_LOGGING_LOSSLESS - Block and wait on a full channel until a message can be inserted DRAGON_LOGGING_FIRST - Drop message on a full channel DRAGON_LOGGING_LAST - Remove oldest message to insert newest on a full channel !!! NOT IMPLEMENTED !!!

Raises:

RuntimeError: Input memory pool was None

DragonLoggingError: Logging was not successfully initialized

classmethod attach(serialized_bytes: bytes, mpool=None) → DragonLogger

Attach to a logging channel given a serialized descriptor

Parameters:

  • serialized_bytes (bytes) – serialized logging channel descriptor

  • mpool (MemoryPool, optional) – memory pool to construct messages from. If None, tries to use the pool associated with the channel, defaults to None

Returns:

DragonLogger instance attached to given channel backed by option mpool

Return type:

DragonLogger

destroy(destroy_pool: bool = True)

Destroy the DragonLogger object and its underlying memory pool

Should only be called when it is known that no other processes or services will be writing to it

Parameters:

destroy_pool (bool, optional) – whether to destroy memory pool support the logging channel, defaults to True

Raises:

DragonLoggingError – unable to destroy the logging object as requested

get(priority=20, timeout=None)

Get a message out of logging channel queue of level priority

Args:

priority (int): level the return message should at minimum be (eg: logging.INFO) timeout (int, float): maximum time in seconds to wait for a message

num_logs()

Get number of logs in queue

Returns:

int: number of logs currently in channel queue

put(msg: str, priority: int = 20)

Put a logging message into the logging channel queue

Args:

msg (str)

priority (int): logging level with values matching those in Python’s logging module (eg: logging.INFO)

serialize()

Return a serialized descriptor of the logging channel

For an already created logger, return its serialized descriptor so other services can attach to it

Returns:

bytes: serialized descriptor

exception DragonLoggingError

Bases: Exception

class Errors

Bases: Enum

An enumeration.

SUCCESS = 0
FAIL = 1
__init__(lib_err, msg)