This is documentation for Apprenda 7 and 8.
Documentation for older versions are also available.

Logs

The Logs page in the SOC allows you to review all the logs from your Platform and set log overrides to help manage logs. You are also able to manage the audit logs from this page.

To view logs, navigate to the Logs page from top menu of the SOC.

Event Logs

Any .NET service, user interface, or Java Web Application hosted on one of your Apprenda servers can contact the system logging service using the Apprenda API. The logging service will only allow events to be logged at the current Global Log Level or higher, in order of severity, where severity is measured as follows (from low to high):

For example, if the Global Log Level is set to Warning, the logging service will accept and display log entries for Warning, Error, and Fatal events. Based on expected usage of the logging service, the Debug level will result in the highest number of event log entries across the system.

Viewing a Log Entry

The Logs page shows a list of events that have been captured by the logging system in the past 24 hours. The default view displays the Level, Timestamp, Application, Session ID, Tenant, User, Source, Machine (server), and a truncated view of the log entry text for each entry. The Columns pull-down on the upper-right side of the page can be used to customize which columns are shown/hidden. Use the column headers to sort by any column. You can also search via the Search textbox and/or restrict by timestamp.

Note: The Event Logs view will display by default the last 24 hours’ worth of logs. You can use the Start Date and End Data input fields to search further than the past day.

If the Logs page is currently displaying logs messages pertaining to Platform operations, you can hide these messages using the Hide Platform Logs button in the System Events section in the upper left-hand side of the page. Conversely, if Platform logs are hidden, you may display them by clicking the Show Platform Logs button that will appear in the System Events section.

The App Filter can be used to display log messages for a given application version. To do so, simply click on the pull-down icon in the App Filter field. This will display a list of up to 25 application versions (by application alias and then version alias) of guest applications currently on the Platform. If 26 or more guest application versions are hosted on the Platform, type at least the first 3 letters of an application alias in order to populate the list. Selecting the Hide All App Logs option will configure the Logs page to hide all guest application log messages.

In order to view a specific log message, double-click on its row to open a pop-up window containing the full log text.

Deleting Individual Log Entries

You can delete a specific log entry from the logging system by selecting it in the list (use Ctrl + Click to select multiple entries or the Select All ... Logs button to select all log entries that fit the criteria of the current App and/or Platform filters). Click Delete Selected in the left toolbar to delete selected log entries.

Please note: developers may also be able to delete log entries related to their guest applications depending on the value configured for the Logging.AllowDevelopersToDeleteEntries Platform Registry Setting.

Logging System Context Awareness

Every event explicitly logged using Apprenda’s logging API maintains contextual awareness of the prevailing Apprenda contexts present at the time that event is captured. In addition to the timestamp of the event, every log entry in the Event Logs can contain:

  • Application – The application name and version name of the application version that logged the event, as well as its unique GUID.
  • Session ID - The unique GUID of the SaaSGrid session during which the event occurred.
  • SessionActive - Flag specifying if the session is still active.
  • ProviderName -The name and unique GUID of the Development Team that deployed the application that logged the event.
  • Tenant -The name and unique GUID of the Organization account that owns the User and session during which the event occurred.
  • User -The e-mail address and unique GUID of the User who made the request during which the event occurred.

Contextual awareness is extremely useful in determining the details around a particular event. For instance, finding contextual patterns in recurring events can be used to determine whether or not the event pertains only to a particular Tenant or User.

Setting the Global Log Level

To set the global log level, which is the level at which the logging system will accept log entries from any entity, select the desired level from the dropdown list in the left panel, and then click the Change button. The logging system will immediately begin to accept and display log entries at the new global level.

Clearing the Logs

Periodically, you may wish to empty the system store for logged events. To do so, click the Clear All Logs button. Note: Clearing the logs does not perform any sort of backup prior to removing log entries. If you wish to store log entries for historical purposes, you should employ a regular database backup strategy for the Apprenda core databases.

Exporting the Logs

A useful feature for Platform Operators is the ability to export logs from your Platform into a CSV file. To do so, select the logs you wish to export, then click Export Selected Logs. The Export Select Logs button is only enabled if logs are selected; otherwise the button is grayed out. Once you click to export, your browser should automatically download the CSV file of your chosen logs. The downloaded CSV file will contain an export of all the information contained within the database for the selected logs.

Masking the Logs

Some log entries may contain sensitive data that you do not want to be stored within the logging service’s database. If one or more Log Masks are specified, Apprenda will perform a search & replace action on the text of all log entries as they are processed by the logging system.

To create a new Log Mask, enter the text that Apprenda should search for within log entry text along with the text that you want Apprenda to replace it with. For example, if you want to mask the known password text “mypassword,” you might enter something like this:

Apprenda’s logging system will replace the string “mypassword” with the string “****” within the text of any event sent to the system at any logging level. It is important to note that this action occurs prior to the log entry actually being stored in the logging system’s database to ensure that the data you are trying to mask is not persisted. Click the Create Mask button to create your Log Mask and immediately apply the mask to incoming log events. Apprenda will not retroactively perform masking on events already in the logging system’s database.

Overriding the Logs

Setting the Global Log Level to a less severe level (Debug, Information) can result in a large number of events being sent to the logging system. Typically, software developers will use the Debug and Information log levels within application code to capture execution information during normal operation of the software that can be useful if something goes wrong. Apprenda’s core services work this way. Therefore, setting the Global Log Level to a less severe level can result in a lot of “noise” in the logging system from core services and deployed applications. For example, when the Global Log Level is set to Debug, all Apprenda routers on all machines will log information about the messages that they are routing between services. Apprenda allows you to create a log override, which enables you to capture events at a certain level for specific applications while the rest of the system remains at the Global Log Level.

Click the Overrides tab to view a list of the log overrides currently in place. The App Filter can be used to display overrides for a given application version. To do so, simply click on the pull-down icon in the App Filter field. This will display a list of up to 25 application versions (by application alias and then version alias) of guest applications currently on the Platform. If 26 or more guest application versions are hosted on the Platform, type at least the first 3 letters of an application alias in order to populate the list. Selecting the Show All Overrides option to show overrides for all application versions.

To create a new log override, click on the pull-down icon in the App & Version Alias field. This will display a list of up to 25 application versions (by application alias and then version alias) of guest applications currently on the Platform. If 26 or more guest application versions are hosted on the Platform, type at least the first 3 letters of the application alias in order to populate the list (at. Once you have found the application version for which you would like to create a log override, click on the version alias to select it.

Next, select the log level for this override.

You may filter your log override with additional criteria for finer grained control over the log entries that will be captured by this override. One of the following filter types may applied per log override:

  • Source (tag) - A string that matches the source tag for the log entry.
  • Tenant (customer) - The unique ID of the Tenant entity within Apprenda that is the prevailing context at the time the log entry is created.
  • User (subscriber) - The unique ID of the User entity within Apprenda that is the prevailing context at the time the log entry is created.
  • Message Text (message) - A string that matches the text of the logged message.

Additionally, you may provide a semi-colon or space delimited list of email addresses to notify when a log entry that matches your new log override criteria is captured. The logging system will automatically dispatch emails to the addresses you provide here in addition to capturing the event in the logging system.

The following settings would result in Apprenda capturing all Info events that occur while the Tenant with GUID D85C315F-0DE4-4BA7-8128-B5BDB5DB272A is using version vi of the application with app alias myapp1, and event-notifications@contoso.com will receive an email from the system:

Editing a Log Override

Select a log override in the list of current overrides and then click the Edit Selected Override button. The parameters of the selected override will be displayed in the Log Overrides form in the left panel. From here you can make necessary changes to your override. Click the Save Override button to save those changes. The action will be applied immediately, but will not affect any log entries that have already been captured by the previous override settings.

Removing a Log Override

Select a log override entry in the list of current overrides (Ctrl + Click to select multiple entries) and then click the Delete Selected Overrides button to remove the override(s). This action will be applied immediately, but will not remove any log entries that have already been captured by deleted overrides.

Audit Logs

This feature can optionally be enabled at Platform installation or by using the modify workflow in the Apprenda Installer. Once enabled, it cannot be disabled. 

Auditing is a way for you to view logs of operations performed on your Platform, such as login failures, password changes, user and role changes, etc. As of Platform version 7.2.0, certain actions performed in the Developer Portal are now audited. See a full list of audited actions to learn more.

Audit logs are kept within a SQL database instance provided during installation. Your Platform will not provide any special encryption on the Audit database. You will be responsible for instituting encryption, like Transparent Data Encryption, on that database according to your security requirements.  

If you have Auditing enabled on your Platform, you will be able to view the recorded actions under the Auditing tab. If you do not have Auditing enabled, you will still see the tab on the Logs page, but no logs will be recorded. The Auditing table displays all the Audit Logs made in the Platform, starting with the most recent. Each log will display the Timestamp, User ID, Tenant Name, Source IP, Operation, Resource changed, Original Value, and New Value. Any sensitive information that is already encrypted by the platform, like passwords, will be masked in the log to protect the information. You can filter through the Audit Logs by using the Search textbox or the Start Date and End Date input fields at the top of the table. 

 

To get an expanded view of the log entry, click on the View Details button for that log.  

  • User ID: The id of the User that performed the Operation.
  • Tenant Name: The name of the Tenant the User belongs to.
  • Source IP: The IP address of the origin where the User performed the Operation.
  • Operation: The action performed by the User.
  • Resource: The Platform entity that changed (ex. Platform Registry setting, Application Alias).
  • Original Value: The value of the Resource before the User performed the Operation.
  • New Value: The value of the Resource after the User performed the Operation.
  • Details: Any additional information the Platform recorded with the Operation.

Managing Audit Logs

To preserve the integrity of the audit logs, you are not able to delete or export any of the logs through the SOC. Additionally, Audit logs will remain intact when an application or user the log refers to is deleted or disabled. To remove old logs, you can control the period audit logs are kept in the Audit Database by adjusting the Auditing.GroomingPeriodDays Platform Registry setting. Logs with dates older than the grooming period will be deleted.