ORDS Standalone access logs: Jetty and customizing with XML

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 😢.

Download ORDS | Oracle ORDS forum | ORDS Docs | ORDS playlist

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]

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:

ords config set standalone.access.log [/Path to the access log location of your choosing]

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 location IS 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:

[ORDS configuration directory]/global/standalone/etc

An example:

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.xm file into that /etc folder. [4]

This jetty-access-log.xml file is comprised of the following properties:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <Ref id="Handlers">
      <Call name="addHandler">
        <Arg>
          <New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler">
            <Set name="requestLog">
              <New id="RequestLogImpl" class="org.eclipse.jetty.server.CustomRequestLog">
                <Arg>/Users/choina/ords_access_logs/access.log</Arg>
                <Arg>%{remote}a - %u %t "%r" %s %O "%{Referer}i" "%{User-Agent}i"</Arg>
              </New>
            </Set>
          </New>
        </Arg>
      </Call>
    </Ref>
</Configure>

Notice the <Arg> tags.

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:

1. Configured the standalone.access.log setting using the ORDS CLI, and
2. You have included a jetty-access-log.xml file (or whatever file name of your choosing) in the /etc folder.

Configuring standalone.access.log

Using 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.

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 file (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. [5]

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:

ords config set standalone.access.log [/Path to the access log location of your choosing]

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!

• Blog
• Twitter
• YouTube
• LinkedIn
• Instagram
• TikTok
• GitHub
• Mail

Footnotes

1. 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.
2. About Jetty Custom Request Log format codes and syntax
3. 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.
4. This file can be named [anything].xml. The format, contents, and arguments therein are what are important.
5. 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-archived HTTPd page for more information on the creation of this format.