The MediaSense open Application Programming Interface (API) list is available for third-party users to securely perform the following functions:

• Pause and resume, hold and resume, or conference and transfer a recording while in progress.

• Control a recorded session.

• Search and manage existing recordings.

• Monitor a live session.

MediaSense APIs provide an alternate to the functionality that is available through the MediaSense web interface. Using these APIs, users can create customized client applications. System integrators and developers who want to use MediaSense to integrate with other Unified Communications software or any third-party software applications need to have access to the MediaSense API. See Unified Communications Manager User Information and MediaSense Setup.

MediaSense deployments provide pruning options to address varied deployment scenarios. Pruning options are specified on the Administration > Prune Policy Configuration page.

These pruning options allow you to enter the following modes:

• New Recording Priority mode—In this mode, the priority is on providing space for newer recordings, by automatically pruning older recordings. This is the default behavior. The default age after which recordings will be pruned is 60 days. Old recordings will also be pruned if disk space is required for new recordings.

• Old Recording Retention mode—In this mode, priority is placed on retaining older recordings. Old recordings are not automatically pruned.

To focus priority on making new recordings in the New Recording Priority mode, check Automatically prune recordings after they are more than __days old, and when disk space is needed for new recordings check box. When this check box is checked, a recording is deleted when one of the following conditions is met:

• The age of the recording is equal to or greater than the retention age that you specify in the field for this option (valid range is from 1 to 3650 days).

  For example, if you are within your disk usage percentage and if you want to automatically delete all recordings older than 90 days, you must enter 90 in the Automatically prune recordings after they are more than __days old, and when disk space is needed for new recordings field. In this case, all recordings which are older than 90 days are automatically deleted. The default value is 60 days.

  Note

  A day is identified as 24 hours from the precise time you change this setting—it is not identified as a calendar day. For example, if you change the retention period at 23.15.01 on April 2, 2010, the specified recordings will be deleted only at 23.15.01 on April 3, 2010. The recordings will not be deleted at 00:00:01 on April 3, 2010.

• The disk usage has crossed the 90 percent mark. When the disk usage crosses the 90 percent mark, some sessions are pruned based on age criteria. This pruning continues until the disk usage is acceptable.

  Note

  When you use this option to automatically delete recordings, MediaSense removes older recording data irrespective of contents. The priority is provided to newly recorded media and disk space is overwritten to accommodate new recordings. If you want to use the preceding option (New Recording Priority mode) and, at the same time, you want to protect a particular session from being automatically pruned, be sure to store that session in MP4 format, download the MP4 file, and save it to a suitable location in your network. You can also use the downloadUrl parameter in the Session Query APIs and download the raw recording to a location of your choice.

When sessions are pruned, the corresponding metadata is not removed from the database; nor is the data marked as deleted in the database. MediaSense also provides options (radio buttons) that allow you to choose (or decline) to have this associated session data removed automatically.

The following options allow you choose how to handle data associated with pruned sessions:

• To have MediaSense remove the associated data automatically, select the Automatically remove associated data and mp4 files radio button.

• If you select the Do not automatically remove associated data and mp4 files radio button, the associated data will not be removed automatically. Instead, your client application must explicitly remove automatically pruned recordings, by way of the getAllPrunedSessions API and the deleteSessions API. When the deleteSessions API is executed, the metadata is marked as deleted, and the MP4 files are deleted.

To place the priority on retaining older recordings (Old Recording Retention mode), uncheck the Automatically prune recordings after they are more than __days old, and when disk space is needed for new recordings check box. If this check box is unchecked, Cisco MediaSense does not automatically prune data for those recordings that are created after the check box is unchecked. To remove unwanted data and free up disk space, use your client application. See the Developer Guide for Cisco MediaSense at http:/​/​www.cisco.com/​en/​US/​products/​ps11389/​products_​programming_​reference_​guides_​list.html for more information.

Note	If this check box is unchecked, the Old Recording Retention mode is applicable only to those recordings that are created after the box is unchecked; it does not prevent prior recordings that were created previously from being pruned.

Caution

If you do not clean up unwanted data periodically, the call control service rejects new calls and drops existing recordings at the emergency threshold level (ENTER_EMERGENCY_STORAGE_SPACE). See System Thresholds for more details.

Storage Management agent (SM agent) monitors the storage thresholds on a per server basis. The thresholds are for the total space used on each server and do not attempt to distinguish between the media types being stored.

Periodic storage capacity checks are performed to maintain the health of the system and recordings.

You can also obtain the current storage use information using HTTP GET requests. The URL for accessing this information is:

http://<server-ip-address>/storagemanageragent/usage.xml

The storage use information is provided in an XML format.

• Example 1— Does not use any media disks:

                  <?xml version="1.0" encoding="UTF-8" ?>
                  - <storageUsageInfo date="Oct 26 2010" time="13:24:22" gmt="1288124662599">
                  - <partitions>
                    <partition name="/common" size="655G" usage="29%" />
                    </partitions>
                    </storageUsageInfo>
                

• Example 2—Uses two media partitions:

                  <?xml version="1.0" encoding="UTF-8" ?>
                  <storageUsageInfo date="Oct 26 2010" time="13:10:53" gmt="1288123853753">
                   <partitions>
                    <partition name="/media1" size="200G" usage="5%" />
                    <partition name="/media2" size="200G" usage="50%" />
                    </partitions>
                    </storageUsageInfo>
                

Note	The number of media partitions directly corresponds to the number of configured media disks. If you configure two media disks, you see two media partitions: /media1 and /media2.

The disk use monitoring category charts the percentage of disk use for the common and media partitions. It also displays the percentage of disk use for each partition (Active, Boot, Common, Inactive, Swap, Shared Memory, Spare) in each host. The Log Partition Monitoring Tool is installed automatically with the system and starts automatically after the system installation process is complete.

Note	If more than one logical disk drive is available in your system, the Cisco Unified Real Time Monitoring Tool (Unified RTMT) can monitor the disk use for the additional partition in the Disk Usage window.

Unified RTMT displays all partitions in MediaSense and in the Unified Communications OS. Depending on the number of disks installed, the corresponding number of media partitions are visible in the Disk Usage window. If you do not install any media partitions, only Partition Usage (common media) is visible.

Caution

The MediaSense SM agent must be running to view media disk use information in both the Disk Usage window and the Performance window in Unified RTMT.

While real-time media partition use is visible in the Disk Usage window, historical partition use details are visible as performance counters in the Performance window.

The MediaSense File Details screen displays information about individual media files in two tables. The top table displays details at the cluster level. The bottom table displays details at the node level.

The state values in both tables appear to be the same. Possible states in both tables include Processing, Ready, Deleting, and Error. However, these state values mean different things in each table. In the top table, states that are reported are aggregate values that reflect all nodes in the cluster. For example, as long as at least one node is processing a media file, the cluster state value is reported as Processing. The cluster state does not change to Ready until the media file is ready on all nodes in the cluster.

In the bottom table, state values are reported at the node level. The states, Processing, Ready, Deleting, and Error, are shown for the uploaded media file as it is on each separate node in the cluster. Media files can reflect different states on different nodes at the same time. For example, a media file might be shown as Processing on the secondary node and shown as Ready on an expansion node at the same time.

Trace flag information is stored in the configuration database.

Log Levels identify the MediaSense message level (info and debug) to be generated for each service. The currently enabled log levels for each service component are identified by a radio button (Log Level column) in the Trace Configuration screen. The currently enabled trace flags are identified by a check mark (Enabled column) in the Trace Configuration screen.

Note	There is no log level or trace mask for the Perfmon agent network service.

Caution

Because the media service does not support dynamic trace-level change, you cannot create or view a trace file for this service. Trace flags for the media service are used only by TAC and are not available to end users.

MediaSense log information is provided in the following output files:

• ORASERVICE-oraservice.<yyyy-MM-dd>T<HH-mm-ss.SSS>.startup.log— Contains debug and info messages (see the MediaSense log levels table above for more information about debug and info message levels).

• Error-oraservice.<yyyy-MM-dd>T<HH-mm-ss.SSS>.startup.log— Contains only system conditions.

Each of these files has a default maximum file size of 50 MB. The log file size and the number of files are not configurable.

Each service component has different logical divisions with corresponding trace flags. To ensure that a minimum level of logging information is captured whenever an issue occurs, a specific set of trace flags is enabled by default when MediaSense is installed. For the trace flags to take effect, you must set the log level for the corresponding component to DEBUG. The log level for most components is set to DEBUG by default when the MediaSense system is installed.

You can enable the entire component or certain trace flags within each component. You can also set different log level values (info or debug) for different MediaSense services in the same cluster.

MediaSense serviceability administration lists each trace flag within its MediaSense service component.

Caution

You cannot create a trace file for the media service because this service does not support dynamic trace-level changes.

The list shows the components that have their required trace flags enabled by default:

• MediaSense API service

  • AMS system

  • Entering and exiting methods

  • SIP Adapter

• MediaSense call control service

  • DEBUG

• MediaSense configuration service

  • Configuration service data adapter

  • Configuration service core

  • Configuration service AXL interface

  • System

  • Configuration notification

• MediaSense serviceability administration

  • System activities

  • Configuration service interaction

  • System service interaction

  • Audit information

  • Clustering activities

  • Controller class activities

• MediaSense administration

  • Administration service core

  • DB access

  • General ORA administration user interface

  • Administration configuration update

  • Administration utilities

• MediaSense storage management agent

  • DEBUG

The trace file contains information about each service.

After configuring the information that you want to include in the trace files for each service, you can collect and view the trace files by using the Unified Communications Trace and Log Central option in the Unified Real-Time Monitoring Tool (Unified RTMT). Trace and Log Central is the Unified Communications component which manages and provides access to trace files. When the services start up (during the post-installation process), the trace and log files are visible in the RTMT Trace and Log Central section after you launch Unified RTMT.

See Cisco Unified Real-Time Monitoring Tool Administration Guide for detailed information.

The MediaSense server stores the trace files in a log folder within the folder in which you installed the MediaSense component. You can collect and view trace information using Unified RTMT.

Reactivating the media service, the call control service, or the database service results in the following consequences:

• In-progress recordings may fail to complete properly when outages occur in the media service, call control service or database service and end in an error state even after the service is reactivated. Recordings in all other states will be fine.

• You can record new calls only after the service is reactivated.

Note	Reactivate or restart call control, database, and media services during off-peak hours to ensure minimum disruption to recordings in progress.

The Unified RTMT tracks and displays current performance information and alerts for MediaSense. Unified RTMT is integrated with the MediaSense administration and serviceability software.

Unified RTMT enables you to monitor the performance of all servers in MediaSense clusters. You can also continuously monitor a set of preconfigured objects.

In addition, Unified RTMT:

• Sends pop-up or email alerts to system administrators when performance counter values exceed predefined thresholds.

• Saves and restores settings, such as counters being monitored, threshold settings, and alert notifications, so that you can customize troubleshooting tasks.

• Charts up to six Perfmon counter values so that you can compare them.

To support the Unified RTMT client, a number of services must be active and running on the MediaSense server. AMC service is one such service. It starts up automatically after the Unified RTMT installation and allows the Unified RTMT client to retrieve real-time information from the MediaSense server. The AMC service, the Alert Manager, and the collector service enable Unified RTMT to retrieve real-time information from the server or from all servers in the MediaSense cluster.

To view the state of the AMC service, navigate to Unified Communications Manager Administration on MediaSense server and choose System > Service Parameters. Then, choose the required server and select the Cisco AMC service. For more information about the AMC Service, see the Cisco Unified Real-Time Monitoring Tool Administration Guide.

Caution

If for any reason the primary MediaSense server shuts down or is in a failed state, the secondary MediaSense server continues to function in the normal state. If you launch the Unified RTMT client at this time, the MediaSense tab in the Alert Central window may remain blank and display Error polling alert \ status. AMC service is down. in the status pane. Similarly, the System Summary pane may display HTTP request failed. Web Server unreachable. for the same issue. To work around this issue, configure the secondary Cisco AMC Service in the primary Cisco MediaSense server.

Note	Be sure to make the following change in the primary Cisco MediaSense server first.

Navigate to Unified Communications Manager Administration (in the primary Cisco MediaSense server). Choose System > Service Parameters, then select the secondary MediaSense server from the drop-down list, and select Cisco AMC Service. In the resulting Service Parameter Configuration web page, select the secondary MediaSense server from the drop-down list next to the Failover Collector field. After you configure the AMC Service for the secondary MediaSense server, the secondary server takes over when the primary MediaSense server goes down, and Unified RTMT continues to display alert names under Alert Central.

Note	You can access Unified Communications Manager Administration on the MediaSense server by providing the following URL format in a browser window: http://<MediaSenseServer-ip-address>/ccmadmin.

The collect files tool allows you to specify the required MediaSense services and application in the Select MediaSense Services/Application tab, which is part of the collect files wizard. After you specify the required MediaSense services, continue to proceed as you would for the System Service/Application. You can collect trace files that contain search criteria that you specify and save the trace collection criteria for later use.

Unified Serviceability stores the logs for the version of application that you are logged in to in the active partition and stores the logs for the other version (if installed) in the inactive folder.