Introduction

Log Services is a Tibco component, which allows configuration of log messages via kcs file called message catalog. Besides that provides SNMP trap functionality - ability to send SNMP traps from given log message. Currently Log Services component is used just for SNMP trap log messages.

Functionality

  • log messages configurable via message catalog (kcs file)
  • message catalog auditing - no duplicate ids, ...
  • sending SNMP trap messages (uses snmptrapappender component)
  • default messages are used when message catalog is not loaded
  • administration target to display components with loaded message catalogs and their log levels
  • administration target to enable/disable specific log level for given parameter and value, e.g. msisdn
  • administration target to generate MIB file from SNMP trap messages defined in the message catalog

Planned

  • able to set global locale ( for example, to get messages in french )

Naming conventions

  1. Name of message catalog kcs file must be message.catalog.[componentname].kcs It's important, because the script for loading configuration – bex_loadmulticonfig searches for files of this pattern and loads them together
  2. In projects and components, Logservices.message should be wrapped to another method, which sets parameter componentName of the Logservices.message. It should be called Log.message, or Log[ComponentName].message.

Basic usage

For detailed description of the usage see sections component integration and project integration. If your project already has message catalog and you need to add simple log message (not SNMP trap), you need to follow next steps:

  • Find a class and method, which wraps Logservices.message method and sets component name.

    It should be called Log.message or Log[ComponentName].message. In our example it will be LogComponentA.message

    Note that logservices assumes an active transaction.

    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    /**
     * Wrapper for message method - sets componentName
     */
    public class LogComponentA {
     
        public final static String componentName = "A";
     
        /**
         * wrapper for LogServices.message which sets component name value as parameter 
         */
        public static void message(long messageId, String defaultString, String[] params){
            LogServices.message(componentName, messageId, defaultString, params);
        }
     
        public static void message(long messageId, String[] params){
            LogServices.message(componentName, messageId, params);
        }
    }
  • Use this method for your log messages.

    Find message catalog (kcs file) called message.catalog.[componentname].kcs . It should be in main/src/config directory (for components) or in config directory of frameworks and projects.

  • Call LogComponentA.message (or other appropriate method from your tree) from your code
    25
    26
    // notice that parameters and their values are separated by ":"
    LogComponentA.message(2, "default message ${portNumber}", new String[]{"portNumber:4444"});

    Note that the alarmId parameter in the list of parameters is optional. If specified and no catalog configuration exists for this message then it forces an alarm. In general, however, the catalog configuration should be used to map a given message to an alarm.

  • Add this message to the message catalog (kcs file).
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    {
    messageId = 2;
     
    locale = "en";
     
    message = "Service running on port ${portNumber}";
     
    severity = INFO;
     
    params =
    {
        {
         name = "portNumber";
         description = "port number";
        }
    };
    }
  • Adding SNMP trap is the same as for simple log message above, just you need to provide also alarmId parameter and in message catalog also alarmMessage.

    Example of an alarm definition in a message catalog:

    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    {
    messageId = 1;
     
    locale = "en";
     
    message = "ClientEndpoint: Bind failed";
     
    severity = ERROR;
     
    correlationId = 1;
     
    alarmId = "1";
     
    alarmMessage= "BIND_FAILED";
     
    params =
    {
        {
         name = "alarmId";
     
         description = "snmp alarm id";
        }
    };
    },

    Example of logging of an alarm event:

    245
    246
    247
    248
    if(!lc.isBound()) {
        // bind failed                 
        Log.message(1, "ClientEndpoint: Bind failed", new String[]{"alarmId:1"});
        lc.disconnect();

Admin commands

  • display

    Display one or all components which have loaded message catalogs with their default log level. If parameter componentname is not present, display list of all components with log levels, otherwise just one specified component.

    parameter presence description
    componentname optional if present, show log level of given component otherwise list of all components with loaded message catalogs and their log levels

    Example:

    display logservices componentname=diameterchannel
  • addfilter

    Change log level of the logger for log messages which contains given parameter and value.

    parameter presence description
    parameter mandatory name of the parameter used for log message
    value mandatory value of the parameter used for log message
    loglevel mandatory logger level for given message containing parameter with specified value

    Example:

    addfilter logservices parameter=msisdn value=00447542453452 loglevel=INFO
  • generatemib

    Generate MIB file from given component's message catalog (kcs file). Message catalog must be loaded and activated before generating MIB file. Generated MIB uses definitions from TIBCOTHREEGPPTRAP-MIB.mib, which is contained in the Log Services project tree, in the snmp directory.

    parameter presence description
    componentname mandatory name of the component for which MIB will be generated, String
    packagetrapoid mandatory unique OID for component, Integer
    outputfilename mandatory output file name, String

    Example:

    generatemib logservices componentname=diameterchannel packagetrapoid=100 outputfilename="DIAMETER.MIB"
  • exportapt

    Export the loaded configuration in APT (Almost Plain Text) format for inclusion into site documentation.

    parameter presence description
    componentname mandatory name of the component to export, String
    filename mandatory name of the file to generate, Stringß