Skip to main content

Logging

By default, Cortex logs only "Warning", "Error", and "Critical" messages. The first is essentially situations that Cortex is able to recover from (like a missing image or configuration), but might result in behavior different from what you're expecting (e.g. the form will only partially render). The latter two are unrecoverable situations where Cortex can not continue, and are accompanied by a yellow banner across the bottom of the page or a white page with a red message. (Likewise, if you see one of these two in the UI, the full details are available in the logs)

Where are the logs?​

Depending on how you are running Cortex, the logs may be visible in different places.

Event Viewer (Running Cortex with IIS)​

If you're using IIS, Warnings and Errors (as Windows calls them) are visible in the Windows Event Viewer, under "Applications". If you enable other log levels (see below), they can not be viewed with the Event Viewer and you will have to enable logging to file

Console (Running Cortex from the command line)​

When you run Cortex from the command line, logs are printed to standard output of the process. All log levels are visible.

Console (Running Cortex from the container image)​

If you're running Cortex in a container via e.g. Docker or Kubernetes, the container's console (sometimes called "log stream") contains the Cortex process's standard output (logs). Similarly to running from the command line, all logs enabled are visible.

File (Running Cortex with IIS)​

Logging to file is disabled by default, but can be enabled in the web.config file by updating this line:

<aspNetCore processPath=".\Cortex.exe" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />

At a minimum change stdoutLogEnabled="false" to stdoutLogEnabled="true", but also ensure that the path specified is a path that the app pool identity* has write access to. This path is relative to the directory the web.config file is in.

info

App Pool Identity​

IIS runs applications in something called an "application pool." By default, this application pool runs as a "user" (it's not really a user, but something called a "principal", but for our purposes it's a user) named the same as the application pool. (So the "DefaultAppPool", the one IIS uses by default, runs as a "user" called "IIS\DefaultAppPool".) All of the application pool users are part of a built-in group called "IIS_IUSRS" that you can grant permissions to if you want all of your app pools to have access. Importantly, if you choose to have your app pool run as a specific user (for instance, if you're using Windows Authentication for the SQL Server connection), then that user needs to be granted access.

Configuring log levels​

Cortex uses the ASP.NET 5+ (Core) logging infrastructure, which allows you to specify log levels by "category" in the "Logging:LogLevel" section of the appsettings.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      // ...
    }
  }
}

To set the log level for a particular category via the appsettings.json file (if you're running Cortex under IIS), simply change the value for the entry (or add a new one from the list below).

warning

appsettings.json is a JSON file and must contain valid JSON. Notably, this means no "comments" like you might find in Javascript or other programming languages; and punctuation matters. (For instance, the "comment" in the above example is purely for illustrative purposes to indicate that there may be additional configuration.)

Valid log levels​

These are the valid log levels and how Cortex uses each of them

  • Critical - Cortex has encountered a situation in which it can not continue at all and must immediately exit.
  • Error - Cortex has encountered a situation where it must immediately stop processing the current request. This results in a white page with red message or a yellow banner across the bottom.
  • Warning - Cortex has encountered an unexpected situation, but is able to continue with some (possibly incorrect) assumptions or missing information.
  • Information - Cortex has encountered a situation that might be useful for troubleshooting.

There are other levels, but they should not be used during normal operation (truthfully, "Warning" is the lowest level recommended for normal operation).

Useful "Categories"​

  • "Default" - the default level for all categories not otherwise specified
  • "Cortex" - Cortex-specific code
  • "Cortex.Authentication" - Logic used for identifying users from authentication providers and mapping them to security groups
  • "Cortex.Services.BusinessDataAccessor" - All logic related to accessing the business object record data
  • "Microsoft.AspNetCore" - The infrastructure used to serve Cortex pages. Can be useful to see if/when requests are making it to Cortex (e.g. through a load balancer)
  • "Microsoft.EntityFrameworkCore.Database" - Low-level SQL queries. Useful for verifying that queries are hitting the database.