The WebLogic Monitoring Exporter is a Prometheus-compatible exporter of metrics from WebLogic Server (WLS) instances, which it obtains by using the WLS RESTful Management API, available in version 12.2.1 or later. Metrics are selected using a YAML configuration file.
The exporter is available in two forms:
A web application that you deploy to the server from which metrics are to be extracted. You may include a configuration file directly in the WAR file, and you may temporarily modify the configuration in a running system by using a web form, either by selecting a replacement configuration or one to append to the current one, with the caveat that if both the original and appended configurations have filters, the update will be rejected. If a coordination configurator is running and configured, that temporary configuration will be sent to all servers configured to use it.
A separate process that is run alongside a server instance. You supply the configuration to such a process with a PUT command, as described below. WebLogic Server Kubernetes Operator versions 3.2 and later have special support for the exporter in this form. For more information, see Use the Monitoring Exporter with WebLogic Kubernetes Operator.
Here is an example yaml
file configuration:
query_sync:
url: http://coordinator:8999/
interval: 5
metricsNameSnakeCase: true
domainQualifier: true
restPort: 7001
queries:
- key: name
keyName: server
applicationRuntimes:
key: name
keyName: app
componentRuntimes:
type: WebAppComponentRuntime
prefix: webapp_config_
key: name
includedKeyValues: "abc_.*"
excludedKeyValues: "abc_12.*"
values: [deploymentState, contextRoot, sourceInfo, openSessionsHighCount]
stringValues:
status: [deployed, undeployed]
servlets:
prefix: weblogic_servlet_
key: servletName
values: invocationTotalCount
Note that there are two parts to the configuration. The optional top portion defines general processing rules.
Name | Description |
---|---|
query_sync |
Optional, used in the web application only. Configuration for a service which coordinates updates to the query configuration. |
query_sync.url |
The URL of the service. Required if this section is present. |
query_sync.interval |
The interval, in seconds, at which the service will be queried. Defaults to 10. |
metricsNameSnakeCase |
If true, metrics names will be converted to snake case. Defaults to false. |
domainQualifier |
If true, the domain name will be included as a qualifier for all metrics. Defaults to false. |
restPort |
Optional, used in the web application only. Overrides the port on which the exporter should contact the REST API. Needed if the exporter cannot find the REST API. The most common case is running on a system with the administration port enabled. In that case, you must specify the administration port in this field and access the exporter by using the SSL port. |
Note that if unable to contact the REST API using the inferred host and port, the exporter will try the local host name and, if the REST port is specified, the local port.
The query
field is more complex. Each query consists of a hierarchy of the MBeans, starting relative to ServerRuntimes
.
Within each section, there are a number of options:
Name | Description |
---|---|
key |
The name of the attribute to use as a key for qualifiers in the output. |
includedKeyValues |
An optional filter. If specified, only entries whose key value matches the specified regular expression will generate metrics. |
excludedKeyValues |
An optional filter. If specified, entries whose key value matches the specified regular expression will NOT generate metrics. |
keyName |
The name to use for the key in the qualifier; defaults to the name of the attribute. |
prefix |
A prefix to use for all the metrics gathered from the current level. |
values |
The attributes for which metrics are to be output. If not specified and a prefix is defined, all values on the MBean will be selected. |
type |
A filter for subtypes. If specified, only those objects whose type attribute matches will be collected. |
stringValues |
A map of string-valued metric names to a list of case-insensitive possible values. They will be converted to indexes of that list. |
Note that all fields other than the above, will be interpreted as collections of values.
In the preceding example, the presumed underlying data structure is:
+---------------+ applicationRuntimes
| ServerRuntime |-----------+
+---------------+ |
v
+--------------------+ +------------------+
| ApplicationRuntime | componentRuntimes | ComponentRuntime |
|--------------------| --------------------> |------------------|
| + name | | + type |
+--------------------| +------------------+
^
/ \
|
+------------------------+ +-------------------------+
| Servlet | servlets | WebAppComponentRuntime |
|------------------------| <----------------- |-------------------------|
| + servletName | | + name |
| + invocationTotalCount | | + contextRoot |
+------------------------+ | + deploymentState |
| + sourceInfo |
| + openSessionsHighCount |
| + status |
+-------------------------+
The above configuration will then produce metrics such as:
webapp_config_deployment_state{domain="mydomain",server="myserver",app="myapp",name="aWebApp"}
webapp_config_open_sessions_high_count{domain="mydomain",server="myserver",app="myapp",name="aWebApp"}
webapp_config_status{domain="mydomain",server="myserver",app="myapp",name="aWebApp"}
weblogic_servlet_invocation_total_count{domain="mydomain",server="myserver",app="myapp",name="aWebApp",servletName="servlet1"}
weblogic_servlet_invocation_total_count{domain="mydomain",server="myserver",app="myapp",name="aWebApp",servletName="simpleServlet"}
Note that no help or type text is currently produced, as the REST API has no access to the underlying MBean info.
The exporter produces metrics for monitoring its own performance:
wls_scrape_mbeans_count_total
reports the number of metrics scraped.wls_scrape_duration_seconds
reports the time required to do the scrape.wls_scrape_cpu_seconds
reports the CPU time used during the scrape.The exporter must be able to contact the REST API of the WLS instance on which it is deployed. It does so by using
the primary host address of its server and the port on which the request for metrics was made. Usually, that will work;
however, if the metrics request is made using a load balancer or Kubernetes NodePort service, the port to which the
original request was made might not be the same as the instance's HTTP port. In such a case, the configuration should
include the restPort
configuration to tell the exporter which port to use.
If you are running operator-managed WebLogic Server domains in Kubernetes, simply add the monitoringExporter
configuration element in the domain resource to enable the Monitoring Exporter. For an example, see the following yaml
file configuration:
kind: Domain
metadata:
name: domain2
namespace: domain_ns
spec:
monitoringExporter:
configuration:
metricsNameSnakeCase: true
domainQualifier: true
queries:
- key: name
keyName: server
applicationRuntimes:
key: name
keyName: app
componentRuntimes:
type: WebAppComponentRuntime
prefix: webapp_config_
key: name
values: [deploymentState, contextRoot, sourceInfo, openSessionsHighCount]
servlets:
prefix: weblogic_servlet_
key: servletName
values: invocationTotalCount
To use the Monitoring Exporter with Prometheus, see the directions here.
Deployment-based sample: This sample helps you set up and run Prometheus and Grafana with the WebLogic Monitoring Exporter. Deployment YAML files are provided to install Prometheus and Grafana.
Chart-based sample: This is an end-to-end sample that shows you the steps to set up monitoring for WebLogic domains using Prometheus and Grafana. Prometheus and Grafana are installed with Helm charts.
One way to use the exporter is by creating a WAR file with a default configuration and deploying it to a WebLogic Server instance.
The web application has a main landing page, which displays the current configuration and allows
you to change it, either by uploading a replacement or an addition to the queries specified with the current one.
Metrics will then be available from <application-root>/metrics
.
You can find all the exporter releases on the Releases page.
To download the web application wls-exporter.war
file and put your configuration file into the WAR, download the getXXX.sh
script, which is provided with each release and also can be downloaded from the Releases page, and then run:
bash getXXX.sh <your-config-file>
Use mvn install
to build the web application. This will create wls-exporter-<version>
, where version
is the Maven-assigned version number.
Adding -Dconfiguration=<some-config-file>
will insert the specified configuration as its default and remove
the version number to simplify deployment to WebLogic Server.
The sidecar is a standalone process that runs the exporter.
There are two ways to build the sidecar implementation. The first is with Maven, using the same mvn install
command
specified above. Note that this requires JDK21 or later; building the project with JDK8 will
skip the sidecar module. The alternative is to build with Docker.
Instead of manually building them, if you want to use pre-built images, then you can pull a pre-created image from the Oracle Container Registry (OCR) or from Google Container Registry (https://ghcr.io/), as follows:
docker pull container-registry.oracle.com/middleware/weblogic-monitoring-exporter:x.x.x
OR
docker pull ghcr.io/oracle/weblogic-monitoring-exporter:x.x.x
After building, run:
java -jar wls-exporter-sidecar/target/wls-exporter-sidecar.jar
This will start the exporter on port 8080, and it will expect to find a local WebLogic Server instance, listening on port 7001.
You can make changes by specifying parameters on the command line:
Setting | Default | Property |
---|---|---|
Domain name | (use WLS definition) | DOMAIN |
Exporter port | 8080 |
EXPORTER_PORT |
WebLogic host name | localhost |
WLS_HOST |
WebLogic port | 7001 |
WLS_PORT |
Use https | false |
WLS_SECURE |
You configure the sidecar by sending a PUT request to the path /configuration
.
You can do this with curl
; that is how the operator does it.
curl -X PUT -i -u myname:mypassword \
-H "content-type: application/yaml" \
--data-binary "@<path to yaml>" \
http://localhost:8080/configuration
Replace myname
and mypassword
with the credentials expected by WebLogic Server for its REST API,
and <path to yaml>
with the relative path to the configuration to use.
After the exporter is configured, a GET to http://localhost:8080/metrics
(or whatever port was chosen) will return the current metrics.
If you don't want to use a pre-built image from OCR, you can use the following Docker command to build the Monitoring Exporter image.
docker build . -t <image-name>
This will build the project and create a Docker image with the specified name. It is not necessary even
to do the Maven build first, as that will happen as part of creating the image. When running behind a firewall,
it is necessary to specify a value for the MAVEN_OPTS
and https_proxy
variables on the command line. For example:
docker build . --build-arg MAVEN_OPTS="-Dhttps.proxyHost=www-proxy -Dhttps.proxyPort=80" \
--build-arg https_proxy=www-proxy:80 \
-t <image-name>
This allows Docker to download the dependencies.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.
Please consult the security guide for our responsible security vulnerability disclosure process.
Copyright (c) 2019, 2023, Oracle and/or its affiliates.
Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.