Did you know that you can very quickly and easily enable access logging when you are running ORDS in standalone mode (i.e., when using the embedded Jetty server)?
FYI: This article is an excerpt from a living document I've been working on dedicated to ORDS installation, configuration, and usage (from the development/developer's perspective).
And in true "me" fashion, I've sufficiently traveled down the rabbit hole and back for your benefit! What you'll see below is a proposed update to the related section of the current ORDS docs (specifically, 5.2.3 Using Jetty XML Configuration). Some of what you see here might not make it to the official docs, however, I do think there is some good background and references. In fact, some of the "examples" might not make it either 😢.
Proposed/updated section
NOTE: I intentionally made things redundant as possible. This way, when you are scanning a discrete section you should hopefully have enough context to accomplish what you want in as little time as possible.
5.2.3 Using Jetty XML Configuration Files
This section describes how to configure the ORDS Jetty server (i.e., Standalone mode) for additional functionality using Jetty XML configuration files.
Some background
When ORDS is in Standalone mode (i.e., relying on the embedded Jetty server as its web server), ORDS can detect and “pick up” user-provided configuration settings found in the [ORDS configuration directory]/global/standalone/etc directory.
NOTE: You must create the [ORDS configuration directory]/global/standalone/etc directory. The /etc directory is not part of a standard ORDS configuration.
FYI: If you are familiar with Jetty, then just know that the ORDS /etc. directory is analogous to the JETTY_BASE directory, found in a standard Jetty deployment.1
5.2.3.1 Jetty Access Logs
NOTE: Beginning with ORDS version 24.1, the standalone ORDS Access Log format was updated to include additional format codes.2
ORDS versions
Jetty Format codes used
Access Log example
23.4 and earlier
“%h %l %u %t “%r” %s %b”
127.0.0.1 – frank [10/Oct/2000:13:55:36 -0700] “GET /ords HTTP/1.1” 302
Comparing ORDS access log formats pre- and post-version 24.1.
ORDS Standalone access logs will automatically be enabled once an access log location has been configured. You can enable Standalone logging by executing the following command:
After issuing this configuration command, the ORDS CLI will echo back the location. You can review your configuration settings by executing the ords config list --include-defaults command.
You will also see a new <entry></entry> has been saved to your /global/standalone/settings.xml file in your ORDS configuration folder.
In most cases, the ORDS-provided Access Log data should be sufficient. However, should you choose to create your own custom access log, you may do so with Jetty XML files.3
5.2.3.1.1 Jetty examples
The behavior of the access log will differ depending on your configuration settings. Three possible scenarios for access logs are included.
NOTE: The inclusion of these XML files at runtime changes Jetty server behavior and not ORDS behavior.
Scenario 1: a jetty-access-log.xml file IS included and standalone.access.log locationIS NOT set
In this first scenario, you do not need to “set” the standalone.access.log location. As can be seen in the below image:
You will, however, need to create an /etc directory in your ORDS configuration folder, similar to how you see below:
In the above image the /etc folder is nested under the /standalone folder, the /standalone folder is nested under the /global folder, and the /global folder is nested under the ORDS configuration folder (your unique configuration folder name and absolute folder paths will differ).
Place the following jetty-access-log.xml4 file into that /etc folder.
This jetty-access-log.xml file is comprised of the following properties:
Pay special attention to the <Arg></Arg> tags. The first <Arg>ument informs Jetty where and how to save the access log file (i.e., save as access.log at the location indicated). The second argument specifies the format strings to include in the log file. For a detailed explanation of these format strings, see the Jetty Access Logs section of this document.
NOTE: The format strings used in this sample XML file were chosen arbitrarily. You can include whatever relevant information, assuming it is available. See here for details.
Once you have saved this file, you may then start ORDS normally (i.e., with the ords serve command). ORDS will then save and append Jetty (Standalone) access log information to the access.log file. You can later view the results and formatting of this log at the location you specified:
An example access log file.Reviewing the contents of the access log file.
NOTE: You can remove this file from your ORDS configuration prior to the next time ORDS is started, and it will have no impact on your service.
Scenario 2: A jetty-access-log.xml file IS included and standalone.access.log location IS set
In this scenario, you will have already completed the following two steps:
Configured the standalone.access.log setting using the ORDS CLI, and
You have included a jetty-access-log.xml file (or whatever file name of your choosing) in the /etc folder.
Configuring standalone.access.log Verifying the configuration setting with the ords config list --include-defaults command.
NOTE: You will also see a new <entry></entry> has been saved to your /global/standalone/settings.xml file in your ORDS configuration folder.
After executing the ords serve command, you’ll also see the standalone.access.log configuration setting included as ORDS initializes.
You’ll also notice two versions of the access log files in the /[access log] folder location.
One file for the access.log, which was created from the jetty-access-log.xml file you included.
The other will be a log file with the format of: ords_[log file date].log.
This second file5 (and subsequent log files saved by date), is the one that is automatically created for you as a result of setting the standalone.access.log property in your ORDS configuration.
Scenario 3: A jetty-access-log.xml file IS NOT included and standalone.access.log location IS set
This is effectively the standard, typical way you would configure ORDS for Standalone access logging.
Set the standalone.access.log configuration setting with the following command:
NOTE: You will also see a new <entry></entry> has been saved to your /global/standalone/settings.xml file in your ORDS configuration folder.
Remove any [jetty].xml files from your /etc folder.
Once you start ORDS (i.e., ords serve) you’ll find access logs in your access log folder. These and subsequent logs will be saved in the ords_[log file date].log format.
And that’s it! You made it 😃.
And some considerations
The third scenario (the standard option) seems to be the most logical and convenient method for saving Standalone access logs, for a few reasons:
No need to rely on XML files
Log files are conveniently saved with an intuitive naming convention, and
Log files are saved in a recognized format; making it easier for third-party logging analytics tools to ingest the data
Footnotes are below. If you thought this was helpful, please share and comment! That’s all for now 😬.
Follow
And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!
It’s not crucial for you to have a deep understanding of how Jetty works. At a basic level, just know that there will always be a JETTY_BASE as well as a JETTY_HOME directory. And, in a standard Jetty installation, JETTY_BASE is where your modules and any customization live. While JETTY_HOME is where the Jetty binaries live. For the purposes of ORDS, the [ORDS configuration directory]/global/standalone/etc directory can be looked at as your JETTY_BASE. That is where you’ll place JETTY.XML files; similar to the ones you’ll see in this section’s examples. Again, none of this is important for you to know unless, of course, you’d like to learn more about Jetty. ↩︎
Jetty XML files can be viewed as a simpler way to add additional configuration settings to your Jetty server without having to create a custom Jetty Module. For a deeper dive into Jetty modules, how to configure them, and customizations see here. ↩︎
This file can be named [anything].xml. The format, contents, and arguments therein are what are important. ↩︎
The ORDS-provided access logs, automatically save in the NCSA Common log format. Since other logging applications and tools may expect to ingest logs in this format, it might be worth considering whether or not you actually want to customize your own Jetty access logs. You can find details on the NCSA Common log format here or visit the now-archivedHTTPd page for more information on the creation of this format. ↩︎
I’m kidding, there’s more. But if you don’t feel like reading anymore, bookmark this post and return when you’re ready.
Assuming you have ORDS installed, you too can execute the ords config list --include-defaults command to reveal almost all the configuration settings for your ORDS installation.
Here is what my configuration looks like:
Executing the ords config list --include-defaults command.
Configuration settings: what am I seeing?
This command is a quick way to see all the settings from your .XML configuration files (i.e., the settings.xml and pool.xml files), including other settings automatically configured for you when you first ran the ords interactive installer.
In short: All your default settings and any that you may have added or changed are on one screen.
Read on to explore further…
Version, config folder location, and pool information
I've broken the configuration settings into sections. Anywhere you see red arrows, are just areas of intrigue (personally); however THIS LIST IS NOT EXHAUSTIVE.
I use this first section as an easy, convenient way to determine the ORDS version I’m running. Additionally, you can verify the location of your configuration folder (in case you forget). You can also verify the database pool (default is the default name for the pool unless you modify the name) you are using.
ORDS version, configuration folder location, and database pool information.
If you want to learn more about the ORDS pools, visit this link and this link.
💡I only have single install, that is why I see default as the default database pool.
Pool and global settings
Not much here that you probably already don’t know. However, in the future I will look at the features associated with the database.api.management.services.disabled = false property (also, I think the way this is written is a referred to as a “logical negation”, and it hurts my brain to read).
General ORDS settings.
Read more about this service here. But in short (and once you’ve created the requisite user), you can explore various services such as:
DBCA Jobs, available methods: DELETE, GET and POST
DBCA Templates GET
Oracle Home Environment GET
PDB Lifecycle DELETE, GET, POST
Open Service Broker DELETE, GET, and PUT
Debug and Error
My settings are false (these are the default settings). But if I were to, for instance, set debug.printDebugToScreen = true, I would then be able to see any error messages in the browser.
ORDS debug and error settings.
I can change the responseFormat to always display as JSON, HTML, or AUTO (i.e., Automatically determine the most appropriate format).
ℹ️ Note: Must explore this further and report back after I've sufficiently tinkered.
Did you know you can create custom HTTP error pages in ORDS? These two error.properties appear to be associated in some way. So if you were two create custom error pages, you’d probably need to consider the format as well. Nonetheless, could you imagine the fun you could have coming up with something totally unique to your application?
I'm definitely adding this to my "Productive Procrastination" list 🤣!
GraphQL and SQL Developer Web
ORDS supports GraphQL now; did you know?! I just set up my local installation (it wasn’t too bad once I figured out how to properly set my Java to GraalVM 😑), so I can start learning GraphQL queries.
GraphQL and ORDS settings.
Did you know ORDS ships with the GraphiQL IDE now? Learn how to set it up here.
Cookies and ICAP
I honestly wouldn’t have known ORDS could offload virus scanning to ICAP (Internet Content Adaptation Protocol) servers unless I looked at what was actually in the configuration settings. I’m not sure if I’ll configure this anytime soon, but maybe you will.
Want to bore yourself? Read more about ICAP in this RFC 3507 memo.
Java Database Connectivity (JDBC)
I am NOT going to spend much time here. I still need toggle these parameters and experiment more. However, I will point out that the default setting for maximum JDBC connections is 20 (jdbc.MaxLimit setting).
Java Database Connectivity and ORDS settings.
jdbc.MaxLimit=20 is probably too low for a production environment. I’ve left it as-is because it’s just me, and I’m doing everything locally in my Podman container.
Suppose you need to familiarize yourself with JDBC or Universal Connection Pools (UCPs)? In that case, we should both read the introduction sections of the following guides:
I have spent little time with MongoDB, but from what I understand, the Oracle Database API for MongoDB translates the MongoDB wire protocol into SQL statements executed by the Oracle.
ORDS and the MongoDB API settings.
What I’m inferring from our docs is that once you’ve migrated your data from a MongoDB into a supported Oracle database, you (or your application) can keep talking “MongoDB speak,” and at least in this case, ORDS will be able to interpret this Mongospeak and query the database on your behalf 🤯!
If this describes you or your use-case, you’re in luck; I found some excellent resources!
You’ll notice, no red arrows here. I have yet to spend much time with this section. However, I want to draw your attention to the security.jwks.[etc...] and security.jwt.[etc...] properties.
ORDS security settings.
In ORDS 23.3, we introduced JSON Web Tokens (JWTs) support, so these properties very much concern that new functionality.
In short, we've allowed you to incorporate JWT authentication provided through third parties into your APIs.
The nice thing about ORDS is that you can use the embedded Jetty server as a local web server for testing. This section shows most of the essential settings for running Jetty in “Standalone mode.”
ORDS standalone Jetty Server settings.
I use the term “testing” because our docs state, “the default configuration of Jetty is optimized for the most common ORDS use cases.”I interpret this as, “This is designed to expose you to Jetty (and make it easy to get you up and running), but you’ll probably need to adjust this according to your own requirements.”
The only things I want to point out here are the standalone.doc.root and standalone.static.context.path properties. These settings will look familiar if you’ve ever performed an APEX installation (available here, for free, BTW).
However, if you want to deploy custom HTML, CSS, and image files, you can configure this for ORDS. We have an overview in our docs here.
I think I've just stumbled upon another fun Friday afternoon project 😍!
Okay, that’s it for now. Thank you for choosing to waste your time with me.
What’s the point of this post?
There was no point to this post. I’m constantly wasting time researching technology and techniques I don’t need to know. However, in this case, I’ve hopefully:
left you with at least one helpful ORDS command-line command (ords config list --include-defaults), and
provided you with some helpful explanations and resources on what is contained in your ORDS installation (again, this list is NOTexhaustive)
And if you found this post helpful, please share it!
Follow
And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!