diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-monitoring.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-monitoring.adoc index 564130fc6e..5adea899e8 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-monitoring.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-monitoring.adoc @@ -339,6 +339,10 @@ The Open Identity Platform common audit event framework includes handlers for lo + OpenDJ supports LDAP and HTTP CSV access logs, which you must configure in order to use. +* JSON files. ++ +The default configuration includes the Json File-Based Access Logger, a JSON file handler for LDAP access events. The logger is disabled by default, because it records the same operations as the standard File-Based Access Logger and adds logging overhead for every client request. + * Elasticsearch server. + You configure the Elasticsearch handler as an external log publisher that logs access messages to Elasticsearch. @@ -354,6 +358,8 @@ Although it is rarely used for access events, you can configure the Syslog handl The Open Identity Platform common audit event framework supports a variety of audit event topics. OpenDJ currently supports handling for access events, which are system boundary events such as the initial request and final response to that request. In other words, the implementation in OpenDJ is focused only on access logging. Based on the connection handler for the request, OpenDJ divides access events into `ldap-access` events and `http-access` events. To enable common audit-based logging, follow one of these procedures: +* xref:#log-common-audit-ldap-json["To Enable JSON LDAP Access Logs"] + * xref:#log-common-audit-ldap-csv["To Enable LDAP CSV Access Logs"] * xref:#log-common-audit-http-csv["To Enable HTTP CSV Access Logs"] @@ -361,6 +367,51 @@ To enable common audit-based logging, follow one of these procedures: * xref:#log-common-audit-external["To Enable External LDAP or HTTP Access Logging"] +[#log-common-audit-ldap-json] +.To Enable JSON LDAP Access Logs +==== +The default configuration includes the Json File-Based Access Logger, a common audit JSON file handler for LDAP access events. The logger is disabled by default: it records the same operations as the standard File-Based Access Logger, so running both loggers doubles the logging work for every client request. + +After you complete the following steps, OpenDJ directory server records LDAP access event messages in files named like `logs/ldap-access.audit.json`: + +. (Optional) If you trust transaction IDs sent by client applications, and want monitoring and reporting systems consuming the logs to allow correlation of requests as they traverse multiple servers, update the global server configuration as described in xref:#log-common-audit-trust-transaction-ids["To Trust Transaction IDs"]. + +. Enable the log publisher as in the following example: ++ + +[source, console] +---- +$ dsconfig \ + set-log-publisher-prop \ + --port 4444 \ + --hostname opendj.example.com \ + --bindDN "cn=Directory Manager" \ + --bindPassword password \ + --publisher-name "Json File-Based Access Logger" \ + --set enabled:true \ + --trustAll \ + --no-prompt +---- + +. (Optional) To avoid logging each operation twice, consider disabling the standard access logger as in the following example: ++ + +[source, console] +---- +$ dsconfig \ + set-log-publisher-prop \ + --port 4444 \ + --hostname opendj.example.com \ + --bindDN "cn=Directory Manager" \ + --bindPassword password \ + --publisher-name "File-Based Access Logger" \ + --set enabled:false \ + --trustAll \ + --no-prompt +---- + +==== + [#log-common-audit-ldap-csv] .To Enable LDAP CSV Access Logs ==== diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-tuning.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-tuning.adoc index 3e58b545c0..aa14039150 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-tuning.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-tuning.adoc @@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. + Portions Copyright 2024-2026 3A Systems LLC. //// :figure-caption!: @@ -306,6 +306,8 @@ Debug logs trace the internal workings of OpenDJ, and therefore generally should In general leave other logs active for production environments to help troubleshoot any issues that arise. +Note that only one access logger, the File-Based Access Logger, is enabled in the default configuration. The Json File-Based Access Logger records the same operations in JSON format and is disabled by default: each enabled access logger adds its own log messages for every client request, so running several access loggers multiplies the logging cost on the operation processing path. + For OpenDJ servers handling very high throughput, however, such as 100,000 operations per second or more, the access log constitute a performance bottleneck, as each client request results in multiple access log messages. Consider disabling the access log in such cases: [source, console] diff --git a/opendj-server-legacy/resource/config/config.ldif b/opendj-server-legacy/resource/config/config.ldif index 0683e93851..ccf0fbf3ca 100644 --- a/opendj-server-legacy/resource/config/config.ldif +++ b/opendj-server-legacy/resource/config/config.ldif @@ -14,7 +14,7 @@ # Portions Copyright 2012-2014 Manuel Gaupp # Portions Copyright 2010-2016 ForgeRock AS. # Portions copyright 2015 Edan Idzerda -# Portions Copyright 2025 3A Systems, LLC. +# Portions Copyright 2025-2026 3A Systems, LLC. # This file contains the primary Directory Server configuration. It must not # be directly edited while the server is online. The server configuration @@ -805,13 +805,18 @@ ds-cfg-log-file: logs/debug ds-cfg-log-file-permissions: 640 ds-cfg-asynchronous: false +# The JSON access logger is disabled by default: it duplicates the File-Based +# Access Logger above (every operation is logged twice), and its bounded write +# queue is a measurable contention point on the operation hot path under load. +# Enable it with dsconfig if JSON-formatted (common-audit) access logs are +# needed, and consider disabling the text access logger in that case. dn: cn=Json File-Based Access Logger,cn=Loggers,cn=config objectClass: ds-cfg-log-publisher objectClass: ds-cfg-access-log-publisher objectClass: top objectClass: ds-cfg-json-file-access-log-publisher cn: Json File-Based Access Logger -ds-cfg-enabled: true +ds-cfg-enabled: false ds-cfg-java-class: org.opends.server.loggers.JsonFileAccessLogPublisher ds-cfg-log-directory: logs ds-cfg-rotation-policy: cn=24 Hours Time Limit Rotation Policy,cn=Log Rotation Policies,cn=config