Appsettings.json Configuration

Below is an example of the updated BAM settings in a general appsettings.json file. Of course, any already existing appsettings.json file may have additional settings present not shown here. The default location of appsettings.json file is located in %OMETA_INSTALL_ROOT%\Ometa Software Suite

{
  "BamConfig": {
    "Enabled": true,
    "Destination": "File",
    "LogDirectory": "C:\\Program Files (x86)\\Ometa BVBA\\Log",
    "PortalUrl": "http://bam:65487/Portal/Dashboard-Health.aspx",
    "MaxPropertySize": 100,
    "MinimumLogLevel": "Information",
    "ProcessOverrides": [
      {
        "ProcessName": "BCS_ODBC",
        "Enabled": false
      },
      {
        "ProcessName": "BCS_OPCUA",
        "Enabled": true,
        "MinimumLogLevel": "Debug"
      }
    ]
  },
  "ConnectionStrings": {
    "OmetaBamDatabase": "Data Source=sqlserver.domain.net;database=OmetaBAMLogging;trusted_connection=yes;TrustServerCertificate=True;"
  }
}

General Logging Settings

Set the Enabled property to false to disable logging of the server. Obviously, setting it to true enables logging. Note: make sure the setting is present and set to true, otherwise the logging will be disabled by default.

Destination can either be File or Database.

  • File means writing to log files which are later processed for transfer to the BAM database.
  • Database means writing all logging directly to the BAM database.

When no destination is provided, the logging system will assume File being the default.

Note

Regardless of the defined destination, critical (= log level 'Critical') messages are also sent to the Windows Event Log.

Connection String

The connection string is used to process the files from the log directory and write them to a database, or writing logging directly to the database when the property Destination is set to Database. It is stored in the property OmetaBamDatabase of the section ConnectionStrings. This is a required setting.

An example showing a connection string for a default SQL setup (port 1433):

Data Source=sqlserver.domain.net;database=OmetaBAMLogging;trusted_connection=yes;TrustServerCertificate=True;

The following example shows a connection string for a SQL that is configured to receive connections on port 1500:

Data Source='serverName,1500\sqlInstance';database=OmetaBAMLogging;trusted_connection=yes;TrustServerCertificate=True;
Note

When using Trusted_Connection=yes in the OmetaBamDatabase connection string, ensure that the user of the BCSL service has sufficient permissions for reading and writing to the BAM logging database created during installation.

And be aware during initialisation the logging system checks whether the connection string is present and a connection can be set up to the database. If not, the system will fall back to file based logging, see Initialisation Fallback for more information.

BAM Portal Url

The BAM Portal URL is the URL used by the Ometa Business Connector to navigate to the BAM Portal website. It is stored in the property PortalUrl.

Important

Ensure that the BAMPortalUrl has a direct reference to the Portal/Dashboard-Health.aspx page. Another possibility is to set the index page of the BAM IIS site to this page.

Max Property Size

Stored in the property MaxPropertySize.

The amount of characters before it is cut of. This is only applied for properties in the formatted message of log events of the levels Error and Fatal. For more information about the log levels, see here.

If no value is provided or the defined value is lower than 100, the logging handler will reset the value to 100.

max property size example

Log Directory

The property LogDirectory contains the path name of the folder used to store the log files. This is a required setting when the Destination is set to File.

Within that log directory several subdirectories exist: Failed, Processing and Successful. Items in these directories stay there for seven days and are removed by the BAM Windows Service.

That BAM Windows Service is responsible to process all log files and writes them to the Ometa BAM Logging database. Even if the property Destination is set to Database, the service will still check for the presence of any files. When a particular file could not be processed properly, the entire file will be placed in the Failed subdirectory.

Note

Keep in mind that during initialisation the logging system checks whether the log directory is defined and exists. If not, the system will fall back to Windows Event Log based logging, see Initialisation Fallback for more information.

Log Levels

The current BAM implementation uses log levels for filtering. Every log line gets a severity or "state of importance". Depending on that severity, the BAM processes will decide to write the log line to the files (or directly to the database), or not at all. Additionally, it is possible to define additional minimum log level requirements for each of the separate processes of the framework. The default minimum log level is Trace, or logging of all information.

All available log levels, sorted from lowest to highest level:

Level Description
Trace Trace is the noisiest level, rarely (if ever) enabled for a production app.
Debug Debug is used for internal system events that are not necessarily observable from the outside, but useful when determining how something happened.
Information Information events describe things happening in the system that correspond to its responsibilities and functions. Generally these are the observable actions the system can perform.
Warning When service is degraded, endangered, or may be behaving outside of its expected parameters, Warning level events are used.
Error When functionality is unavailable or expectations broken, an Error event is used.
Critical The most critical level, critical or fatal events demand immediate attention.

With the help of the property MinimumLogLevel is it possible to tell BAM which log lines must be written. When the property is set to Information, all log lines with severities Information, Warning, Error and Critical will be logged. Log lines with severities Trace and Debug will be dropped. Another example: setting the property value to Error, will result that only log lines with severities Error and Critical are processed. Any other log lines are not.

Note

The minimum log level filter will only be applied at the moment of writing the log line to either a file or directly in the database. The BAM Windows Service processing log files for transferring them over into the BAM database will ignore the value of this property to avoid losing logging data unknowingly.

Important

It is important to note the old log category Verbose is mapped to the new log level Debug. This mapping is decided because the old Verbose level had the exact same meaning.

Process Filtering

The property MinimumLogLevel sets the log level for all framework processes. However, as stated before it is possible to define separate settings for individual processes. Those definitions have precedence over the general setting.

An example:

{
  "ProcessOverrides": [
    {
      "ProcessName": "BCS_ODBC",
      "Enabled": false
    },
    {
      "ProcessName": "BCS_OPCUA",
      "Enabled": true,
      "MinimumLogLevel": "Debug"
    }
  ]
}

In the example above, the 2 possible types of definitions are shown:

  • either disabling the logging for a process entirely (Enabled set to false for the process "BCS_ODBC"),
  • or defining a different minimum log level (MinimumLogLevel set to Debug for the process "BCS_OPCUA").

Make sure the setting Enabled is set to true otherwise the logging system will assume the process being set as disabled from logging.

The minimum log level can deviate from the general level in both directions. Setting a lower level will generate more logging for that process, and setting a higher one will generate less logging.

Following process names can be used:

  • BCA
  • BCJS
  • BCM
  • BCS_BaaN
  • BCS_OPCUA
  • BCS_AD
  • BCS_CMIS
  • BCS_DAV
  • BCS_DLL 4
  • BCS_File
  • BCS_MAPICS
  • BCS_MoveX
  • BCS_OData
  • BCS_ODBC
  • BCS_OS
  • BCS_REST
  • BCS_SAP
  • BCS_SharePoint
  • BCS_WebService
  • BCS_XML
  • BCSL
  • BCSP
  • Ometa.Framework.Authority
  • Ometa.Framework.Services.Bam
  • Ometa.Framework.Services.OpcUa
  • Ometa.Framework.Web (= Core web service)
  • Ometa.Services.Web (= Generic REST)
  • WpfGUI
Important

Best For Production Environments

Ometa recommends to set the MinimumLogLevel to at least Information in production environments. Define separate log level filters for specific processes if extra logging is needed.

Component Filtering

In case the Process Filtering isn't fine-grained enough and still too many log lines are generated, it is possible to add extra filtering in the component name of the log line. Component names refer to internal parts of the framework processes, allowing of easier identification of the source of a log line. Even more, logging from the Microsoft .NET platform (the platform on which the Ometa framework is based) is also written to BAM and those log lines can be identified by component name.

Warning

Filtering Sequence!

Log lines are first filtered through the Process Filtering. Any log lines still available are then checked against the component filtering. When that check succeeds, the log line will be written to BAM.

Configuration example:

{
  "ProcessOverrides": [
    ...
  ],
  "ComponentFilter": {
    "Microsoft.EntityFrameworkCore": "Error",
    "Microsoft.AspNetCore.Mvc": "Warning"
  }
}

Component name filtering or component filtering for short, works a bit different from the Process Filtering. Based on the configuration example above, the filtering works as follows:

  • log lines with a component name starting with 'Microsoft.EntityFrameworkCore' will only be written if the log level of those lines is at least equal to Error or higher.
  • log lines with a component name starting with 'Microsoft.AspNetCore.Mvc' will only be written if the log level of those lines is at least equal to Warning or higher.

The starting with is important. It means that e.g. in case of 'Microsoft.EntityFrameworkCore' all log lines having component names like 'Microsoft.EntityFrameworkCore', 'Microsoft.EntityFrameworkCore.Database', 'Microsoft.EntityFrameworkCore.SQLServer', etc. will be checked against. Even a component name like 'Microsoft.EntityFrameworkCoreV7' would be processed for filtering. The reason behind this, is that the component filtering is based on simple text-based comparisons, unlike the Process Filtering which is based on fixed value checks.

By default, some component filtering is already loaded during startup of each framework process. Good to know is that user configuration defined in the appsettings.json file will always have precedence over these default settings.

Default filters:

  • IdentityServer4.Startup: Warning
  • Microsoft.AspNetCore.DataProtection: Warning
  • Microsoft.AspNetCore.Mvc: Warning
  • Microsoft.AspNetCore.Routing: Warning
  • Microsoft.AspNetCore.StaticFiles: Warning
  • Microsoft.AspNetCore.Hosting: Warning
  • Microsoft.AspNetCore.Authentication: Warning
  • Microsoft.AspNetCore.Authorization: Warning
  • Microsoft.EntityFrameworkCore: Warning

Additional configuration example:

{
  "ProcessOverrides": [
    ...
  ],
  "ComponentFilter": {
    "Microsoft.EntityFrameworkCore": "Information",
    "Microsoft.AspNetCore": "Error"
  }
}

In this example, all log lines having the component name 'Microsoft.EntityFrameworkCore' (and starting with) with log level Information will be written to BAM. The default value will be ignored. Additionally, all log lines having the component name 'Microsoft.AspNetCore' (and starting with) including all defaults (see the list above), will only result in log data when the log level is set to Error. All default filters with the log level of Warning will be ignored.

Note

Be careful of faulty configuration!

{
  "ProcessOverrides": [
    ...
  ],
  "ComponentFilter": {
    "Microsoft.AspNetCore.Mvc": "Information",
    "Microsoft.AspNetCore": "Error"
  }
}

Here it may appear that all log lines having component names starting with 'Microsoft.AspNetCore.Mvc' will write logging from level Information and higher, and all log lines having component names starting with 'Microsoft.AspNetCore' will write logging from level Error and higher.

This is wrong. The definition of 'Microsoft.AspNetCore.Mvc' will be ignored and only the definition of 'Microsoft.AspNetCore' will apply.