Introduction

The Telemetry Service of the Consultingwerk Telemetry Toolkit (included in the SmartComponent Library) provides insights into the utilization of the AppServer backend of an application, regardless of the type of frontend  (Web-, GUI-, REST-, SOAP- or open-client applications).

The Telemetry Service captures and writes request details including the execution time, user and domain, service interface used and the actual service component (Business Entity) and method called into. Applications can further customize the data produced (for example, to record the queries requested by the client).

Data is recorded on a per-request basis. By default, data is written in a standard NDJSON format. NDJSON (https://ndjson.org/ ) is a JSON based file format optimized for stream processing. Telemetry data can be consumed by various applications, whether desktop or cloud-based.

The Consultingwerk Telemetry Toolkit is a standalone library that is used to gather and publish data on requests made to an AppServer. This library can be added to an existing application. The Telemetry Toolkit consists of the SmartComponent Library Telemetry Service and its dependencies, procedures that allow the runtime to bootstrap itself, and various code that performs the measurement of requests made to the AppServer. It also includes a standalone GUI viewer for the data.

Installation

The Telemetry Toolkit is available from https://esd.consultingwerkcloud.com/ for licensed customers. The source code is published in a ZIP archive and needs to be extracted into a directory of choice. We will be referring to this directory as the installation location.

Configuration

The Telemetry Service was original designed to work with PASOE, although it can work with Classic AppServer and Classic WebSpeed as well. The Using the Telemetry Toolkit with Classic servers section has more information.

PROPATH

The installation location must be added to the application’s PROPATH in conf/openedge.properties .

Session Startup Procedure

The Telemetry Service needs to be started as part of session startup. To do so, add to conf/openedge.properties

If the application already has a session startup event procedure, the Telemetry Toolkit’s procedure must be run from the application’s startup procedure. The behaviour of the Telemetry Service can be configured (see below).

The Consultingwerk.Framework.FrameworkSettings:TelemetryService static property is set to the Telemetry Service instance on successful start of the service. This property must be used to reference the Telemetry Service in the application.

For example, to set the user name and domain,  call the SetUserInformation method as below.

Activate and Deactivate Procedures

The Telemetry Service relies on the AppServer’s activate and deactivate event procedures as a central location for initializing the request logging and finalizing the logging and the actual output. These procedures are required to be run as part the request’s activation and deactivation; the Telemetry Service will not operate properly otherwise.

So the AppServer configuration needs to include our Activate and Deactivate procedures. If the application does not have such procedures configured, they can be added to conf/openedge.properties

If the application already has the activate or deactivate event procedure, the Telemetry Toolkit’s procedures must be run from the application’s activate and deactivate procedures.

The Telemetry Service’s BeginRequest() method should be called during the activate procedure. The Telemetry Service’s EndRequest() method should be called during the deactivate procedure.

Instrumenting Applications

The Telemetry Service gathers various data about a request, including

• Metadata: for example the kind of request; the OpenEdge version being run; the duration of a request; on PASOE, the agent ID, session ID and request ID.

• The service interface and service used

• The current user, if any

• Errors that may have occurred during the request

• Application data, such as the queries run or the URL requested

Certain of these data can be populated generically from the activate and deactivate procedure, but some types of requests, and some data requires applications to add code (“instrumentation”) to gather relevant data.

Service Interface Data

When making requests to an AppServer the initial program run is either a service or a service interface. This program may be a class or a procedure, and may be the program that does the requested work (a service) or a program that delegates the work (a service interface).

The Telemetry Toolkit’s activate procedure records the program that is run as the service interface for the request. In most cases, this is adequate. The major exception is for PASOE web requests. In this case, the program called is always the same (OpenEdge.Web.InternalWebRouter), regardless of the URL and of which webhandler is configured to process that request. Typically, an application is more interested in the webhandler that is run.

The TelemetryService’s SetServiceInterface() method infers the service interface class and method names, and should be called from a webhandler’s HandleGet() and similar methods. The Telemetry Service includes the Consultingwerk/Framework/Server/Telemetry/web-handler-request.i include that sets the service interface appropriately, along with certain other information. This include should be added to all webhandler methods that process HTTP requests.

Service Name Data

The service is the business logic or process code that the service interface calls. The name of the service to run is not generically available – usually the service interface knows how to determine it, either by hard-coding, or by parameters passed in, or by some other form of lookup/abstraction.

The service name must be set by the service interface, using the SetServiceRequest() method.

User Data

When the Telemetry Toolkit’s activate procedure runs, it extracts the ABL client-principal for the request, and if valid, records that user name.

Not all applications use the client-principal for determining user identity. In this case, once the current user identity has been determined, the SetUserInformation() method may be called.

Errors

Errors that are raised during the execution of the service should be caught by the service interface and added to the telemetry data. The SetError() and SetStopCondition() methods must be used for recording errors and stop conditions, respectively, that have been caught using CATCH blocks.

Application-specific data

Application-specific data may be added to a request’s telemetry data using the SetData() method. Examples of such data are the queries executed for a business entity’s fetch data request, or the HTTP request method used.

Since telemetry data may be consumed by third-party monitoring tools, care should be taken when deciding which data to add. Confidential or private data should not be added as telemetry data.

Telemetry Toolkit API

API documentation for Consultingwerk.Framework.Server.Telemetry.ITelemetryService is available at http://help.consultingwerkcloud.com/smartcomponent_library/release/Consultingwerk.Framework.Server.Telemetry.ITelemetryService.html

The Consultingwerk/Framework/Server/Telemetry/web-handler-request.i is provided to conveniently set various aspects of the telemetry data from a webhandler.         

Event procedures are provided in Consultingwerk/Framework/Server/Telemetry/ for session startup (as_startup.p), activate (as_activate.p) and deactivate (as_deactivate.p).

Using the Telemetry Toolkit with Classic servers

Using the TelemetryService with a Classic AppServer or Classic WebSpeed requires some minor changes to the configuration used for PASOE.

Appserver configuration

The startup, activate and deactivate event procedures must still be configured in the same manner as for PASOE. However, the property names are srvrStartupProc, srvrActivateProc and  srvrDeactivateProc respectively.

$DLC/tty/netlib/OpenEdge.Net.pl must be added to PROPATH. This procedure library is added to PASOE propaths by default.

Other changes

The fileNamePattern property in the telemetry.conf configuration file contains tokens for the agent and session ID’s, that will not resolve on Classic AppServer. The default patterns is

The req.agent and req.session tokens will not resolve on Classic servers, resulting in file names like telemetry_devver-126_20230123_141149_${req.agent}_${req.session}.ndjson .

The fileNamePattern property value can be changed to something like the below

These changes are recommended.

Using the Telemetry Toolkit with SmartComponent Library based applications

The SmartComponent Library has already implemented all the necessary instrumentation to take full benefit of the Telemetry Toolkit.

However, specific Business Services may want to add specific instrumentation to log very specific request details.

Using the Telemetry Toolkit with ADM2-based applications

Consultingwerk supports recording telemetry data on ADM2-based applications that use SmartDataObjects  (SDOs). Instrumentation has been added to the standard ADM2 service interface procedures for reading and writing data, and for making generic calls.

The adm2/fetchdata64.p, adm2/fetchrows.p (for reading data), adm2/commit.p (for writing data) and adm2/calltable.p (for calling procedures) procedures provided by the Telemetry Toolkit must be placed in a folder that appears before the OpenEdge install (or other ADM2 location).

Other changes

Procedures that are called directly across the AppServer boundary may also need to be instrumented to add application context to the telemetry data captured. This data could take the form of input parameter values, for instance.

Error handling should also be added to the procedures. The Telemetry Service accepts an instance of a Progress.Lang.Error object as an error; ADM2-based error-handling often uses the ABL’s RETURN-VALUE or ERROR-STATUS handle. Only the former is transmitted back to a client. A Consultingwerk.Util.Exceptions.Adm2Exception class is provided to provide a wrapper for ADM2-style error messages.

An example of how using this class is below. The pocMessages parameter contains the ADM2 messages in this case.