Chapter 4 Logging Functions

This chapter provides a reference to public functions in the C SDK for logging on the local system or on Sun Java^TM System Access Manager. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_log.h:

• am_log_add_module()

• am_log_flush_remote_log()

• am_log_init()

• am_log_is_level_enabled()

• am_log_log()

• am_log_log_record()

• am_log_record_add_loginfo()

• am_log_record_create()

• am_log_record_destroy()

• am_log_record_populate()

• am_log_record_set_log_level()

• am_log_record_set_log_message()

• am_log_record_set_loginfo_props()

• am_log_set_levels_from_string()

• am_log_set_log_file()

• am_log_set_module_level()

• am_log_set_remote_info()

• am_log_vlog()

am_log_add_module()

Adds a new module to the list of known logging modules.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_add_module(const char *name, am_log_module_id_t *id_ptr);

Parameters

This function takes the following parameters:

name

The name to associate with the new module.

id_ptr

Where to store the id of the logging module.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error is detected.

AM_INVALID_ARGUMENT

If name or id_ptr is NULL.

AM_NSPR_ERROR

If unable to initialize to the logging package.

AM_NO_MEMORY

If unable to allocate memory for the new logging module.

AM_FAILURE

If any other error is detected.

Details

If a module of the same name already exists, then the module ID of that module is returned.

am_log_flush_remote_log()

Flushes all the log records in the log buffer.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_flush_remote_log();

Parameters

This function takes no parameters:

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If Flush to remote log was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_init()

Initializes logging.

This must be called before using any am_log_* interfaces.

If any SSO, authentication, or policy initialization functions, am_sso_init() , am_auth_init(), or am_policy_init(), is called, then am_log_init() does not need to be called separately. Any of those functions will call am_log_init() internally with the same properties parameter that was used to initialize SSO, authentication, or policy.

See the agents documentation on parameters related to logging that can be used to initialize log.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_init(const am_properties_t log_init_params);

Parameters

This function takes the following parameters:

log_init_params

Properties to initialize the log module with.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If log initialization is successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_is_level_enabled()

Determines whether a logging message at the specified level and associated with the specified module would be emitted.

Syntax

#include "am_log.h"
AM_EXPORT boolean_t
am_log_is_level_enabled(am_log_module_id_t moduleID,
                        am_log_level_t level);

Parameters

This function takes the following parameters:

module

The ID of the module to be examined.

level

The logging level to be checked.

Returns

This function returns boolean_t with one of the following values:

!0

If the message would be emitted.

0

Otherwise

am_log_log()

Log the given message for the given module and at the given level.

Syntax

#include "am_log.h"
AM_EXPORT boolean_t
am_log_log(am_log_module_id_t moduleID,
            am_log_level_t level,
            const char *format, ...);

Parameters

This function takes the following parameters:

module

The ID of the module to be associated with the message.

level

The logging level of the message.

format

A printf-style format string.

Returns

This function returns boolean_t with one of the following values.

The set of addition arguments needed by the format string either enumerated directly or passed using the standard va_list mechanism as appropriate to the call.

Details

The message is emitted only if the current level of the specified module is greater than or equal to the specified level.

am_log_log_record()

Logs the given log record to the given log_name on the Access Manager.

am_log_record_* interfaces can be used to set information in the log record.

Syntax

#include "am_log.h"
 AM_EXPORT am_status_t am_log_log_record
    (am_log_record_t record, const char *log_name, const char *logged_by_token_id);
        Start here

Parameters

This function takes the following parameters:

record

The log record.

log_name

The name of the log module to log the log record to

logged_by_token_id

A valid SSO token ID required to access the logging service on Access Manager.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the log operation was successful

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_add_loginfo()

Updates the log record with additional information.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_add_loginfo(am_log_record_t record,
                            const char *key,
                            const char *value);

Parameters

This function takes the following parameters:

record

Opaque handle to the log record.

log_name

The name of the log module to log the log record to.

logged_by_token_id

A valid SSO token ID required to access the logging service on Access Manager.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the key and value was successfully added to the given log record.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_create()

Creates a log record and initializes it with the given log level and message.

Syntax

#include "am_log.h"
 AM_EXPORT am_status_t am_log_record_create
                   (am_log_record_t *record_ptr, am_log_record_log_level_t log_level,
                    const char *message);

Parameters

This function takes the following parameters:

record

Opaque handle to the log record.

log_name

The name of the log module to log the log record to

logged_by_token_id

A valid SSO token ID required to access the logging service on Access Manager.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the key and value was successfully added to the given log record.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_destroy()

Destroys the log record returned by am_log_record_create.

Syntax

#include "am_log.h" 
AM_EXPORT am_status_t am_log_record_destroy(am_log_record_t record);

Parameters

This function takes the following parameter:

record

Opaque handle to the log record to destroy.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the log record was successfully destroyed.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_populate()

Updates the log record with user’s SSO token information.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_populate(am_log_record_t record,
                        const char *user_token_id);

Parameters

This function takes the following parameters:

record

Opaque handle to the log record.

user_token_id

A valid SSO Token ID.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the operation was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_set_log_level()

Convenience functions.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_log_level(am_log_record_t record,
                            am_log_record_log_level_t log_level);

Parameters

This function takes the following parameters:

record

Opaque handle to the log record.

log level

Log level to set in the log record.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the log level was successfully set.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_set_log_message()

Convenience function.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_log_message(am_log_record_t record,
                                const char *message);

Parameters

This function takes the following parameters:

record

Opaque handle to the log record.

message

The message to set in the log record.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the message was successfully added to the log record.

AM_*

If any error occurs, the type of error indicated by the status value.

am_log_record_set_loginfo_props()

Updates the log record with additional information.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_loginfo_props(am_log_record_t record,
                                am_properties_t log_info);

Parameters

This function takes the following parameters:

record

Opaque handle to the log record.

log_info

Key value pairs to be set in the log record.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If log_info was successfully added.

AM_*

If any error occurs, the type of error indicated by the status value.

Details

Sets all log info values as properties map.

The log_info is expected to have the required log info members as key value pairs and user is expected to delete the am_properties_t pointer only when he is done with amsdk.

am_log_set_levels_from_string()

Sets the logging level for the modules listed in specified string.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_levels_from_string(const char *module_level_string);

Parameters

This function takes the following parameter:

module_level_string

List of modules to set.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error is detected

AM_INVALID_ARGUMENT

If name or id_ptr is NULL

AM_NSPR_ERROR

If unable to initialize to the logging package

AM_NO_MEMORY

If unable to allocate memory for the new logging module

AM_FAILURE

If unable to allocate memory for the new logging module

Details

The format of the string is:

<ModuleName>[:<Level>][,<ModuleName>[:<Level>]]*

Optional spaces may occur before and after any commas.

am_log_set_log_file()

Sets the name of the file to use for logging.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_log_file(const char *name);

Parameters

This function takes the following parameter:

name

Name of the file in which to record logging messages.

Returns

This function returns am_status_twith one of the following values:

AM_SUCCESS

If the logging file could be set

AM_NO_MEMORY

If unable to allocate memory for internal data structures

AM_FAILURE

If any other error is detected

Details

If the specified name is NULL or empty, then logging messages will be sent to the stderr stream.

am_log_set_module_level()

Sets the logging level for the specified module.

Syntax

#include "am_log.h"
AM_EXPORT am_log_level_t
am_log_set_module_level(am_log_module_id_t moduleID,
               am_log_level_t level);

Parameters

This function takes the following parameters:

moduleID

The ID of the module to be modified.

level

The new logging level for the module.

Returns

This function returns am_log_level_t with one of the following values:

The previous logging level of the module.

When the logging level is set properly.

LOG_NONE

If the specified module is invalid.

am_log_set_remote_info()

Sets information about Access Manager log service for the remote log module.

This must be called before calling am_log_message() with AM_LOG_REMOTE_MODULE as the log module.

Otherwise use am_log_log() with a log record and SSO token ID to log to Access Manager.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_remote_info(const char *rem_log_url,
                        const char *sso_token_id,
                        const char *rem_log_name,
                        const am_properties_t log_props);

Parameters

This function takes the following parameters:

rem_log_url

URL of the Access Manager log service.

sso_token_id

The logged by SSO Token ID.

rem_log_name

The log name on Access Manager.

log_props

Properties to initialize the remote log service with.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the function call is successful.

AM_*

If an error occurs.

am_log_vlog()

Logs a message for the given module at the given level.

Syntax

#include "am_log.h"
AM_EXPORT boolean_t
am_log_vlog(am_log_module_id_t moduleID,
                                am_log_level_t level,
                                const char *format, ...);

Parameters

This function takes the following parameters:

module

The ID of the module to be associated with the message.

level

The logging level of the message.

format

A printf-style format string.

Returns

The set of addition arguments needed by the format string either enumerated directly or passed using the standard va_list mechanism as appropriate to the call.

Details

The message is emitted only if the current level of the specified module is greater than or equal to the specified level.