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:
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.
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!