2 Introduction to Oracle Service Bus Administration

This chapter gives an overview of Oracle Fusion Middleware, Oracle Service Bus, and the types of administration tasks you perform from Oracle Enterprise Manager Fusion Middleware Control and from the Oracle Service Bus Console.

This chapter includes the following topics:

2.1 Oracle Fusion Middleware Overview

Oracle Fusion Middleware is a collection of standards-based software products that spans a range of tools and services: from Java EE and developer tools, to integration services, business intelligence, and collaboration.

Oracle Fusion Middleware offers complete support for development, deployment, and management of applications. Oracle Fusion Middleware components are monitored at runtime using Oracle Enterprise Manager Fusion Middleware Control Console.

2.2 Oracle Service Bus Overview

Oracle Service Bus is a component of Oracle Fusion Middleware that provides standards-based integration for high-volume SOA environments.

Service Bus is a core component in Oracle SOA Suite, acting as a back-bone for SOA messaging. Service Bus connects, mediates, and manages interactions between heterogeneous services, legacy applications, packaged applications, and multiple enterprise service bus (ESB) instances across an enterprise-wide service network. Service Bus adheres to the SOA principles of building coarse-grained, loosely coupled, and standards-based services, creating a neutral container in which business functions can connect service consumers and back-end business services, regardless of underlying infrastructure.

2.2.1 Introduction to Service Monitoring and Management

Service Bus includes a powerful set of runtime tools for monitoring, alerting, reporting, configuration, and management. The Service Bus monitoring framework provides access to server statistics, such as the number of messages that were processed successfully or that failed, the average execution time of message processing, the number of errors and alerts generated, and the average response time. Using Fusion Middleware Control, you can view monitoring statistics for the period of the current aggregation interval or for the period since you last reset statistics for this service or since you last reset statistics for all services. Using the public APIs you can access only the statistics since the last reset. Administration Consoles

Service Bus is fully integrated with Fusion Middleware Control for SOA-wide management. Most monitoring and management tasks for Service Bus services are performed using Fusion Middleware Control, though certain administration tasks require the Oracle Service Bus Console.

In Fusion Middleware Control, Service Bus provides operational functions and settings that allow you to monitor SLA alerts, pipeline alerts, logs, reports, and policy usage by providing a cluster-wide view of service status and statistics. The framework monitors business services, proxy services, pipelines, and split-joins, including response times, message counts, error counts, and security policy usage and violations. Using Fusion Middleware Control, you can also turn tracing on and off, enable and disable services, update logging and alert levels, and recover from resequencing faults. Service-level flags and global flags help control monitoring, alerting, reporting, and logging.

The Oracle Service Bus Console provides configuration tools for creating service level agreement alerts, pipeline alerts, messaging reporting actions, alert destinations, and throttling groups for business service endpoints. Using the console, you can also update environmental values, either individually or in bulk. Auditing Capabilities

Service Bus provides the following capabilities for auditing and monitoring services:

  • Gathers statistics about message invocations, errors, performance characteristics, messages passed and SLA violations.

  • Sends SLA-based alerts as SNMP traps, enabling integration with third-party ESM solutions.

  • Logs selected parts of messages for both systems operations and business auditing purposes.

  • Provides search capabilities by extracting key information from a message and use as it as a search index.

2.2.2 Introduction to the Oracle Service Bus Monitoring Framework

The monitoring framework monitors the operational resources, servers, and service level agreements (SLAs) for Service Bus.Figure 2-1 illustrates of the architecture of the monitoring framework.

Figure 2-1 Monitoring Framework in Oracle Service Bus

Description of Figure 2-1 follows
Description of "Figure 2-1 Monitoring Framework in Oracle Service Bus"

The Service Bus monitoring architecture consists of the following components:

  • Collector: Each Managed Server in a cluster hosts a Collector. The Collector collects statistics on operational resources at regular intervals of time, which is managed in a RMI object. It also keeps a history within the aggregation interval for the collected statistics.

    The Service Bus runtime invokes a collector at the beginning of each minute. At every system-defined checkpoint interval, it stores a snapshot of current statistics into a persistent store for recovery purposes and sends the information to the Aggregator in raw format, as raw format is optimized for fast collection and small footprint.


    An operational resource is defined as the unit for which statistical information can be collected by the monitoring subsystem. Operational resources include proxy services, business services, pipeline components, split-join components, service-level resources such as Web Services Definition Language (WSDL) operations, and endpoint URIs.

  • Aggregator: The Aggregator is present only on one Managed Server. The server on which this resides is selected arbitrarily when you generate a domain using the configuration wizard. It aggregates all the statistics that are collected from all Managed Servers across all Managed Servers in a cluster.

    The Service Bus runtime invokes the aggregator twenty-five seconds past each minute, to enable collectors to collect data and send it to the aggregator. At system-defined checkpoint intervals, each Managed Server in the cluster sends a snapshot of its contributions to the Aggregator. Data structures in aggregator are optimized for aggregating and retrieving data.

  • Retriever: The Retriever retrieves the statistics that are stored in the memory. This is present only in the Managed Server that contains the aggregator.

  • Alert Manager: The alert manager fires alerts based on the aggregated statistics. This is present only in the Managed Server that contains the aggregator.

The Collector collects the updated statistics from the Service Bus runtime and sends it to the Aggregator, which then aggregates the statistics over the aggregation interval. Those statistics then are pushed to the Alert Manager, which triggers alerts based on the statistics. The aggregated statistics are also stored and can be retrieved by the Retriever.

2.2.3 Accessing Statistics Using the JMX API

You can access the statistical information for a service through Fusion Middleware Control or directly by using the Java Management Extensions (JMX) monitoring APIs. Using the JMX monitoring APIs only allows access to the running count statistics. The JMX monitoring APIs provide efficient lower-level support for bulk operations. For more information about using JMX monitoring APIs, see JMX Monitoring API.

2.2.4 Accessing Statistics in a Cluster

In a clustered environment, all the statistics collected on the Managed Servers are pushed to the aggregator. Statistics are available at individual Managed Server level and the cluster level. On the Service Health page, you can choose Cluster or the name of a Managed Server from the Server list to view statistics for the cluster or the individual Managed Server.

2.3 Oracle Service Bus Runtime Monitoring

Service Bus lets you monitor and collect runtime information required for system operations by aggregating runtime statistics.

Administrators can view the statistics in real-time to monitor system operational health and to flag problems in messaging services. This allows quick isolation and diagnosis of problems as they occur. In addition, you can configure service level agreement (SLA) alerts, pipeline alerts, and message reporting to trigger alerts or event logs under the conditions you define. Fusion Middleware Control provides configuration tools for loggers and log levels, as well as the ability to view log entries directly in the console. The following sections describe the monitoring features of Service Bus.

2.3.1 Service Health Monitoring

Information about system operational health can be viewed at the server, project, and individual service level. The Service Bus domain and Service Bus Project Service Health pages display statistics aggregated for each service in either the domain or project. Individual service dashboards also display performance statistics at an operational level for more granular analysis. For pipelines and split-joins, performance statistics can be gathered for components in the message flow.

Statistics are collected for all Service Bus services. The monitoring system supports the following types of statistics:

  • Counter: A counter keeps track of the count of events in the runtime such as the number of messages received, errors generated, and failovers. This is scalar and takes on integral values.

  • Interval: An interval keeps track of the time elapsed between two well-defined events. This tracks the total, average, minimum, and maximum of such events in the runtime. This takes on integral and non-integral values.

  • Status Type: A status statistic keeps track of a service's status. Using this you can keep track of the initial status and the current status of the object.

For more information about different types of statistics collected, see Using the JMX Monitoring API. For information about monitoring service health, see Monitoring Oracle Service Bus Service Health. Metric Aggregation

The displayed health statistics are based on an asynchronous aggregation of data collected during system operation. In a production cluster domain, the data aggregator runs as a singleton service on one of the Managed Servers in the cluster. Server-specific data aggregation is performed on each of the Managed Servers in the domain. The aggregator is responsible for the collection and aggregation of data from all the Managed Servers at regular, configurable intervals. These metrics are aggregated across the cluster for the configured aggregation interval and displayed on the Service Bus pages in Fusion Middleware Control. Monitoring a Service that was Renamed or Moved

When you rename or move a service, all the monitoring statistics that have been collected are lost. All current aggregation interval and cumulative metrics are reset and the service is monitored from start. If the endpoint URI for a service was marked offline before it was renamed or moved, the URIs are marked online again and the status of the URI is displayed as online after you complete renaming or moving the service.

2.3.2 SLA and Pipeline Alert Monitoring

Service level agreement (SLA) alerts and pipeline alerts are configured for specific services in order to generate information about how messages are being processed through those services. SLA alerts are raised to indicate potential violations of service level agreements. The following are some common uses for SLA alerts:

  • Monitoring and generating e-mail notification of WS-Security errors.

  • Monitoring the number of messages passing through a particular pipeline.

  • Detecting the violation of service level agreements with third-party products.

  • Detecting a non-responsive endpoint.

Pipeline alerts are defined directly in a pipeline using an alert action. Pipeline alerts are generally used to detect errors in a message flow or to indicate a business event. For more information about creating and monitoring alerts, see Monitoring Oracle Service Bus Alerts. SLA Alerts Overview

Service Level Agreements (SLAs) define the precise level of service expected from the services in Service Bus. SLA alerts are automated responses to violations of SLA rules and conditions. Service Bus runs SLA rules against aggregated monitoring statistics and raises alerts when rule violations are found. After monitoring those alerts, you can enable or disable services as needed. Administrators can set service level agreements (SLAs) on the following conditions:

  • Message processing times.

  • Message processing volume.

  • Number of errors, security violations, and validation errors.

  • Failure and success ratios.

  • For business services only, endpoint URI status.

The Service Bus Dashboard and Alert History page in Fusion Middleware Control both display SLA alerts. When an SLA alert is raised, Service Bus also sends a notification to the alert destinations defined for that alert rule. In order for Service Bus to raise SLA alerts, SLA alerting must be enabled at both the service level and the global level.

The Oracle Service Bus Console provides editors to create SLA alert rules and to define the conditions under which an alert is raised. Alert rules specify unacceptable service performance according to your business and performance requirements. Each alert rule allows you to specify the aggregation interval for that rule. This interval is not affected by the aggregation interval set for the service. Pipeline Alerts Overview

In addition to SLA alerts, Service Bus also provides alert actions that can be configured within the message flow of a pipeline. Pipeline alerts are generally used for business purposes such as recording the number of messages that flow through the message pipeline, tracking occurrences of certain business events, or reporting errors (though not for the health of the system). Pipeline alert actions generate alerts based on the message context in a pipeline, and can be configured to include an alert name, description (which can include message elements), alert destination, and alert severity.

Service Bus generates a pipeline alert when it reaches an alert reporting action in a pipeline and the conditions defined for the action are met. You define the conditions under which a pipeline alert is triggered using the conditional constructs available in the pipeline editor, such as an XQuery expression or an if-then-else construct. When a pipeline alert is raised, Service Bus sends a notification to the alert destinations defined for that alert action.

The Service Bus Dashboard and Alert History page in Fusion Middleware Control both display pipeline alerts. You define pipeline alerts using the editors in either Oracle Service Bus Console or JDeveloper.

2.3.3 Resequencing Group Monitoring

Service Bus pipelines can be configured to use a resequencer, which re-orders messages that arrive in a random order into a new order based on the type of resequencer used. The Resequence Messages page displays information about the state of resequenced messages so you can monitor and manage the status of resequencers in the runtime. You can search for resequencing groups to view based on the group name, the location of the pipeline, or the status of the resequencing group. If you click a group ID in the search results, additional information about the group appears in the Resequencing Group dialog.

The information displayed in the group dialog depends on the status of the group. If the group is faulted or timed out, you can recover the faulted message or skip to the next available message. The Resequencing Group dialog provides the following information about a group:

  • Whether the group is timed-out or faulted.

  • The blocking message in the group, if any.

  • The next message to be processed after the group is unlocked.

  • The time after which the processing of the messages in the group stopped.

  • The instruction text to unlock the group.

When processing of messages in a group is suspended due to a fault or a timeout, the dialog provides information about the suspended group. For more information about monitoring resequenced messages, see Monitoring Resequencing Groups.

2.3.4 Log File Monitoring

Service Bus components generate log files containing messages that record all types of events, including startup and shutdown information, errors, warning messages, access information on HTTP requests, and additional information. Service Bus uses Oracle Diagnostic Logging (ODL) to define the standard format, content, and file-handling of diagnostic log files. In addition to logging standard actions, Service Bus adds entries to the diagnostic log file for any pipelines and split-joins that have log actions and that have logging enabled. Administrators can view this information on the Log Messages page of Fusion Middleware Control. Fusion Middleware Control also provides configuration tools, where you can specify the loggers to use and the log level for each logger.

For more information about logging, see Configuring and Monitoring Log Files.

2.3.5 Message Reporting

Reporting actions configured in a pipeline let you report on message data as messages pass through the pipeline. A reporting action can be placed at any point within a request or response pipeline or an error pipeline stage, and you can specify the information about each message that is written in each report entry generated by the action.You can use reporting actions to filter message information as it flows through the pipeline. The data captured by the report action can then be monitored in Fusion Middleware Control or accessed by a reporting provider. Reporting actions can help you determine whether there is a problem with a message pre- or post-transformation, during routing, and so on.

The Message Reports page in Fusion Middleware Control displays information from the reporting data store, including summary information. You can expand summary information to view detailed information about specific messages. Service Bus provides additional tools for message reporting, including a built-in JMS reporting provider and a Java API you can use to create your own reporting provider. The JMS reporting provider picks up reported data and stores it in a message reporting database that acts as the reporting data store.

Use monitoring, SLA alerts, and reporting features in combination to manage the health and availability of the service infrastructure in real time, measure SLA compliance, and report this information efficiently and effectively.

For more information about message reporting, see Configuring Reporting for Messages and Alerts.

2.4 Oracle Service Bus Runtime Management

In addition to monitoring Service Bus services in the runtime, you can also manage running services. Management tasks include customizing environment values, configuring operational settings, managing endpoint URIs for business services, and importing and exporting services.

The following sections describe the management tasks you can perform using Fusion Middleware Control.

2.4.1 Environment Customization

Service Bus uses environment variables and values to represent properties in the Service Bus configuration that are likely to change when you move your configuration from one domain to another (for example, from test to production). By representing these properties as environment values, you can modify things like server names, port numbers, directory names, and retry configurations without having to change the value in each Service Bus resource individually. A good example is the URL of a proxy service, which changes depending on the physical location of the domain. Environment values can be found in alert destinations, proxy services, business services, SMTP server and JNDI provider resources, UDDI registry entries, and transports.

Service Bus provides two methods to update environment values in a domain. You can either use the Find and Replace dialog on the Oracle Service Bus Console to update environment values or you can create and execute a configuration file that defines the values for each environment value. Using Find and Replace, you can replace entire environment values or just substrings of the values, which is useful for making minor or small changes. Configuration files let you modify all the environment variables directly, find and replace strings or substrings, update operational settings at the global and service levels, and update references between resources.

For more information, see Customizing Oracle Service Bus Environments.

2.4.2 Runtime Configuration

Operational settings provide control over the state of a service and how it can be monitored in Fusion Middleware Control. Configure operational settings to enable or disable the following features at the service or global level. The operational settings at the service level are overridden by those set at the global level.

  • A service's state

  • Monitoring, logging, and reporting

  • Aggregation interval

  • SLA and pipeline alerts

  • Execution and message tracing

  • Non-responsive endpoints

  • Throttling

  • Result caching

  • Resequencer processing

In addition, you can restrict concurrent processing of messages, set the maximum number of messages in the throttling queue, and set the maximum length of time a message can stay in the throttling queue.

2.4.3 Business Service Endpoint Management

In the runtime, you can monitor metrics for each business service endpoint URI to ensure they are all performing as expected. When you notice issues with an endpoint URI, Service Bus lets you mark a URI endpoint as offline to avoid repeated attempts at accessing the endpoint URI. You can alternatively configure the business service to automatically mark non-responsive URIs as offline.

Configuring a business service to mark non-responsive URIs offline prevents a business service from repeatedly attempting to access a non-responsive URI and therefore avoids the communication errors caused by trying to access a non-responsive URI. Once an endpoint URI is marked offline, Service Bus can bring it back online after a time period you specify, or keep it offline until you change the status manually.

For more information about managing endpoint URIs, see Monitoring and Managing Endpoint URIs for Business Services.

2.4.4 Tuning Performance with Endpoint Throttling

Service Bus provides the ability to regulate message traffic to a business service or group of business services, giving you control over the load placed on a business service. Throttling helps improve performance and stability by preventing message overload on high-traffic business services. Service Bus uses a throttling queue in which messages are stored once a business service is processing the maximum number of concurrent messages allowed. You configure the number of messages that can be concurrently processed, the maximum number of messages in the queue, and the length of time a message can stay in the queue. Messages are processed from the queue in order of priority, which can be assigned using routing options.

You can apply throttling to individual business services or to groups of business services by assigning them to a throttling group. Throttling groups are useful when multiple business services send requests to the same server. By setting up throttling, you can control the flow of messages to that server, ensuring the message volume does not exceed the server's capacity. The configuration of the group applies to all services assigned to the group.

For more information, see Configuring Business Services for Message Throttling.

2.4.5 Importing and Exporting Resources

The import and export features of Service Bus let you share and update projects and resources between different runtime environments. In Fusion Middleware Control, you can import and export full configuration JAR files or just a subset of the resources included in a JAR file. A configuration JAR file contains projects or resources that were previously exported from a Service Bus instance. Importing configuration files can update or delete existing resources and add new resources to the configuration.

When you import Service Bus resources, you can also import a configuration file that defines environment values specific to the domain in which you are working, as described in Environment Customization.

For more information, see Importing and Exporting Oracle Service Bus Resources.

2.4.6 Diagnostics

Service Bus leverages Oracle WebLogic Server and Oracle Fusion Middleware diagnostic and reporting tools to help you detect, diagnose, and resolve issues in the runtime. WebLogic Diagnostic Framework (WLDF) captures diagnostic data, and can monitor logs and send notifications when certain conditions are met. The Oracle Fusion Middleware Diagnostic Framework targets critical errors, such as those caused by code bugs, data corruption, deadlocked threads, and inconsistent states. The framework captures dumps of relevant diagnostics, which you can then view and analyze.

The Automatic Diagnostic Repository (ADR) stores all diagnostic data, such as traces and dumps, for Oracle Fusion Middleware components. The Oracle Dynamic Monitoring Service (DMS) provide metrics, trace events, and system performance information to administration tools.

For information about how these tools work together to provide diagnostic information, see Using the Diagnostic Frameworks to Diagnose Problems.

2.5 Oracle Service Bus Runtime Security

Security administration in the runtime includes monitoring policies, policy usage, and policy violations for services.

In Fusion Middleware Control, you can also define administrative security by defining authentication and authorization for Service Bus users and service clients.

2.5.1 Working with Security Policies

Service Bus uses standard Fusion Middleware Control features to monitor and manage the security policies attached to running business and proxy services. Policies provide a framework to manage and secure those services. Policy monitoring and management include the following tasks:

  • Attaching and detaching policies from services.

  • Updating policy overrides.

  • Attaching policy sets globally.

  • Monitoring policy usage.

  • Monitoring policy violations.

You can configure policies for individual services in both the Oracle Service Bus Console and in Fusion Middleware Control. For more information, see Monitoring and Managing Security Policies.

2.5.2 Defining Security Administration

For authentication and authorization, Service Bus uses Oracle Application Development Framework (ADF) security, which is built on Oracle Platform Security Services (OPSS). Service Bus leverages the security features in Fusion Middleware Control to create users, roles, and groups, and to assign security permissions. Service Bus provides a set of default application roles that you can assign to the users you create in order to give them a standard set of access permission to Service Bus features, such as creating specific resources, monitoring the runtime, deploying resources, and so on. Inbound transport-level security and message-level security also use Service Bus user, group, and role data to authenticate inbound client requests based on conditions you define.

For more information, see Defining Access Security for Oracle Service Bus.

2.6 Introduction to Aggregation Intervals

In Service Bus, the monitoring subsystem collects statistics over an aggregation interval, which is the time period over which statistical data is collected and displayed in Fusion Middleware Control.

Statistics that are not based on an aggregation interval are meaningless. In addition to statistics collected over a well-defined aggregation interval you can also collect cumulative statistics.

2.6.1 Refresh Rate of Monitored Data

The aggregation interval is a moving window, which always refers to an interval of time in minutes, hours or days. It does not move with infinite granularity or precision, but at regular intervals of time called the sampling interval. This enables an aggregation interval to move smoothly and produce accurate statistics.

Figure 2-2 Illustration of Aggregation Interval and Sampling Interval

Description of Figure 2-2 follows
Description of "Figure 2-2 Illustration of Aggregation Interval and Sampling Interval"

Figure 2-2 is an illustration of the of aggregation interval. For example, aggregation interval A1 is set at five minutes and aggregation interval A2 is set at ten minutes. The runtime collects statistics for the service with aggregation interval A1 for every minute (S1). It aggregates the statistics at the end of the aggregation interval.

Similarly for aggregation interval A2 it collects statistics for every five minutes (S2). Intervals S1 and S2 are called sampling intervals, described below.

2.6.2 Aggregation Interval Properties

The aggregation interval has the following properties:

  • You can track statistics for a service over only one aggregation interval.

  • You cannot set an arbitrary value for an aggregation interval. You must choose from one of the values in the list.

  • You can set the aggregation interval for services and for alert rules.

  • You can only specify an aggregation interval less than or equal to seven days.

When you modify the aggregation interval of a service, the statistics of the service in the current aggregation interval are reset. However, the status of the endpoint URI for the service remains unaffected by the change in the aggregation interval. A running count metrics of the service is not reset when you modify the aggregation interval.

2.6.3 Resetting the Statistics

When you reset statistics for a service in the Oracle Service Bus Console, all the statistics collected for the service since the last reset are lost. You cannot undo this action. The status of endpoint URIs is not reset when you reset statistics.

2.7 Server Monitoring and Management

Fusion Middleware Control displays information about the state of the Service Bus server so you can monitor the health and performance of your Service Bus environment and deployed applications.

The console displays information about the state of domains, clusters, administration and managed servers, system components, and applications. You can also start and stop the server from Fusion Middleware Control. For more information, see "Monitoring Oracle Fusion Middleware" in Administering Oracle Fusion Middleware.

2.8 Oracle Service Bus and Oracle Enterprise Scheduler

Using Oracle Enterprise Scheduler, you can define, schedule, and run jobs, which are units of work done on an application's behalf. When Oracle Enterprise Scheduler is installed with Service Bus, you can create jobs to perform tasks and define a schedule that indicates how often to trigger the scheduler.

For example, you can schedule a Service Bus proxy service with a web services interface using Oracle Enterprise Scheduler. In order to use Oracle Enterprise Schedule with Service Bus, the following templates must be deployed on the Service Bus domain:

  • Oracle Enterprise Scheduler Service Basic

  • Oracle Enterprise Manager Plugin for ESS

You can define jobs in Fusion Middleware Control. For information and instructions, see the following documentation:


When you create a job definition or schedule for a Service Bus proxy service, you must specify /oracle/apps/ess/custom/osb for the Package field.