Configuring and Using the WebLogic Diagnostic Framework
|
 |
 |
|
|
 |
 |
Terminology
Key terms that you will encounter throughout the diagnostic and monitoring documentation include the following:
Any resulting physical entity, or data, generated and persisted to disk by the WebLogic Diagnostic Framework that can be used later for diagnostic analysis. For example, the diagnostic image file that is created when the server fails is an artifact. The diagnostic image artifact is provided to support personnel for analysis to determine why the server failed. The WebLogic Diagnostic Framework produces a number of different artifacts.
If diagnostic monitoring is enabled, a diagnostic context is created, initialized, and populated by WebLogic Server when a request enters the system. Upon request entry, WebLogic Server determines whether a diagnostic context is included in the request. If so, the request is propagated with the provided context. If not, WebLogic Server creates a new context with a specific name (
weblogic.management.DiagnosticContext). The contextual data for the diagnostic context is stored in the diagnostic context payload. Thus, within the scope of a request execution, existence of the diagnostic context is guaranteed.The actual contextual data for the diagnostic context is stored in the Context Payload. See also context creation, diagnostic context, request dyeing.
Data stores are a collection of data, or records, represented in a tabular format. Each record in the table represents a datum. Columns in the table describe various characteristics of the datum. Different data stores may have different columns; however, most data stores have some shared columns, such as the time when the data item was collected.
In WebLogic Server, information captured by WebLogic Diagnostic Framework is segregated into logical data stores, separated by the types of diagnostic data. For example, Server logs, HTTP logs, and harvested metrics are captured in separate data stores.
Business logic or diagnostic code that is executed when a joinpoint defined by a pointcut is reached. Diagnostic actions, which are associated with specific pointcuts, specify the code to execute at a joinpoint. Put another way, a pointcut declares the location and a diagnostic action declares what is to be done at the locations identified by the pointcut.
Diagnostic actions provide visibility into a running server and applications. Diagnostic actions specify the diagnostic activity that is to take place at locations, or pointcuts, defined by the monitor in which it is implemented. Without a defined action, a diagnostic monitor is useless.
Depending on the functionality of a diagnostic action, it may need a certain environment to do its job. Such an environment must be provided by the monitor to which the diagnostic action is attached; therefore, diagnostic actions can be used only with compatible monitors. Hence, diagnostic actions are classified by type so that their compatibility with monitors can be determined.
To facilitate the implementation of useful diagnostic monitors, a library of suitable diagnostic actions is provided with the WebLogic Server product.
The WebLogic Diagnostic Framework adds contextual information to all requests when they enter the system. You can use this contextual information, referred to as the diagnostic context, to reconstruct transactional events, as well correlate events based on the timing of the occurrence or logical relationships. Using diagnostic context you can reconstruct or piece together a thread of execution from request to response.
Various diagnostic components, for example, the logging services and diagnostic monitors, use the diagnostic context to tag generated data events. Using the tags, the diagnostic data can be collated, filtered and correlated by the WebLogic Diagnostic Framework and third-party tools.
The diagnostic context also makes it possible to generate diagnostic information only when contextual information in the diagnostic context satisfies certain criteria. This capability enables you to keep the volume of generated information to manageable levels and keep the overhead of generating such information relatively low. See also context creation, context payload, request dyeing.
An artifact containing key state from an instance of a server that is meant to serve as a server-level state dump for the purposes of diagnosing significant failures. This artifact can be used to diagnose and analyze problems even after the server has cycled. Each diagnostic image contains a summary artifact that includes, at a minimum, the following elements:
A diagnostic module is the definition the configuration settings that are to applied to the WebLogic Diagnostic Framework. The configuration settings determine what data is to be collected and processed, how the data is to be analyzed and archived, what notifications and alarms are to be fired, and the operating parameters of the Diagnostic Image Capture component. Once a diagnostic module has been defined, or configured, it can be distributed to a running server where the data is collected.
Typically, diagnostic data is collected from a number of sources depending on the complexity of the system being monitored. Rather than collect data from all sources all the time—an approach that could result in massive amounts of data being collected and require significant system resources to collect and many person hours to evaluate—the ability to define a subset of sources to be monitored saves system and human resources. Further, the ability to define diagnostic modules enables the users to design the data collected to meet the needs of both the system and the environment in which it is being used. Clearly, the ability to define diagnostic modules can have a very positive effect on maintainability and productivity.
In WebLogic Server, a single diagnostic module can be defined and then targeted to one or more individual servers or clusters of servers. Only one diagnostic module can be targeted to a single server at a time.
A diagnostic monitor is a unit of diagnostic code that defines 1) the locations in a program where the diagnostic code will be added and 2) the diagnostic actions that will be executed at those locations.
WebLogic Server provides a library of useful diagnostic monitors. Users can integrate these monitors into server and application classes. Once integrated, the monitors take effect at server startup for server classes and application deployment and redeployment for application classes.
The action that occurs as a result of the successful evaluation of a watch rule. The WebLogic Diagnostic Framework supports four types of diagnostic notifications: Java Management Extensions (JMX), Java Message Service (JMS), Simple Mail Transfer Protocol (SMTP), and Simple Network Management Protocol (SNMP).
The process of looking at the dye mask and making the decision as to whether or not a diagnostic monitor should execute an action so as to generate a data event. Dye filtering is dependent upon dye masks. You must define dye masks in order for dye filtering to take place. See also dye mask, request dyeing.
The entity that contains a predefined set of conditions that are used by dye filtering to determine whether or not a data event should be generated. You use system resource descriptors to configure the dye masks. See also dye filtering, request dyeing.
A harvestable entity is any entity that is available for data consumption via the Harvester. Once an entity is identified as a harvestable resource, the Harvester can engage the entity in the data collection process.
Harvestable entities provide access to the following information: harvestable attributes, values of harvestable attributes, meta-data for harvestable attributes, and the name of the harvestable entity. See also harvestable data, harvested data, Harvester's configuration data set, MBean type discovery.
Harvestable data (types, instances, attributes) is the set of data that potentially could be harvested when and if it is configured for harvesting. Therefore, the set of harvestable data exists independent of what data is configured for harvesting and of what data samples are taken.
The
WLDFHarvesterRuntimeMBeanprovides the set of harvestable data for users. For a description of the information about harvestable data provided by this MBean, see the description of theweblogic.management.runtime.WLDFHarvesterRuntimeMBeanin the WebLogic Server MBean Reference.The WebLogic Diagnostic Framework only makes MBeans available as harvestable. In order for an MBean to be harvestable, it must be registered in the local WebLogic Server runtime MBean server. See also harvestable entities, harvested data, Harvester's configuration data set, MBean type discovery.
A type, instance, or attribute is called harvested data if that data is currently being harvested. To meet these criteria the data must: 1) be configured to be harvested, 2) if applicable, it must have been discovered, and 3) it must not throw exceptions while being harvested.
When the configuration is loaded, the set of harvested items is the same as the set of configured items for WebLogic Server MBean types. Configured customer data is added as it is discovered. So the list of harvested instances for both WebLogic Server and customer types can grow as MBeans are added. And for customer data, the introduction of new instances can also cause the list of harvested types and attributes to grow. However, if the Harvester discovers that certain items cannot be harvested, they are removed, thereby, causing the list to shrink. If the Harvester configuration changes, the set of harvested data is recalculated.
The
WLDFHarvesterRuntimeMBeanprovides the set of harvested data for users. The information returned by this MBean should be considered a snapshot of a potentially changing state. For a description of the information about harvested data provided by the this MBean, see the description of theweblogic.management.runtime.WLDFHarvesterRuntimeMBeanin WebLogic Server MBean Reference. See also harvestable entities, harvestable data, Harvester's configuration data set, MBean type discovery.The set of data to be harvested as defined by the Harvester's configuration. The configured data set can contain items that are not harvestable and items that are not currently being harvested.
The set of harvestable MBeans comprises the set of harvestable instances. This set is dynamic in that it grows and shrinks as MBeans are registered with and removed from the MBean server. Since the set is dynamic, some data may be legitimately harvestable one moment and not harvestable the next. The dynamics of the set can also create situations where the configuration is legitimate, but the data is not available to verify the configuration. The Harvester's validation is designed to be tolerant of these dynamic situations.
The Administration Console assists you in the configuration process by prompting you with lists of harvestable data that can be configured—such as harvestable types, instances of harvestable types, and harvestable attributes of harvestable types. The information listed is always complete for WebLogic Server MBeans data, but is discovered dynamically for custom MBeans. See also harvestable entities, harvestable data, harvested data, Harvester's configuration data set.
A well defined point in the program flow where diagnostic code can be added. The Instrumentation component allows identification of such diagnostic joinpoints with an expression in a generic manner.
A well defined set of joinpoints, typically identified by some generic expression. Pointcuts identify joinpoints, which are well-defined points in the flow of execution, such as a method call or data variable access. The Instrumentation component provides a mechanism to allow execution of specific diagnostic code at such pointcuts. The Instrumentation component adds such diagnostic code to the server and application code.
A Java object that provides a management interface for an underlying resource. An MBean is part of Java Management Extensions (JMX).
In the WebLogic Diagnostic Framework, MBean classes are used to configure the service and to monitor its runtime state. MBeans are registered with the MBean server that runs inside WebLogic Server. MBeans are implemented as standard MBeans which means that each class implements its own MBean interface.
For WebLogic Server entities, the set of harvestable types is known at system startup, but not the complete set of harvestable instances. For customer defined MBeans, however, the set of types can grow dynamically, as more MBeans appear at runtime. The process of detecting a new type based on the registration of a new MBean is called type discovery. MBean type discovery is only applicable to customer MBeans.
The set of harvestable attributes for a type (and its instances) is defined by the meta-data for the type. Since the WebLogic Server model is MBeans, the meta-data is provided through
MBeanInfos. Since WebLogic type information is always available, the set of harvestable attributes for WebLogic Server types (and existing and potential instances) is always available as well. However, for customer types, knowledge of the set of harvestable attributes is dependent on the existence of the type. And, the type does not exist until at least one instance is created. So the list of harvestable attributes on a user defined type is not known until at least one instance of the type is registered.It is important to be aware of latencies in the availability of information for custom MBeans. Due to latencies, the Administration Console cannot provide complete lists of all harvestable data in its user selection lists for configuring the harvester. The set of harvestable data for WebLogic Server entities is always complete, but the set of harvestable data for customer entities (and even the set of entities itself) may not be complete.
Meta-data is information that describes the information the WebLogic Diagnostic Framework collects. Because the service collects diagnostic information from different sources, the consumers of this information need to know what diagnostic information is collected and available. To satisfy this need, the Data Accessor provides functionality to programmatically obtain this meta-data. The meta-data made available by means of the Data Accessor includes: 1) a list of supported data store types, for example,
SERVER_LOG,HTTP_LOG,HARVESTED_DATA, 2) a list of available data stores, and 3) the layout of each data store, that is, information about columns in the data store.Monitoring system operation and diagnosing problems depends on having data from running systems. Metrics are measurements of system performance. From these measurements, support personnel can determine whether the system is in good working order or a problem is developing.
In general, metrics are exposed to the WebLogic Diagnostic Framework as attributes on qualified MBeans. In WebLogic Server, metrics include performance measurements for the operating system, the virtual machine, the system runtime, and applications running on the server.
Requests can be dyed, or specially marked, to indicate that they are of special interest. For example, in a running system, it may be desirable to send a specially marked test request, which can be conditionally traced by the tracing monitors. This allows creation of highly focused diagnostic information without slowing down other requests.
Requests are typically marked when they enter the system by setting flags in the diagnostic context. The diagnostic context provides a number of flags, 64 in all, that can be independently set or reset.
Only dyes 56-63 are available for use by applications. All other dye flags are reserved for use by WebLogic Diagnostic Framework components and libraries.
The
DyeInjectionmonitor can turn on these flags when the request enters the system based on its configuration and request properties. Thereafter, other diagnostic monitors can make use of these flags (dyes) to conditionally execute certain actions. For example, a diagnostic monitor can be configured to perform its diagnostic action only if the request originated from a specific address. See also context creation, context payload, diagnostic context.Whenever a system fails, there is need to know its state when it failed. Therefore, a means of capturing system state upon failure is critical to failure diagnosis. A system image capture does just that. It creates, in essence, a diagnostic snapshot, or dump, from the system for the express purpose of diagnosing significant failures.
In WebLogic Server, you can configure the WebLogic Diagnostic Framework provides the First-Failure Notification feature to trigger system image captures automatically when the server experiences an abnormal shutdown. You can also implement watches to automatically trigger diagnostic image captures when significant failures occur and you can manually initiate diagnostic image captures on demand.
A watch encapsulates all of the information for a watch rule. This includes the watch rule expression, the alarm settings for the watch, and the various notification handlers that will be fired once a watch rule expression evaluates to true.
The time it takes while loading server and application classes to insert the diagnostic byte codes into server and application classes at well-defined locations. The diagnostic byte codes enable the WebLogic Diagnostic Framework to take diagnostic actions. Weaving time affects both the load time for server-level instrumented classes and application deployment time for application-level classes.
