dxFeed Graal Native SDK 3.12.0
Loading...
Searching...
No Matches
Logging

Interception of the messages that the QD library and the SDK log, and the logging levels. More...

Data Structures

struct  dxfg_logging_listener_t
 A handle of a Java InterceptableLoggingListener object, a wrapper of a listener that allows to intercept the logged messages; release it with dxfg_JavaObjectHandler_release(). More...

Typedefs

typedef enum dxfg_logging_level_t dxfg_logging_level_t
 The logging levels that can be used to control the logging output.
typedef struct dxfg_logging_listener_t dxfg_logging_listener_t
 A handle of a Java InterceptableLoggingListener object, a wrapper of a listener that allows to intercept the logged messages; release it with dxfg_JavaObjectHandler_release().
typedef void(*) dxfg_logging_listener_function_t(graal_isolatethread_t *thread, dxfg_logging_level_t level, int64_t timestamp, const char *thread_name, int64_t thread_id, const char *logger_name, const char *message, dxfg_exception_t *exception, const char *formatted_message, void *user_data)
 The function of a dxfg_logging_listener_t: called for every message that is logged while the listener is installed and the level of the message is not below the logging level (see dxfg_logging_set_log_level()).

Enumerations

enum  dxfg_logging_level_t {
  DXFG_LOGGING_LEVEL_ALL = 0 , DXFG_LOGGING_LEVEL_TRACE , DXFG_LOGGING_LEVEL_DEBUG , DXFG_LOGGING_LEVEL_INFO ,
  DXFG_LOGGING_LEVEL_WARN , DXFG_LOGGING_LEVEL_ERROR , DXFG_LOGGING_LEVEL_OFF
}
 The logging levels that can be used to control the logging output. More...

Functions

int32_t dxfg_logging_listener_new (graal_isolatethread_t *thread, dxfg_logging_listener_function_t user_func, void *user_data, DXFG_OUT dxfg_logging_listener_t **listener)
 Creates a new logging listener.
int32_t dxfg_logging_set_listener (graal_isolatethread_t *thread, dxfg_logging_listener_t *listener)
 Installs the logging listener.
int32_t dxfg_logging_set_log_level (graal_isolatethread_t *thread, dxfg_logging_level_t level)
 Sets the logging level for the listener or the console or the log file.
int32_t dxfg_logging_set_err_level (graal_isolatethread_t *thread, dxfg_logging_level_t level)
 Sets the logging level for the err file.

Detailed Description

Interception of the messages that the QD library and the SDK log, and the logging levels.

The messages are logged by the Java com.devexperts.logging system of the isolate. Instead of the console and the log files the messages can be given to a C function: create a listener with dxfg_logging_listener_new() and install it with dxfg_logging_set_listener(). The logging implementation is chosen when the first message is logged, so the property log.className (see dxfg_system_set_property()) must be set before that, as in the sample of dxfg_logging_listener_new().

The classes InterceptableLogging and InterceptableLoggingListener that the functions of this group call belong to the SDK (package com.devexperts.logging), not to the QD library.

The ownership rules of the handles are described in the group Javac.

Typedef Documentation

◆ dxfg_logging_level_t

The logging levels that can be used to control the logging output.

The values correspond to the levels of java.util.logging.Level that the logging system uses.

Java: java.util.logging.Level.

◆ dxfg_logging_listener_function_t

typedef void(*) dxfg_logging_listener_function_t(graal_isolatethread_t *thread, dxfg_logging_level_t level, int64_t timestamp, const char *thread_name, int64_t thread_id, const char *logger_name, const char *message, dxfg_exception_t *exception, const char *formatted_message, void *user_data)

The function of a dxfg_logging_listener_t: called for every message that is logged while the listener is installed and the level of the message is not below the logging level (see dxfg_logging_set_log_level()).

The function is called synchronously by the Java thread that logs the message, which may be any thread of the isolate (including the threads of the endpoints), not the thread that installed the listener. The calls are serialized by a lock of the logging system: the function is never called concurrently, and while it runs the other threads that log wait. So it should return quickly and should not block.

The strings and the exception are allocated by the SDK for the call and released by the SDK after the function returns: copy what is needed, do not keep the pointers and do not release them. A string or the exception is NULL when the corresponding value is absent.

Java: InterceptableLoggingListener.onLog(Level, long, String, long, String, String, Throwable, String).

Parameters
[in]threadThe current GraalVM Isolate's thread.
[in]levelThe level of the message.
[in]timestampThe time of the message in milliseconds since the Unix epoch (UTC).
[in]thread_nameThe name of the Java thread that logged the message, a NUL-terminated UTF-8 string.
[in]thread_idThe identifier of the Java thread that logged the message.
[in]logger_nameThe name of the logger, a NUL-terminated UTF-8 string (NULL if the logger has no name).
[in]messageThe text of the message without the time, the level and other parts of the layout, a NUL-terminated UTF-8 string.
[in]exceptionThe exception that is logged with the message, or NULL if there is none. See dxfg_exception_t.
[in]formatted_messageThe whole line that the logging system would write: the message with the time, the level, the thread and the exception formatted with the layout of the logging system, a NUL-terminated UTF-8 string.
[in]user_dataThe pointer that was passed to dxfg_logging_listener_new(); the SDK does not use it.

◆ dxfg_logging_listener_t

typedef struct dxfg_logging_listener_t dxfg_logging_listener_t

A handle of a Java InterceptableLoggingListener object, a wrapper of a listener that allows to intercept the logged messages; release it with dxfg_JavaObjectHandler_release().

Create it with dxfg_logging_listener_new() and install it with dxfg_logging_set_listener(). The last handle of the listener that is released deactivates the listener: its function is not called anymore.

Enumeration Type Documentation

◆ dxfg_logging_level_t

The logging levels that can be used to control the logging output.

The values correspond to the levels of java.util.logging.Level that the logging system uses.

Java: java.util.logging.Level.

Enumerator
DXFG_LOGGING_LEVEL_ALL 

Indicates that all messages should be logged (Level.ALL).

DXFG_LOGGING_LEVEL_TRACE 

Indicates a highly detailed tracing message (Level.FINEST).

DXFG_LOGGING_LEVEL_DEBUG 

A message level providing tracing debug information (Level.FINE).

DXFG_LOGGING_LEVEL_INFO 

A message level for informational messages (Level.INFO).

DXFG_LOGGING_LEVEL_WARN 

A message level indicating a potential problem (Level.WARNING).

DXFG_LOGGING_LEVEL_ERROR 

A message level indicating a serious failure (Level.SEVERE).

DXFG_LOGGING_LEVEL_OFF 

A special level that can be used to turn off logging (Level.OFF).

Function Documentation

◆ dxfg_logging_listener_new()

int32_t dxfg_logging_listener_new ( graal_isolatethread_t * thread,
dxfg_logging_listener_function_t user_func,
void * user_data,
DXFG_OUT dxfg_logging_listener_t ** listener )

Creates a new logging listener.

The listener does nothing until it is installed with dxfg_logging_set_listener(). The function is called as described at dxfg_logging_listener_function_t.

Releasing the last handle of the listener with dxfg_JavaObjectHandler_release() (or dxfg_NativeListener_deactivate()) stops the calls of the function: after the release returns the function is not running and is not called anymore, so the user data can be freed. An installed listener cannot be replaced or removed (see dxfg_logging_set_listener()), it can only be deactivated this way.

Sample:

void callback(graal_isolatethread_t *thread, dxfg_logging_level_t level, int64_t timestamp, const char *thread_name,
int64_t thread_id, const char *logger_name, const char *message, dxfg_exception_t *exception,
const char *formatted_message, void *user_data) {
printf("[%" PRId64 "]: %s", thread_id, formatted_message);
}
// ...
// Set the logging Java class
dxfg_system_set_property(isolate_thread, "log.className", "com.devexperts.logging.InterceptableLogging");
// Turn off logging.
dxfg_system_set_property(isolate_thread, "log.level", "OFF");
dxfg_logging_listener_t *listener = {};
dxfg_logging_listener_new(isolate_thread, &callback, NULL, &listener);
dxfg_logging_set_listener(isolate_thread, listener);
// Turn on logging
dxfg_DXEndpoint_close(isolate_thread, ep);
dxfg_JavaObjectHandler_release(isolate_thread, &listener->handler);
struct __graal_isolatethread_t graal_isolatethread_t
The state of one thread attached to an isolate: the first parameter (thread) of the SDK functions.
Definition graal_isolate.h:60
int32_t dxfg_DXEndpoint_close(graal_isolatethread_t *thread, dxfg_endpoint_t *endpoint)
Closes the endpoint: disconnects it and releases its resources. The endpoint cannot be used after tha...
dxfg_endpoint_t * dxfg_DXEndpoint_getInstance(graal_isolatethread_t *thread)
Returns the default application-wide singleton endpoint with the DXFG_ENDPOINT_ROLE_FEED role,...
int32_t dxfg_JavaObjectHandler_release(graal_isolatethread_t *thread, dxfg_java_object_handler *handler)
int32_t dxfg_logging_set_log_level(graal_isolatethread_t *thread, dxfg_logging_level_t level)
Sets the logging level for the listener or the console or the log file.
int32_t dxfg_logging_listener_new(graal_isolatethread_t *thread, dxfg_logging_listener_function_t user_func, void *user_data, DXFG_OUT dxfg_logging_listener_t **listener)
Creates a new logging listener.
int32_t dxfg_logging_set_listener(graal_isolatethread_t *thread, dxfg_logging_listener_t *listener)
Installs the logging listener.
dxfg_logging_level_t
The logging levels that can be used to control the logging output.
Definition dxfg_logging.h:48
@ DXFG_LOGGING_LEVEL_INFO
Definition dxfg_logging.h:59
int32_t dxfg_system_set_property(graal_isolatethread_t *thread, const char *key, const char *value)
Sets the Java system property indicated by the specified key.
A handle of a Java DXEndpoint object; release it with dxfg_JavaObjectHandler_release().
Definition dxfg_endpoint.h:68
dxfg_java_object_handler handler
Definition dxfg_endpoint.h:70
An exception that was thrown by the Java side: the class, the message, the stack trace and the cause.
Definition dxfg_catch_exception.h:83
A handle of a Java InterceptableLoggingListener object, a wrapper of a listener that allows to interc...
Definition dxfg_logging.h:78
dxfg_java_object_handler handler
Definition dxfg_logging.h:80

Java: InterceptableLoggingListener.onLog(Level, long, String, long, String, String, Throwable, String).

Deprecated
Use dxfg_v4_logging_listener_new().
Parameters
[in]threadThe current GraalVM Isolate's thread.
[in]user_funcThe listener callback.
[in]user_dataThe user data that will be passed to the callback; the SDK does not use it. It must stay valid until the listener is deactivated.
[out]listenerThe pointer to the variable that receives the new listener (release its handle with dxfg_JavaObjectHandler_release()). It is written only on success. A NULL pointer is an error.
Returns
DXFG_EXECUTE_SUCCESSFULLY (0) on successful function execution or DXFG_EXECUTE_FAIL (-1) on error. Use dxfg_get_and_clear_thread_exception_t() to determine if an exception was thrown.

◆ dxfg_logging_set_err_level()

int32_t dxfg_logging_set_err_level ( graal_isolatethread_t * thread,
dxfg_logging_level_t level )

Sets the logging level for the err file.

The level is set for the second handler of the logging system: the file of the errors (err.file). If there is no such handler (e.g. a listener is installed or err.file is not set), the function does nothing and returns DXFG_EXECUTE_SUCCESSFULLY. The default level of the err file is taken from the system property err.level (warnings and errors by default).

Java: InterceptableLogging.setErrLevel(Level).

Deprecated
Use dxfg_v4_logging_set_err_level().
Parameters
[in]threadThe current GraalVM Isolate's thread.
[in]levelThe new logging level.
Returns
DXFG_EXECUTE_SUCCESSFULLY (0) on successful function execution or DXFG_EXECUTE_FAIL (-1) on error. Use dxfg_get_and_clear_thread_exception_t() to determine if an exception was thrown.

◆ dxfg_logging_set_listener()

int32_t dxfg_logging_set_listener ( graal_isolatethread_t * thread,
dxfg_logging_listener_t * listener )

Installs the logging listener.

It toggles the logging: the existing handlers of the logging system are removed, so the messages are not logged to the console and to files anymore, and the messages are given to the listener. The level of the messages that reach the listener is taken from the system property log.level (all messages by default) and can be changed with dxfg_logging_set_log_level().

Only the first installed listener works: if a listener is already installed, the function does nothing. A NULL listener does nothing as well. In both cases the function returns DXFG_EXECUTE_SUCCESSFULLY. The installed listener cannot be removed; release its handle (see dxfg_logging_listener_new()) to stop its calls.

Java: InterceptableLogging.setListener(InterceptableLoggingListener).

Deprecated
Use dxfg_v4_logging_set_listener().
Parameters
[in]threadThe current GraalVM Isolate's thread.
[in]listenerThe logging listener. The caller keeps its handle.
Returns
DXFG_EXECUTE_SUCCESSFULLY (0) on successful function execution or DXFG_EXECUTE_FAIL (-1) on error. Use dxfg_get_and_clear_thread_exception_t() to determine if an exception was thrown.

◆ dxfg_logging_set_log_level()

int32_t dxfg_logging_set_log_level ( graal_isolatethread_t * thread,
dxfg_logging_level_t level )

Sets the logging level for the listener or the console or the log file.

The level is set for the first handler of the logging system: the handler of the listener if one is installed (see dxfg_logging_set_listener()), otherwise the console or the log file (log.file). If there is no such handler, the function does nothing and returns DXFG_EXECUTE_SUCCESSFULLY.

Java: InterceptableLogging.setLogLevel(Level).

Deprecated
Use dxfg_v4_logging_set_log_level().
Parameters
[in]threadThe current GraalVM Isolate's thread.
[in]levelThe new logging level.
Returns
DXFG_EXECUTE_SUCCESSFULLY (0) on successful function execution or DXFG_EXECUTE_FAIL (-1) on error. Use dxfg_get_and_clear_thread_exception_t() to determine if an exception was thrown.