Tag: ords configuration

  • ORDS Standalone access logs: Jetty and customizing with XML

    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)?

    Proposed/updated section

    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.

    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 versionsJetty Format codes usedAccess 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
    24.1 and later“%{client}a %u %t “%r” %s %{CLF}O “%{Referrer}i” “%{User-Agent}i” %{ms}T %{Host}i”192.168.122.1 – [27/Mar/2023:23:00:07 +0000] “GET /ords/ HTTP/1.1” 302 – “-” “Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/111.0” 132 192.168.122.149:8080
    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.

    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.xml4 file into that /etc folder.

    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>

    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:

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

    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!

    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. ↩︎
  • The one ORDS command you NEED to know!

    The one ORDS command you NEED to know!

    ords config list --include-defaults

    That’s it. Goodbye!

    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:

    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.

    Read on to explore further…

    Version, config folder location, and pool information

    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.

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

    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.

    I can change the responseFormat to always display as JSON, HTML, or AUTO (i.e., Automatically determine the most appropriate format).

    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?

    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.

    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.

    Bookmark this link for future reference!

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

    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:

    MongoDB

    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.

    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!

    Security

    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.

    In ORDS 23.3, we introduced JSON Web Tokens (JWTs) support, so these properties very much concern that new functionality.

    Good resources to bookmark:

    Standalone (Jetty)

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

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

    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 NOT exhaustive)

    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!