Logging

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "general" : {
      "type" : "object",
      "title" : "General",
      "propertyOrder" : 0,
      "properties" : {
        "verifyPeriod" : {
          "title" : "Log Verification Frequency",
          "description" : "The frequency (in seconds) that OpenAM verifies security of the log files.<br><br>When secure logging is enabled, this is the period that OpenAM will check the integrity of the log files.",
          "propertyOrder" : 2000,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "security" : {
          "title" : "Secure Logging",
          "description" : "Enable or Disable secure logging.<br><br>Enabling this setting will cause OpenAM to digitally sign and verify the contents of the log files to help prevent and detect log file tampering. A certificate must be configured for this functionality to be enabled. ",
          "propertyOrder" : 2200,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "status" : {
          "title" : "Log Status",
          "description" : "Enable the OpenAM logging system.<p><p>OpenAM supports two Audit Logging Services: the legacy Logging Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM 13.5, and a new common REST-based Audit Logging Service available from OpenAM 13.5.<p><p>The legacy Logging Service will be deprecated in a future release.",
          "propertyOrder" : 800,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "resolveHostName" : {
          "title" : "Log Record Resolve Host Name",
          "description" : "Enable this to have OpenAM perform a DNS host lookup to populate the host name field for log records.<br><br><i>Note:</i> Enabling this functionality will increase the load of the logging system and the OpenAM host must have DNS configured. ",
          "propertyOrder" : 900,
          "required" : true,
          "type" : "boolean",
          "exampleValue" : ""
        },
        "filesPerKeystore" : {
          "title" : "Number of Files per Archive",
          "description" : "Controls the number of logs files that will be archived by the secure logging system.",
          "propertyOrder" : 2600,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "type" : {
          "title" : "Logging Type",
          "description" : "Specifies whether to log to a database, Syslog, or to the filing system.<br><br>If you choose database then be sure to set the connection attributes correctly, including the JDBC driver to use.",
          "propertyOrder" : 1000,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "fields" : {
          "title" : "Configurable Log Fields",
          "description" : "Controls the fields that are logged by OpenAM.<br><br>This property is the list of fields that are logged by default. Administrators can choose to limit the information logged by OpenAM.",
          "propertyOrder" : 1900,
          "required" : true,
          "items" : {
            "type" : "string"
          },
          "type" : "array",
          "exampleValue" : ""
        },
        "buffering" : {
          "title" : "Time Buffering",
          "description" : "Enable or Disable log buffering<br><br>When enabled OpenAM holds all log records in a memory buffer that it periodically flush to the repository. The period is set in the <i>Buffer Time</i> property.",
          "propertyOrder" : 3000,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "certificateStore" : {
          "title" : "Logging Certificate Store Location",
          "description" : "The path to the Java keystore containing the logging system certificate.<br><br>The secure logging system will use the certificate alias of <code>Logger</code> to locate the certificate in the specified keystore.",
          "propertyOrder" : 2400,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "signingAlgorithm" : {
          "title" : "Secure Logging Signing Algorithm ",
          "description" : "Determines the algorithm used to digitally sign the log records.",
          "propertyOrder" : 2300,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "bufferTime" : {
          "title" : "Buffer Time",
          "description" : "The maximum time (in seconds) OpenAM will hold log records in memory before flushing to the underlying repository.",
          "propertyOrder" : 2900,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "jdkLoggingLevel" : {
          "title" : "Logging Level",
          "description" : "Control the level of JDK logging within OpenAM. ",
          "propertyOrder" : 3100,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "bufferSize" : {
          "title" : "Buffer Size",
          "description" : "The number of log records held in memory before the log records will be flushed to the logfile or the database.",
          "propertyOrder" : 2700,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "signaturePeriod" : {
          "title" : "Log Signature Time",
          "description" : "The frequency (in seconds) that OpenAM will digitally sign the log records.<br><br>When secure logging is enabled, this is the period that OpenAM will digitally signed the contents of the log files. The log signatures form the basis of the log file integrity checking.",
          "propertyOrder" : 2100,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      }
    },
    "database" : {
      "type" : "object",
      "title" : "Database",
      "propertyOrder" : 2,
      "properties" : {
        "maxRecords" : {
          "title" : "Maximum Number of Records",
          "description" : "The maximum number of records read from the logs via the Logging API",
          "propertyOrder" : 2500,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "databaseFailureMemoryBufferSize" : {
          "title" : "DB Failure Memory Buffer Size",
          "description" : "Max number of log records held in memory if DB logging fails.<br><br>This is the maximum number of log records that will be held in memory if the database is unavailable. When the buffer is full, new log records cause the oldest record in the buffer to be cleared. OpenAM monitoring records the number of log entries cleared when the database was unavailable.<br/><br/>If the value of this property is less than that of the <i>Buffer Size</i> then the buffer size value will take precedence. ",
          "propertyOrder" : 2800,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "password" : {
          "title" : "Database User Password",
          "description" : "When logging to a database, set this to the password used to connect to the database. If this attribute is incorrectly set, OpenAM performance suffers.",
          "propertyOrder" : 1200,
          "required" : true,
          "type" : "string",
          "format" : "password",
          "exampleValue" : ""
        },
        "driver" : {
          "title" : "Database Driver Name",
          "description" : "When logging to a database, set this to the class name of the JDBC driver used to connect to the database.<br><br>The default is for Oracle. OpenAM also works with the MySQL database driver.",
          "propertyOrder" : 1300,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "user" : {
          "title" : "Database User Name",
          "description" : "When logging to a database, set this to the user name used to connect to the database. If this attribute is incorrectly set, OpenAM performance suffers.",
          "propertyOrder" : 1100,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        }
      }
    },
    "syslog" : {
      "type" : "object",
      "title" : "Syslog",
      "propertyOrder" : 3,
      "properties" : {
        "host" : {
          "title" : "Syslog server host",
          "description" : "The URL or IP address of the syslog server, for example <code>http://mysyslog.example.com</code>, or <code>localhost</code>.",
          "propertyOrder" : 1400,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "port" : {
          "title" : "Syslog server port",
          "description" : "The port number the syslog server is configured to listen to.",
          "propertyOrder" : 1500,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "facility" : {
          "title" : "Syslog facility",
          "description" : "Syslog uses the facility level to determine the type of program that is logging the message.",
          "propertyOrder" : 1700,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "protocol" : {
          "title" : "Syslog transport protocol",
          "description" : "The protocol to use to connect to the syslog server.",
          "propertyOrder" : 1600,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "timeout" : {
          "title" : "Syslog connection timeout",
          "description" : "The amount of time to wait when attempting to connect to the syslog server before reporting a failure, in seconds.",
          "propertyOrder" : 1800,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      }
    },
    "file" : {
      "type" : "object",
      "title" : "File",
      "propertyOrder" : 1,
      "properties" : {
        "numberHistoryFiles" : {
          "title" : "Number of History Files",
          "description" : "Sets the number of history files for each log that OpenAM keeps, including time-based histories.<p><p>The previously live file is moved and is included in the history count, and a new log is created to serve as the live log file. Any log file in the history count that goes over the number specified here will be deleted.<p><p>For time-based logs, a new set of logs will be created when OpenAM is started because of the time-based file names that are used.",
          "propertyOrder" : 300,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "rotationEnabled" : {
          "title" : "Log Rotation",
          "description" : "Enable log rotation to cause new log files to be created when configured thresholds are reached, such as <i>Maximum Log Size</i> or <i>Logfile Rotation Interval</i>.",
          "propertyOrder" : 100,
          "required" : true,
          "type" : "boolean",
          "exampleValue" : ""
        },
        "suffix" : {
          "title" : "Logfile Rotation Suffix",
          "description" : "The name of the log files will be suffixed with the supplied value.<br><br>This field defines the log file suffix. If no suffix is provided, then the following default suffix format will be used: <code>-MM.dd.yy-kk.mm</code>. The suffix allows use of Date and Time patterns defined in <a href=\"http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html\"><code>SimpleDateFormat</code></a><p><p><i>Note:</i> This field is only used if the time based rotation is enabled.",
          "propertyOrder" : 500,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "maxFileSize" : {
          "title" : "Maximum Log Size",
          "description" : "Maximum size of a log file, in bytes.",
          "propertyOrder" : 200,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "rotationInterval" : {
          "title" : "Logfile Rotation Interval",
          "description" : "The rotation interval (in minutes).<br><br>The rotation interval determines the frequency of when the log files will be rotated. If the value is <code>-1</code>, then time based rotation is disabled and log file size based rotation is enabled.",
          "propertyOrder" : 600,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "prefix" : {
          "title" : "Logfile Rotation Prefix",
          "description" : "The name of the log files will be prefixed with the supplied value.<br><br>This field defines the log file prefix. The prefix will be added to the name of all logfiles.<br/><br/><i>Note:</i> Only used when time-based log rotation is enabled.",
          "propertyOrder" : 400,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "location" : {
          "title" : "Log File Location",
          "description" : "The path to the location of the log files<br><br>This property controls the location of the log files; the value of this property varies on whether File or DB logging is in use:<p><ul><li>File: The full pathname to the directory containing the log files.</li><li>DB: The JDBC URL to the database used to store the log file database.</li></ul>",
          "propertyOrder" : 700,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        }
      }
    }
  }
}