Host Trace

Administration Page	Application/Contract	Syracuse/Collaboration	Class	traceRecords	Representation	traceRecord

Up to version 2018.R2, this function allows you to create technical trace files on request to send to Sage support.From version 2018.R3, trace files are handled in Global Settings.

This function provides:

• A way to create records based on a default configuration (that can be customized manually).
• A service to start a record.
• A service to pause and resume a record.
• A service to stop a record.

The content of a record cannot be retrieved until the record is stopped.

Query facet for traces record

In this facet, you can find the list of trace records and their state. Note that:

• The name can be given manually (manual trace), or start with "Auto_Record_" followed with the date (automatic traces).
• Auto records are handled during the system startup. Several auto records can run simultaneously (one per node.js instance when the load balancer is in operation).
• The alterable flag is set when the user can modify the trace parameters. This is only possible for the node process the user is connected to.
• The status can be "running", "error", or "complete".

Auto record

A standard auto record is automatically created when a node.js process starts. It can also be started to log specific events.

A rotation mechanism was implemented to launch a new auto record each day, and another one was implemented to split records by size. This ensures that records will never be larger than a specified size. These behaviors can be defined from the nodelocal.js configuration file:

   exports.config = {
      ...,
      traces: {
         maxSize: "5m",
         maxFiles: 3,
      }
   },

The maxSize property allows you to define the maximum size for a record. The syntax allowed is "*k" or "*m" or "*g" (kilo, mega or giga bytes) where * is a number.

The maxFiles property allows you to limit the number of files for a given date and PID. When an auto record reaches the maximum size, or when a stop action is called, a new one is created and launched with the same name as the previous one. The previous one is renamed by adding a suffix.

Manual record

For specific needs (bug investigation, for example), you may need to create a manual record. Two modes are available:

• Only my session, which allows you to activate traces corresponding to the current session only. This has less impact on global server performances.
• Ticket number, in case a customer encounters issues and submits a ticket to Support. This information can be entered here so that the Sage Support team can retrieve the information automatically when the customer sends the record.

Several types of events are traced and identified in the Configuration grid. Different trace levels are available for each type of event traced:

• Error_ only traces errors.
• Warning_ also traces warnings.
• _Info_ adds the information log to the previous events.
• _Debug_ is the most verbose trace and returns a lot more information.

Example: In the X3 communication layer, you can trace the call of javascript functions from a 4GL process, the X3 client pool requests, the "sadfsq" communication layer, or the print server layer at the different levels available.

Trace settings are used for each new auto record. Therefore, it is necessary to edit these settings to adjust auto records. However, for manual records, these settings are only available as a default configuration. You can only customize them before starting the record.

Once the setup is complete and saved, it is possible to start, pause, or stop a started trace, as well as resume a paused trace, flush the current trace file, and start another one.

Storage and setup principles

All trace configurations are stored in the traceSetting entity. Each record configuration is synchronized during the server startup:

• If new traces were added, all new configurations that are needed are automatically created in MongoDB if they do not exist.
• The default level values are taken from nodelocal.js or set to "error".
• Existing configurations are retrieved from MongoDB.
• Configurations are automatically deleted if they are no longer required.
• A reset service is provided to reinitialize all configurations with the "error" level or nodelocal.js values.

For an auto record, the nodelocal.js default values needs to be declared as follows:

exports.config = {
      ...,
      traces: {
            levels: {
                  // Example for tracers with submodules
                  orm: { // Object-relational mapping
                        factory: "info", // Syracuse entities management
                        x3: "debug", // X3 ERP entities management
                        mongodb: "error", // MongoDB interactions
                  },
                  // Example for tracers without submodule
                  search: "debug", // Elasticsearch communication
            }
    },      

Creating the records

The Traces grid lists all the files created for a trace session. When the corresponding file is no longer active, it can be downloaded manually by clicking the corresponding icon. A trace file is no longer active after stopping the trace or performing a flush to start another trace file.

You can click Download all to download all the inactive files corresponding to the session. The files need to be sent to the Sage Support team for analysis.