1. Administering Oracle Internet Directory
  2. Basic Administration
  3. Monitoring Oracle Internet Directory

25 Monitoring Oracle Internet Directory

This chapter describes the Oracle Internet Directory Manageability framework, which enables you to monitor statistics for Oracle Internet Directory. It describes how to configure and view statistics collection using Oracle Enterprise Manager Fusion Middleware Control, configure statistics using LDAP command-line utilities, and view statistics using Oracle Directory Services Manager (ODSM) and the oiddiag tool.

For information about monitoring other Oracle Fusion Middleware components, see Monitoring Oracle Fusion Middleware in Administering Oracle Fusion Middleware.

25.1 Introduction to Monitoring Oracle Internet Directory Server

This section introduces you to how to monitor Oracle Internet Directory server.

For more information on how to monitor Oracle Internet Directory server, refer to the following sections:

25.1.1 Capabilities of Oracle Internet Directory Server Manageability

The Oracle Internet Directory Server Manageability framework enables you to monitor the directory server statistics:

  • Server health statistics about LDAP request queues, percent CPU usage, memory, LDAP sessions, and database sessions. For example, you can view the number of active database sessions over a period. You can also view the total number of connections opened to Oracle Internet Directory server instances over a period.

  • Performance statistics. Average latency in millisecond is provided for bind, compare, messaging search, and all search operations over a period.

  • General statistics about specific server operations, such as add, modify, or delete. For example, you can view the number of directory server operations over a period. You can also view the failed bind operation count.

  • User statistics comprising successful and failed operations to the directory and the user performing each one. All LDAP operations are tracked for configured users. Also, the connections held by users at the ends of the statistics collection period are tracked.

  • Critical events related to system resources and security—for example, occasions when a user provided the wrong password or had inadequate access rights to perform an operation. Other critical events include ORA errors other than expected errors including 1, 100 or 1403 and abnormal termination of the LDAP server.

  • Security events tracking of users' successful and unsuccessful bind and userpassword compare operations.

    Because bind and user password compare are among the most security sensitive operations, an exclusive category security event is used to track these two operations. This event tracks the number of these operations performed by LDAP users and applications. The basic information recorded is user DN and source IP address. For failed user password compare, additional information is tracked, specifically, the number of failed compares of one user's password by another user from a given IP address.

  • Status information of the directory server and the directory replication server—for example, the date and time at which the directory replication server was invoked

25.1.2 Oracle Internet Directory Server Manageability Architecture and Components

There are various relationships between various components of directory server manageability.

The relationship between the various components of directory server manageability is explained in Figure 25-1 and the accompanying text in Table 25-1.

Figure 25-1 Architecture of Oracle Internet Directory Server Manageability

Architecture of Oracle Internet Directory Server Manageability

Table 25-1 Components of Oracle Internet Directory Server Manageability

Component Description

Oracle Internet Directory

A directory server responds to directory requests from clients. It has four kinds of functional threads: controller, worker, dispatcher, and listener. It accepts LDAP requests from clients, processes them, and sends the LDAP response back to the clients.

When you use the Oracle Internet Directory Server Manageability framework to set run-time monitoring, the four functional threads of the server record the specified information and store it in local memory.

See Also: Oracle Directory Server Instance for a description of the directory server

Memory Resident Storage

This is a local process memory. The Oracle Internet Directory Server Manageability framework assigns one each for statistics, tracing, and security events. Each has its own separate data structure maintained in the local memory storage.

Low Priority Write Threads

These dedicated write threads differ from server functional threads in that they write server statistics, security events logging, and tracing information to the repository. To maintain reduced system overhead, their priorities are kept low.

External Monitoring Application

This module, which is proprietary and external to the server manageability framework, collects the gathered statistics through a standard LDAP interface with the directory server and stores it in its own repository.

External Repository for Server Management Information

This is the repository that the monitoring agent uses to store the gathered directory server statistics. The monitoring agent determines how this repository is implemented.

Fusion Middleware Control

extracts monitored data from the statistics and events repository, presenting it in a Web-based graphical user interface. Users can view the data in a normal browser. A repository can store the collected data for generic and custom queries.

Logging Repository (File System)

This repository uses a file system to store information traced across various modules of the directory server. By using a file system for this purpose, the Oracle Internet Directory Server Manageability framework uses the features and security of the operating system.

Directory Data Repository

This repository contains all user-entered data—for example, user and group entries.

Statistics and Events Repository

This repository is like the tracing repository except that it stores the information in the same database as the directory data repository rather than in a file system. In this way, the Oracle Internet Directory Server Manageability framework uses:

  • Normal LDAP operations to store and retrieve the information

  • Existing access control policies to manage the security of the gathered information

The directory manageability framework isolates the gathered information from the directory data by storing the two separately.
Oracle Internet Directory Metrics REST API Fetches monitored data from the statistics and events repository. Administrators can query this data using the REST API and use the data to present it in any desired dashboard to monitor Oracle Internet Directory.

25.1.3 Security Events and Statistics Entries Purge

Obsolete statistics entries are removed from Oracle Internet Directory by the Oracle Internet Directory purge tool.

Obsolete statistics entries are removed from Oracle Internet Directory by the Oracle Internet Directory purge tool, described in Managing Garbage Collection.

25.1.4 Account Used for Accessing Server Manageability Information

The Oracle Internet Directory database account ODSSM is used to access server manageability information from the database.

During installation, this account's password is set to a value provided by the user at a prompt. The credentials for this account, including the password, are stored in the Oracle Internet Directory snippet in the Oracle Enterprise Manager Fusion Middleware Control file targets.xml.

The only way you can change this account's password is to use the procedure documented in Changing the Password for the ODSSM Administrator Account. There is no support in the oidpasswd tool for changing this password.

25.2 Overview of Statistics Collection Using Fusion Middleware Control

You can view statistics using Fusion Middleware Control.

This section contains the following topics:

25.2.1 Configuring Directory Server Statistics Collection Using Fusion Middleware Control

You can configure directory server statistics collection by using Fusion Middleware control.

To configure statistics collection from Oracle Enterprise Manager Fusion Middleware Control, follow these steps:

  1. Select Administration, then Server Properties from the Oracle Internet Directory menu, then select Statistics.
  2. In the General section of the page, select Stats Flag to enable statistics collection.
  3. Specify the number of minutes in the Stats Frequency field to control the frequency of statistics collection.
  4. Select values from the Bind Security Event Tracking and Compare Security Event Tracking lists.
  5. To collect statistics about users, select User Statistics Collection in the User Statistics section of the page.
  6. In the Event Levels section of the page, select the events you want to track.

Table 25-2 Configuration Attributes on Server Properties Page, Statistics Tab

Field or Heading Configuration Attribute

Stats Flag

orclstatsflag

Stats Frequency (min)

orclstatsperiodicity

Bind Security Event Tracking and Compare Security Event Tracking

orcloptracklevel

User Statistics

orclstatslevel

Event Levels

orcleventlevel

Note:

  • After you enable User Statistics collection, you also must specify individual users for statistics collection. See Configuring a User for Statistics Collection Using Fusion Middleware Control.

  • If you do not select SuperUser Login as an event level, the corresponding Security values on the Oracle Internet Directory home page is always 0.

  • Since 11g Release 1 (11.1.1.0.0), consecutive settings of orcldebugflag and of orcloptracklevel are additive.

25.2.2 Configuring a User for Statistics Collection Using Fusion Middleware Control

You can configure a user for statistics collection using Fusion Middleware control.

Note:

If you have configured orclldapconntimeout so that idle LDAP connections are closed after a period of time, as described in the LDAP Server Attributes in Tuning Performance, be aware that connections do not time out as per this setting for users who are configured for statistics collection.

To configure a user so that Server Manageability collects statistics for that user:

  1. From the Oracle Internet Directory menu, select Administration, then Shared Properties.
  2. Select the General tab.
  3. Add the user's distinguished name to User DN. (This adds the user's DN to the attribute orclstatsdn.) For example:
    cn=Mary Lee, ou=Product Testing, c=uscn=Michael Smith, ou=Product Testing, c=uscn=Raj Sharma, ou=Human Resources, c=us

25.3 Overview of Statistics Information Viewable from Fusion Middleware Control

You can use Oracle Enterprise Manager Fusion Middleware Control to view many of the features of Oracle Internet Directory Server Manageability, as explained in this section.

For more information, refer to the following sections:

25.3.1 Statistics Information Viewable from the Oracle Internet Directory Home Page

The Oracle Internet Directory home page displays Performance, Load, Security, Resource usage and Average response & Load related statistics information.

The Oracle Internet Directory Home Page displays the following information:

  • Performance

    • Average Operation Response Time(ms)

    • Messaging Search Response Time(ms)

    • Bind Response Time(ms)

  • Load

    • Total LDAP Connections

    • Operations Completed

    • Operations in progress

  • Security

    • Failed Bind Operations

    • Failed SuperUser Logins

    • Successful SuperUser Logins

  • Resource Usage

    • CPU Utilization%

    • Memory Utilization%

  • Average Response and Load

    • LDAPserverResponse

    • numCompletedOps

Click Table View if you want to see values in tabular form.

In the Security section of the page, the values for Failed Bind Operations, Failed SuperUser Logins, and Successful SuperUser Logins are 0 if you have not enabled collection of these metrics. See Overview of Statistics Collection Using Fusion Middleware Control for more information.

25.3.2 Viewing Information on the Oracle Internet Directory Performance Page

The Oracle Internet Directory performance page displays performance summary information.

From the Oracle Internet Directory menu, select Monitoring, then Performance Summary. The following metrics are shown by default:

  • Server Response

  • Total Operations

  • Messaging Search Operation Response Time

  • Bind Operation Response Time

  • Compare Operation Response Time

  • Total Number of Security Events Objects in Purge Queue

  • Total Number of Security Refresh Events Objects in Purge Queue

  • Total Number of System Resource Events Objects in Purge Queue

To display other metrics, expand the Metrics Palette by clicking the arrow on the right edge of the window. You can collapse the Metrics Palette by clicking the arrow on the left edge of the window.

The default time interval is 15 minutes. To change the time interval, click Slider, then use the sliders to set the time interval. You can also click the Date and Time icon, set the start and end date and time on the Enter Date and Time dialog, then click OK.

Click the Refresh icon to refresh the page.

The View list enables you to view and save charts.

The Overlay list enables you to overlay the metrics for a different Oracle Internet Directory target.

Note:

  • For non-critical events, there is a time lag of several minutes, up to orclstatsperiodicity, before the corresponding metric is updated.

  • You must click the Refresh icon to see updated metrics.

25.4 Overview of Statistics Collection Using Metrics REST API

You can use Oracle Internet Directory Metrics REST API to query OID runtime statistics information.

For more information, refer the following sections:

25.4.1 Enabling Oracle Internet Directory Metrics REST API

You need to deploy Metrics REST API in the Weblogic server by extending the existing Weblogic Domain, where OID is installed. You need to use the Oracle Internet Directory Metrics (Collocated) Weblogic template to extend the existing Weblogic Domain. This will install the OID Metrics REST API along with a Weblogic JDBC data source.

25.4.2 Securing Oracle Internet Directory Metrics REST API

The REST API is protected by Basic Authentication mechanism in Weblogic. Users with "Administrators" or "OIDAdministrators" group membership have access to the metrics data.

25.4.3 Statistics Information Accessible from Metrics REST API

You can use Oracle Internet Directory Metrics REST API to query the OID runtime statistics information. Further, you can present the OID runtime statistics information in any desired dashboard application to monitor Oracle Internet Directory.

The following metrics information is available from the REST API for various operations:

  • Performance

    • Average Operation Response Time (micro seconds)
    • Message Search Response Time (micro seconds)
    • Bind Response Time (micro seconds)
    • Compare Response Time (micro seconds)

  • Load

    • Total LDAP Connections
    • Operations Completed
    • Operations in Progress

  • Security

    • Failed Bind Operations

25.5 Statistics Information Accessible from the Oracle Directory Services Manager Home Page

You can access various statistics information from Oracle Directory Services Manager.

The Oracle Directory Services Manager home page for Oracle Internet Directory lists the following information:

  • Uptime

  • LDAP Connections

  • OID Procs

  • Number of Entries

  • LDAP Change Log Entries

  • Replication Agreements

  • Debug Enabled

  • Operation Latency

25.6 Understanding Statistics Collection Using the Command-Line

Using command-line utility, you can collect various statistics information as described in this section.

This section contains the following topics:

25.6.1 Configuring Health, General, and Performance Statistics Attributes

You can use ldapmodify and ldapsearch to set and view statistics collection-related configuration attributes.

The attributes are in the instance-specific configuration entry, as described in Managing System Configuration Attributes.

To enable the collection of health, general, and performance statistics, set the orclStatsFlag and orclStatsPeriodicity attributes.

For example, to enable the Oracle Internet Directory Server Manageability framework for the component oid1, you create an LDIF file that looks like this: 

dn:cn=oid1,cn=osdldapd,cn=subconfigsubentry
changetype: modify
replace: orclstatsflag
orclstatsflag:1

To upload this file, enter the following command:

ldapmodify -h host -p port_number -D bind_DN -q -f file_name

where the bind DN authorized to perform server manageability configuration is cn=emd admin,cn=oracle internet directory.

25.6.2 Configuring Security Events Tracking

To configure security events tracking, set the attribute orcloptracklevel.

The attribute, orcloptracklevel is located in the instance-specific configuration entry, as described in Managing System Configuration Attributes. Table 25-3 lists the values of orcloptracklevel to configure different levels of bind and compare information collection:

Table 25-3 Values of orcloptracklevel

orcloptracklevel value Configuration

1

Bind DN only

2

Bind DN and IP address

4

Compare DN only

8

Compare DN and IP address

16

Compare DN, IP address and failure details

The metrics recorded by each orcloptracklevel value are listed in the following table:

Table 25-4 Metrics Recorded by Each orcloptracklevel Value

Configuration Metrics Recorded

DN only

Date and time stamp

EID of DN performing the operation

Success counts

Failure counts

DN and IP address

All metrics listed under DN only

Source IP Address

DN, IP address and failure details

All metrics listed under DN and IP address

Distinct success counts

Distinct failure counts

Failure details for each DN performing password compare from an IP Address:

  • Date and time stamp

  • Source IP Address

  • EID of DN whose password is compared

  • Failure counts

The attributes orcloptrackmaxtotalsize and orcloptracknumelemcontainers enable you to tune memory used for tracking statistics and events.

See Tuning Security Event Tracking in Tuning Performance.

25.6.3 Configuring User Statistics Collection from the Command Line

To enable user statistics, set the orclstatslevel attribute to 1. The orclStatsPeriodicity attribute must also be set for user statistics collection to occur.

Note:

When you are collecting statistics for Oracle Enterprise Manager Fusion Middleware Control, set orclStatsPeriodicity to be the same as the collection periodicity of the Enterprise Manager agent, which is 10 minutes by default.

To configure users for statistics collection, see Configuring a User for Statistics Collection Using the Command Line.

25.6.4 Configuring Event Levels from the Command Line

The orclstatsflag attribute must be set to 1 for event level tracking to occur.

To configure event levels, use ldapmodify to set the orcleventlevel attribute to one or more of the event levels listed in Table 25-5. The attribute orcleventlevel is in the instance-specific configuration entry, as described in Managing System Configuration Attributes.

Table 25-5 Event Levels

Level Value Critical Event Information It Provides

1

SuperUser login

Super uses bind (successes or failures)

2

Proxy user login

Proxy user bind (failures)

4

Replication login

Replication bind (failures)

8

Add access

Add access violation

16

Delete access

Delete access violation

32

Write access

Write access violation

64

ORA 3113 error

Loss of connection to database

128

ORA 3114 error

Loss of connection to database

256

ORA 28 error

ORA-28 Error

512

ORA error

ORA errors other an expected 1, 100, or 1403

1024

Oracle Internet Directory server termination count

2047

All critical events

25.6.5 Configuring a User for Statistics Collection Using the Command Line

Using command line utility, you can configure a user for collecting statistics form the server.

Note:

If you have configured orclldapconntimeout so that idle LDAP connections are closed after a period of time, as described in the LDAP Server Attributes in Tuning Performance, be aware that connections do not time out as per this setting for users who are configured for statistics collection.

To configure a user by using the command line, add the user's DN to the DSA Configset entry's multivalued attribute orclstatsdn (DN: cn=dsaconfig,cn=configsets,cn=oracle internet directory) by using the ldapmodify command line tool. For example, this LDIF file adds Mary Lee to orclstatsdn: 

dn: cn=dsaconfig,cn=configsets,cn=oracle internet directory
changetype:modify
add: orclstatsdn
orclstatsdn: cn=Mary Lee, ou=Product Testing, c=us

Use a command line such as:

ldapmodify -h host -p port -f ldifFile -D cn=orcladmin -q

25.7 Viewing Information with the OIDDIAG Tool

Using OIDDIAG tool, you can view reports of various statistics.

Reports for all the statistics can be viewed using the oiddiag tool, as follows:

Security Events

oiddiag audit_report=true [outfile=file_name]

All Statistics and Events

oiddiag collect_all=true [outfile=file_name]

Subset of Statistics and Events

oiddiag collect_sub=true [infile=input_file_name outfile=file_name ]

where input_file_name is created by taking the output from 

oiddiag listdiags=true

and removing unwanted statistics classes.

Statistics in HTML format

oiddiag collect_stats=true [outfile=file_name]

Note:

On Windows, the filename of the oiddiag command is oiddiag.bat.

Note:

Starting from this release, you can generate a HTML report which contains the following by supplying collect_stats=true argument:

  • Instance Statistics

  • Operations Statistics

  • Memory/CPU Usage Statistics

  • Network Bytes Sent/Received

  • Client Connections/Operations Statistics

  • DB Connections Statistics

  • LDAP Connections Statistics

  • Replication Operations Statistics

  • Replication Queue Statistics (for all replication agreements)

See Also:

25.8 Monitoring Oracle Internet Directory Server Using LDAP

Oracle Internet Directory provides a variety of methods to monitor the current state of the server for debugging or troubleshooting purposes.

You can monitor the server over LDAP in the following ways:

25.8.1 Viewing Monitoring Information Using the cn=monitor Entry

Oracle Internet Directory records system, performance, and version information as an entry with the base DN of cn=monitor. This entry provides useful performance metrics and server state information that you can use to monitor and debug a directory server instance.

The first level entries under cn=monitor are the categories of available monitoring information. For each category, there is only one attribute called orclmetricsummary, which includes all the monitoring information for that category in the report form. Subtypes of orclmetricsummary further describe the monitoring information.

Note:

Monitoring information using the cn=monitor entry is enabled by default. However, care must be taken to avoid overusing this capability as it can adversely affect performance.

25.8.2 Viewing the Available Monitoring Information

Use the ldapsearch command with the base DN "cn=monitor" to print the supported categories of monitoring information. 

$ ldapsearch -h localhost -p 3060 -D cn=orcladmin –w password –b "cn=monitor" "objectclass=*" -s base

The output will be similar to the following:

cn=monitor
orclmetricsummary;categories=cn=system information,cn=monitor
cn=work queue,cn=monitor
cn=client connections,cn=monitor
cn=version,cn=monitor

25.8.3 Monitoring System Information

Use the ldapsearch command with the base DN "cn=System Information,cn=monitor" to display general system information like OS version. 

$ ldapsearch -h localhost -p 3060 -D cn=orcladmin –w password –b "cn=system information,cn=monitor" "objectclass=*" -s base

The output will be similar to the following:

cn=system information,cn=monitor
orclmetricsummary;os_version=Linux 2.6.39-400.298.2.el5uek x86_64

25.8.4 Monitoring the Work Queue

Use the ldapsearch command with base DN "cn=work queue,cn=monitor" to keep track of outstanding client requests and ensures that they are processed. It displays work queue size and latency information. 

$ ldapsearch -h localhost -p 3070 -D cn=orcladmin –w password –b "cn=work queue,cn=monitor" "objectclass=*" -s base

The output will be similar to the following:

cn=work queue,cn=monitor
orclmetricsummary;overall_stats=total_queue_size:0, avg_queue_latency:3258.000000 micro sec
orclmetricsummary;/inst1/oid1/1=total_queue_size:0, avg_queue_latency:3042 micro sec
orclmetricsummary;/inst1/oid2/1=total_queue_size:0, avg_queue_latency:3474 micro sec

25.8.5 Monitoring Client Connections

Use the ldapsearch command with base DN "cn=client connections,cn=monitor" to display the connection throughput information per instance and the top performing connections details. 

$ ldapsearch -h localhost -p 3060 -D cn=orcladmin –w password –b "cn=client connections, cn=monitor" "objectclass=*" -s base

The output will be similar to the following:

cn=client connections,cn=monitor
orclmetricsummary;/inst1/oid1/1=open_connections:0, new_connections:21, closed_connections:21
orclmetricsummary;/inst1/oid2/1=open_connections:0, new_connections:20, closed_connections:20
orclmetricsummary;top_connections=user_dn:cn=orcladmin, user_ip:::ffff:10.196.16.156, open_connections:0, total_ops:43, bind_ops:21, proxy_bind_ops:0, unbind_ops:21, compare_ops:0, search_base_ops:1, search_one_ops:0, search_sub_ops:0, add_ops:0, delete_ops:0, modify_ops:0, modrdn_ops:0, abandon_ops:0
user_dn:cn=emd admin,cn=oracle internet directory, user_ip:::ffff:10.196.16.156, open_connections:0, total_ops:40, bind_ops:20, proxy_bind_ops:0, unbind_ops:20, compare_ops:0, search_base_ops:0, search_one_ops:0, search_sub_ops:0, add_ops:0, delete_ops:0, modify_ops:0, modrdn_ops:0, abandon_ops:0

Note:

OID can only identify the IP addresses that it receives at its end. If you are using a load balancer then OID cannot identify the actual IP address of the client.

25.8.6 Monitoring Version Information

Use the ldapsearch command with base DN "cn=version,cn=monitor" to display Oracle Internet Directory and database version. 

$ ldapsearch -h localhost -p 3070 -D cn=orcladmin –w password –b "cn=version, cn=monitor" "objectclass=*" -s base

The output will be similar to the following:

cn=version,cn=monitor
orclmetricsummary;oid_version=12.2.1.4.0
orclmetricsummary;db_version=12.1.0.2.0