1. Administering Oracle Identity Governance
  2. Diagnostics and Troubleshooting
  3. Using the Identity Management Diagnostic Framework

29 Using the Identity Management Diagnostic Framework

Using the Identity Management Diagnostic Framework (IDMDF) involves enabling and configuring the framework, understanding how IDMDF works, and using the output for logging and debugging.

Topics

29.1 About the Identity Management Diagnostic Framework

Identity Management Diagnostic Framework (IDMDF) is a framework to provide first occurrence diagnostics and (Service-Level Agreement) SLA-based notification.

IDMDF provides a diagnostic framework that helps you with faster resolution of issues.

It provides the following capabilities:

  • Enable/disable SLA-based event monitoring for predefined events
  • Update/set SLA for predefined events
  • Detailed events logging for SLA breaches
  • Notification for SLA breaches along with events log
  • Trace level logs for failed operations and SLA breaches only if in-memory logging is enabled (should be used in rare cases only)

29.2 Enabling IDMDF

IDMDF is enabled or disabled by setting the value of the IDMDF: Enabled/Disabled By Sysadmin system property.

SLA-based monitoring in Oracle Identity Governance using IDMDF is disabled by default. To enable it:
  1. Log in to Identity System Administration.
  2. On the left navigation pane, under System Configuration, click Configuration Properties.
  3. In the System Configuration tab, search for the IDMDF: Enabled/Disabled By Sysadmin system property with keyword IDM.Diagnostics.Enabled.
  4. Click the system property name to open it.
  5. In the value field, replace the current value with true.
  6. Click Save.

29.3 Configuring the IDM Diagnostic Framework

Oracle Identity Governance provides a number of predefined system properties to control SLA-based monitoring and notification.

You can modify the values of the system properties to change the way you want to debug various operations. Table 29-1 lists these properties.

Table 29-1 Configurable Properties to Control Logging

System Property Description Default/Sample Value
IDMDF: Debug mode (true/false) Property to determine if the logs of IDMDF framework is saved in a log file. Default value is False, therefore, debug mode is disabled.

When set to True, debug mode is enabled.
IDMDF: Default SLA Property to determine the size of the default SLA for events. 600000 milliseconds
IDMDF: SMTP Server Name Property to specify the server responsible for sending email notification. localhost
IDMDF: Flood Control Duration(In Days) Property to indicate the retention period in days for Flood Control Max email. After the defined number of days, the Flood Control Max email counter is reset. 1
IDMDF: Enabled/Disabled By Sysadmin Property used by the system administrator to enable or disable IDMDF. false
IDMDF: Buffer size to hold context sensitive logs Property to determine the number of records in the queue that holds detailed logs of the product. 10000
IDMDF: Buffer size to hold failed records Property to determine the number of records in the queue that holds failed (functional/SLA) events. 1000
IDMDF: Max failed event to execute concurrently Property to determine the number of threads to execute events concurrently and put it in the database. 2
IDMDF: In-Memory Logging Property to determine if the logs are stored in the memory. false
IDMDF: Attachment FilePath Property to specify the path to store the attachment files. Default value: /scratch/IDMDFAttachment

Sample value: OIM_HOME/IDMDFAttachment/

IDMDF: Notification template file name Property to determine the notification template file name. None
IDMDF: Email Message Template Path Property to determine the path of the email message template. None
IDMDF: SLA template file name Property to determine the file containing the list of SLAs for defined use cases. None
IDMDF: IDMDF Rest service end-point Property to determine the URL on which IDMDF services are deployed. http://localhost:PORT/idmeventrecording
IDMDF: E-mail notification from Property to determine the email address from which notification is sent. dummy.dummy@dummy.com
IDMDF: E-mail notification to Property to determine the email address to which notification is sent. dummy.dummy@dummy.com
IDMDF: Notification provider Property to determine the service used for sending notifications. oracle.idm.diagnostics.notification.service.impl.IdmdfNotifier

Note: If you want to change the default notification provider and use a custom notification provider, then extend the oracle.idm.diagnostics.notification.service.impl.IdmdfNotifier base class. To do so, perform the procedure described in Configuring Custom Notification Provider.

IDMDF: Flood Control Max Email Property to determine the maximum number of notifications allowed per use case. 2

See Default System Properties in Oracle Identity Governance for more information about the predefined IDMDF system properties.

See Editing System Properties for information about modifying system properties.

29.4 Understanding the Workflow of SLA Monitoring

The order of precedence for logging and notification by IDMDF is determined by custom system properties, predefined SLA values, and a default SLA value for all events.

After you enable IDMDF, the SLA monitoring and notification works in the following way:
  1. Oracle Identity Governance lets you set the SLA value for an operation or event. You can do that by defining a system property with keyword in the format IDMDF:EVENT_NAME, and specifying an appropriate value. You can determine the event name by referring to a list of predefined event APIs and corresponding SLA values, as listed in SLA for Predefined Operations.

    For example, for the search catalog event, specify a keyword IDMDF.Search.Catalog for the system property you create with value as 50000 (in milliseconds). Here, the predefined event API name is Search Catalog-API. The value you specify for the system property will override the predefined SLA value, which is 60000 milliseconds. Therefore, if the search catalog operation takes more that 50000 milliseconds to complete, then a notification is sent to the administrator with diagnostic information.

    Note:

    See Adding System Properties for information about creating system properties.

    See Understanding the Output for information about the output of IDMDF and the mail format in which notification is sent.

    If a property is defined for the event and an appropriate value is set for that, then IDMDF uses that to log and send notification.
  2. If you do not define a system property for the event, then the default SLA value for that event API is considered by IDMDF for SLA monitoring and sending notification.
  3. If the SLA value is not predefined for an event, then the SLA value for that event is determined by the IDMDF: Default SLA system property. See Default System Properties in Oracle Identity Governance for information about the IDMDF: Default SLA system property.

29.5 SLA for Predefined Operations

Oracle Identity Governance provides default SLA values for a number of operations.

Table 29-2 lists the predefined operations or events and their corresponding SLA values.

Table 29-2 Predefined Events and SLA Values

Category Event SLA (in milliseconds)
CATALOG API Find Catalog-API 60000
CATALOG API Search Catalog-API 60000
CATALOG API Catalog Item Details-API 60000
CATALOG API Catalog Details In Bulk-API 60000
CATALOG API Catalog Details As Metadata-API 60000
CATALOG UI Find Catalog-UI 60000
CATALOG UI Catalog Item Details-UI 60000
SELF REGISTRATION API Self Registration-API 60000
SELF REGISTRATION UI Self Registration-UI 60000
TRACK REQUEST API Get Request Data-API 60000
TRACK REQUEST API Withdraw Request_API 60000
TRACK REQUEST API Close Request-API 60000
TRACK REQUEST API Get Requests-API 60000
TRACK REQUEST_UI Track Request-UI 60000
TRACK REQUEST_UI Withdraw Request-UI 60000
TRACK REQUEST_UI Close Request-UI 60000
TRACK REQUEST_UI Get Requests-UI 60000
Application Onboarding Create Application-REST 60000
Application Onboarding Create Application-API 60000
Application Onboarding Create Application Instance-API 60000
Reconciliation Create Reconciliation Event-API 60000
Provisioning Account Provision-API 60000
Provisioning Revoke Account-API 60000
Provisioning Revoke Entitlement-API 60000
Role API Create Role-API 60000
Role API Update Role-API 60000
Role API Modify Role Based On SearchCriteria-API 60000
Role API Delete Role-API 60000
Role API Delete Bulk Role-API 60000
Role UI Delete Bulk Role-API 60000
Access Policy API Evaluate Policies For User-API 60000
Access Policy API Initiate Policy Evaluation-API 60000
Access Policy API Create Access Policy-API 60000
Access Policy API Update Access Policy-API 60000
Access Policy API Delete Access Policy-API 60000
Access Policy UI Update Access Policy-UI 60000
Access Policy UI Delete Access Policy-UI 60000
Access Policy UI Create Access Policy-UI 60000
MY Information UI Update MyInfo Changes-UI 60000
MY Information UI Apply Changes For ChallengeQuestion-UI 60000
MY Information UI MyInformation Change User Password-UI 60000
MY Information UI Apply Proxy Add/Update-UI 60000
MY Information UI Remove Proxy-UI 60000
MY Information UI Remove All Proxy-UI 60000
My Information API Change password-API 60000
My Information API Set challenge values-API 60000
My Information API Modify Profile Details-API 60000
My Information API Add Proxy For User-API 60000
My Information API Update Proxy For User-API 60000
My Information API Remove Proxy-API 60000
My Information API Remove All Proxies For User-API 60000
Password Policy UI Delete Password Policy-UI 60000
Password Policy UI Apply Create/Update Password Policy-UI 60000
Password Policy API Delete Password Policy-API 60000
Password Policy API Update Password Policy-API 60000
Password Policy API Create Password Policy-API 60000
Certification API Complete Certification-API 60000
Certification API Certify Users-API 60000
Certification API Reassign Items Phase60000-API 60000
Certification API Save Certification Definition-API 60000
Certification API Create Certification Job-API 60000
Certification API Update Certification-API 60000
SoD API Initiate SoD Check=-API 60000
SoD API Get Result For Synchronous SoD Check-API 60000
SoD API Execute Sod Async Provisioning Task-API 60000
SoD API Execute Sod Async Task-API 60000
NA Create User-API 60000
NA Delete User-API 60000
NA Delete User by search criteria-API 60000
NA Delete Users in Bulk-API 60000
NA Update Audit Profile 60000
NA Update Audit Records 60000
NA Initialize IAuditor 60000
NA Create Auditor 60000
NA Create Audit Event 60000
NA Create Audit Event in Bulk 60000
NA Delete AuditEvent Group 60000
NA Create Fresh Profile 60000
NA Create AuditEvent Group 60000
NA Create and Modify Organization-UI 60000
NA Delete Organization-UI 60000
NA Modify User-API 60000
NA Modify User by search criteria-API 60000
NA Modify Users in bulk-API 60000
NA Create and Modify AdminRole-UI 60000
NA Save AdminRole-UI 60000
NA Delete the AdminRole-UI 60000
NA Approval Callback-UI 60000
NA Submit Request-UI 60000
NA Create User-REST 60000
NA Submit OIM Operation-API 60000
NA Submit Request-API 60000
NA Approval Callback-API 60000
NA Post Approval Callback-API 60000
NA Start Orchestration-API 60000
NA Create Organization-API 60000
NA Authorize Access-API 60000
NA Refresh Entity Cache-API 60000
NA Delete Organization-API 60000
NA Execute OIM Event 60000
NA Search Organization To Modify-API 60000
NA Modify Organization-API 60000
NA Send Notification-API 60000
NA Send Bulk Notification-API 60000
NA Create Admin Role-API 60000
NA Modify Admin Role-API 60000
NA Delete Admin Role-API 60000
NA Submit OIM Operation-API 60000
NA Async Processing-API 60000
NA Create Entity-API 60000
NA Modify Entity-API 60000
NA Delete Entity-API 60000
NA Find Entities-API 60000
NA Find Entity-API 60000

29.6 Understanding the Output

IDMDF sends an email notification for each SLA failure.

The email contains information about the event and broken SLA along with two attachments, a detailed log and an event tree XML file.

Notification Email

Table 29-3 lists the contents of the notification email.

Table 29-3 IDMDF Email Notification

Field Sample Value Description

User

4

The user ID of the logged-in user.

Product Name

OIG

The Identity Management product in which the event occurred. IDMDF supports event logging in Oracle Identity Governance (OIG) and Oracle Access Management (OAM).

SLA

2 ms

The default or defined SLA value in milliseconds.

Start Time

2019-03-01 01:18:24.99

The date and time when the event started.

End Time

2019-03-01 01:18:24.994

The date and time when the event ended.

Actual Time Taken

4 ms

The actual time taken in milliseconds for the event to complete.

ECID (Event Identifier)

dced1e07-1e20-4342-b8fb-3bc819b904df-0000000a

The unique identifier for the event.

Detailed Log

Table 29-4 lists the information in the detailed log attachment in the email notification.

Table 29-4 Detailed Log

Field Sample Value Description

Log Level

FINEST

The diagnostic log level, which can be INFO, FINE, FINEST, or NONE. See Configurable Diagnostic Levels Provided in the Framework for information about the diagnostic levels.

Log Time

Jan 14,2019 02:11:33.831

The date and time of the log.

Log Message

Number of invocations of loginSessionCreated is 6

The error or warning message indicating the problem.

Parameters

[getRunAsUser, configurationInstance, []]

The parameters of the log.

Source Class Name

AuthenticationContextUtilForEJB

The class from which the exception has been raised or source class in which the SLA breach has happened.

Source Method Name

setAuthenticationContextInEJB

The method name that is taking time to execute.

Stack Trace

 NA The trace that contains the detail of the events that are executed in between.

Event Tree XML

The event tree XML file contains information about the event execution. The following is the contents of a sample event tree XML file:

<structure>
   <thread>
      <threadId>25</threadId>
      <event name="Find Entities-API" startTime="Jan 14,2019 02:11:33.991" endTime="Jan 14,2019 02:11:34.002" status="SUCCESS">
         <eventDetails>find/lookup for a list of entites</eventDetails>
      </event>
      <event name="Authorize Access-API" startTime="Jan 14,2019 02:11:34.115" endTime="Jan 14,2019 02:11:34.115" status="SUCCESS">
         <eventDetails>Check if action is authorized for the user.</eventDetails>
      </event>
      <event name="Find Entity-API" startTime="Jan 14,2019 02:11:34.117" endTime="Jan 14,2019 02:11:34.131" status="SUCCESS">
         <eventDetails>find/lookup an entity</eventDetails>
      </event>
   </thread>
</structure>