11 Managing and Configuring EDRs, CDRs, and Alarms

Working with EdrAnalytic

Managed object: EdrAnalytic

MBean: oracle.ocsg.edr.analytic.management.EdrAnalyticMBean

listEdrListenerStatistics()

Persisting EDRs Until You Configure JMS Listeners

When you first start Services Gatekeeper, any EDRs generated by the network tier (NT) server are lost by default. They start getting captured after you configure and start the JMS listeners. The instructions in this section explain how to configure Services Gatekeeper to persist these first EDRs long enough to recover them in the JMS listeners.

To configure EDR persistence you need to:

• Set the EdrService MBean DeliverMode attribute to 2 to persist EDRs.

• Set the WLNGEDRResource Time-to-Live Override setting to 0, which directs the domain Java Message Service (JMS) servers to persist EDRs until the JMS listeners are started.

• Add the JMS server name and a unique client ID to the wlng.jar file.

Once you configure these settings, Services Gatekeeper startup EDRs are stored and later delivered to JMS listeners once those listeners are available. These instructions explain how to use the Administration Console to configure EDR persistence. You can set the DeliverMode attribute programmatically using the EdrServiceMbean. However you must use the Administration Console to set the Time-to-Live Override. See the ”All Classes” section of the OAM Java API Reference documentation for details on the EdrServiceMBean.

This section assumes that you have already installed Services Gatekeeper, and defined a JMS server inherited from com.bea.wlcp.wlng.api.edr.jms.JMSListener on the NT server to capture the EDRs. You need the JMS server name and a unique JMS client ID to complete this task. To obtain the JMS server name, open the Administration Console, and navigate to domain_name, then Services, then Messaging, then JMS servers.

To configure EDR persistence:

1. Start the Services Gatekeeper servers.

2. Start the Administration Console.

3. In the Change Center, click Lock and Edit.

4. Navigate to domain_name, then OCSG, then servername, then Container Services, then EdrService.

5. Set the DeliverMode attribute to 2.

6. Navigate to domain_name, then Services, then Messaging, then JMS Modules, then WLNGEDRResource, then Configuration, then EdrTopic, then Overrides.

7. Change the Time-to-Live Override setting to 0.

8. Click Save.

9. In the Change Center, click Activate Changes.

10. Open the Oracle_home/ocsg/server/lib/wlng/wlng.jar file for editing.

11. Add these parameters to your JMS Listener startup script:

    -DJMS_SERVER_NAME=JMSservername 
    -DJMS_CLIENT_ID=clientIDname
    

    Where JMSservername is the name of the JMS server to listen on, and clientIDname is a unique client ID for the listener.

Processing EDRs Using EdrServiceMBean

EdrServiceMBean configures some EDR processing options, and runs EDR processing operations. You can access this MBean from the Administration Console by selecting OCSG, then servername, then Container, then EdrService. Alternately, use a Java application. For information on the methods and fields of the supported MBeans, see the ”All Classes” section of Services Gatekeeper OAM Java API Reference.

This MBean controls EDR processing options such as:

• Whether to use the partitioned EDRs feature

• Whether to store EDRs, CDRs, and Alarms

• Whether to publish EDRs to JMS

• Whether to enable EDR statistics

• Setting the batchTimeout and batchSize options for EDR listeners.

• Whether to persist EDRs, CDRs, and alarms in the database

It also provide operations such as:

• displayStatistics

• loadEdrParamaterXml

• resetStatistics

and so on.

Table 11-1 describes EdrServiceMBean attributes that allow you to log EDRs, CDRs, and alarms to files that are configurable by type (EDR, CDR, alarm) and to globally set which attributes to log.

The PublishToJMS attribute is set to true if any of the type-specific publish-to-JMS attributes are true. For example, if PublishCdrToJms is set to true, PublishToJMS also is set to true. Furthermore, if you set PublishToJMS to true or false, without setting type-specific-publish-to-JMS attributes, the type-specific publish-to-JMS attributes likewise will be set to the same value.

Publishing Statistics

EDR statistics include statistics about how many EDRs, CDRs, and alarms have been published to file.

For example, the following displayStatistics operation shows how many EDRs, CDRs, and alarms were published to JMS and how many to files:

Gets EDR statistics
To use this operation the statisticsEnabled attribute must be set to true.
<p>The following information is returned:</p>
<ul>
<li>Number of EDRs</li>
<li>Smallest EDR message size in bytes</li>
<li>Largest EDR message size in bytes</li>
<li>Average EDR message size in bytes</li>
<li>Number of EDR messages pubished to JMS</li>
</ul>
<p><strong>Scope</strong>: Cluster</p>
@return Number of EDRs generated, and max/min/average size of the EDRs.

RESULT:

Number of EDRs: 0
          Smallest EDR: 2147483647 bytes
   Biggest EDR: 0 bytes
   Average EDR: -1 bytes
**Published to queue:
   Total: 1823
   Total:1823
   Rejected: 0

     Current Queue size [0]: 0
     Current Queue size [1]: 0
     Current Queue size [2]: 0
     Current Queue size [3]: 0
     Current Queue size [4]: 0
     Current Queue size [5]: 0
     Current Queue size [6]: 0
     Current Queue size [7]: 0
     Current Queue size [8]: 0
     Current Queue size [9]: 0
** Published internally:
    Total: 1823
    Error: 0
** Published to JMS:
    Total: 846
    Error: 0
** Internal Publisher:
    Edr: 1699
    Cdr: 846
    Alarm: 116
** Database:
    Cdr: 0
    Alarm: 0
** File
    Edr: 1694
    Cdr: 846
    Alarm: 122

Log4j Loggers

The following three loggers have been created for logging the types EDR, CDR, and alarm to files:

<RollingFile name="edr" fileName="servers/${sys:weblogic.Name}/edr_log/edr.json"
filePattern="servers/${sys:weblogic.Name}/edr_log/edr-%d{MM-dd-yyyy}.json">
  <PatternLayout>
    <Pattern>%m%n</Pattern>
  </PatternLayout>
  <Policies>
    <TimeBasedTriggeringPolicy interval="1"/>
  </Policies>
  <DefaultRolloverStrategy max="7" />
</RollingFile>

<RollingFile name="cdr" fileName="servers/${sys:weblogic.Name}/cdr_log/cdr.json"
filePattern="servers/${sys:weblogic.Name}/cdr_log/cdr-%d{MM-dd-yyyy}.json">
  <PatternLayout>
    <Pattern>%m%n</Pattern>
  </PatternLayout>
  <Policies>
    <TimeBasedTriggeringPolicy interval="1"/>
  </Policies>
  <DefaultRolloverStrategy max="7" />
</RollingFile>
 
<RollingFile name="alarm" fileName="servers/${sys:weblogic.Name}/alarm_log/alarm.json"
filePattern="servers/${sys:weblogic.Name}/alarm_log/alarm-%d{MM-dd-yyyy}.json">
  <PatternLayout>
    <Pattern>%m%n</Pattern>
  </PatternLayout>
  <Policies>
    <TimeBasedTriggeringPolicy interval="1"/>
  </Policies>
  <DefaultRolloverStrategy max="7" />
</RollingFile>
 
<Logger name="OCSG.EdrLogger" level="info" additivity="false">
  <AppenderRef ref="edr" />
</Logger>
 
<Logger name="OCSG.CdrLogger" level="info" additivity="false">
  <AppenderRef ref="cdr" />
</Logger>
 
<Logger name="OCSG.AlarmLogger" level="info" additivity="false">
  <AppenderRef ref="alarm" />
</Logger>

To store EDRs, CDRs, or alarms to a file, you must first enable file publishing in the MBean. You must also specify Log4j configuration to control how to log, for example, what kind of file rotation to use. The default is to rotate the files every midnight while keeping seven backup files.

Example Default API Management EDRs

This section provides example EDRs.

Example 11-3 shows an AT EDR.

AppInstanceId = user_linApp
Class = oracle.ocsg.daf.accesstier.AccessTierTrafficLogger
Direction = south
HttpMethod = GET
HttpStatusCode = 200
Position = after
ReqMsgSize = 0
RspMsgSize = 235
ServerName = WLNG_AT1
ServiceProviderGroup = usrGrp
ServiceProviderId = user
Source = method
State = ENTER_AT
TagEdr = 48001
Timestamp = 1454396477977
TransactionId = b709485c-3ec9-4dc7-9aa1-bfd9dc9ba3ad
TsAfAT = 1454396477977
TsBeAT = 1454396477112
URL = /daf/linApi/1/CUSTOMER/3

Example 11-3 shows the related NT EDR:

ApiId = 9a6aa6d6-c7ae-4a3c-b3b9-ccb0fcf50496
AppInstanceId = user_App1
ApplicationId = 6d8a5379-e186-454d-8baa-d076a45e1b7e
Class = oracle.ocsg.daf.trafficlogger.OcsgTrafficLogger
Method = GET@/userApi/1/CUSTOMER/3
Position = after
ReqAction = ["seq=1, name=OAuth2Validator, status=Success",
             "seq=2, name=SLAEnforcement, status=Success",
             "seq=3, name=Groovy, status=Success",
             "seq=4, name=Sender, status=Success"]
ServerName = WLNG_NT1
ServiceName = /userApi/1
ServiceProviderGroup = userGrp
ServiceProviderId = user
Source = method
State = ENTER_NT
TagEdr = 48000
Timestamp = 1454396477975
TransactionId = b709485c-3ec9-4dc7-9aa1-bfd9dc9ba3ad
TsAfNET = 1454396477974
TsAfNT = 1454396477975
TsBeNET = 1454396477122
TsBeNT = 1454396477117
URL = /daf/linApi/1/CUSTOMER/3
status = Success

Understanding Action Chain EDR Handling

At a minimum, error processing always generates EDRs with after ENTER_AT and after ENTER_NT states to ensure that you always get a certain minimum amount of debugging information for message handling.

The EDR TagEdr field helps identify where the EDR originated. See Table 11-2 for details.

Figure 11-2 shows the possible EDRs, numbered 1 to 6 for the two types of Services Gatekeeper implementations.

Error handling for traffic that uses the action chain has these characteristics. The numbers refer to the EDRs numbered in Figure 11-2:

• If a request message exits the action chain and cannot connect with network's HTTP server, an exception is thrown and a third EDR is generated

• Processing errors in the actions chain from a response message (from Network to Services Gatekeeper) does not generate an exception or an EDR. This is to ensure that actions chain processing continues in the event that one or more actions fail. However, status for individual actions are listed in ReqAction fields in each EDR.

• EDRS generated before the message enters the action chain will at least generate a number 5 EDR. This is the only EDR generated from the NT.

• Errors that occur inside the actions chain are typically runtime exceptions, and at a minimum will still generate EDRs number 2 and 5 in Figure 11-2. Runtime exceptions for an action do not stop the other actions from processing, and the event is recorded in EDRs.

• Action chain errors:

  • Runtime exceptions for one action do NOT stop the other actions from processing, and the exception is recorded in EDRs. In this case the result of all actions are recorded in the RspAction field in the After ENTER_NT EDR.

  • ActionProcessingError exceptions for an action, however do stop action chain processing. In this case the status code of the remaining EDRs indicate ActionProcessingError. In some of these cases an HTTP 500 Internal Server Error and Incident ID is returned to the HTTP client. See "Problem: Receiving an Internal Server Error and Incident ID" for more information.

    In this case the results of any completed actions are recorded in the RspAction field in the After ENTER_NT EDR (EDR #5 in Figure 11-2).

  For both types of error, the Source field is set to Method. If processing is successful without errors, the HTTP code remains set to original value set by the HTTP server.

• Errors generated by the network on the southbound side of Services Gatekeeper (typically server not running) will at least generate EDRs number 2, 3, and 5 from Figure 11-2.

Configuring Partitioned EDRs

This section explains how to configure EDR partitioning for your Services Gatekeeper implementation. These instructions explain how to configure EDR partitioning using the Administration Console. You can also use the EdrServiceMBean to select this option.

Before you start this process you must already have your JMS listeners configured. See "Understanding External EDR listeners" more information.

To configure EDR partitioning for an NT server:

1. Start the Administration Console.

   See "Starting and Using the Administration Console" for details.

2. Select Lock and Edit.

3. Navigate to OCSG, then servername_NTn, then Container Services, then EdrServiceMBean, then the Attributes tab.

   Where servername is the name of one of your NT servers, and n is the server number. For example myserverNT3.

4. In the BatchGroupingNumber attribute field, enter the number of EDR listeners you have configured.

   A value of 0 or 1 specifies that all EDRs are sent to all listeners (the default). A value of 2 or greater specifies EDR partitioning.

   Note:

   If you set BatchGroupingNumber lower than the number of JMS listeners, one or more JMS listeners do not receive any EDRs. Setting the number too high has no effect; all JMS listeners receive the correct EDRs.

5. Navigate to Services, then Messages, then JMS Modules, then, WLNGEDRResource, then EdrTopic, then Configuration.

6. Select the General tab.

7. On the Forwarding Policy: menu select Partitioned.

8. Save your changes.