1 Introduction
2 Configuration
- 2.1 Activate and Deactivate Procedures
- 2.2 Services
- 2.3 Telemetry configuration
3 Output File Format
4 Related Information

Introduction

The Telemetry Service of the SmartComponent Library provides insights into the utilization of the AppServer backend of a SmartComponent Library application, regardless if the backend is used by Web-, GUI-, REST-, SOAP- or open-client applications.

Per request the telemetry service writes down request details including the runtime, user and domain, service interface used and the actual service component (Business Entity) and method called into.

The Telemetry Data can be consumed by various applications. We are working on an integration of the Telemetry Data into the ProTop database monitoring service and portal (https://protop.com).

Configuration

Activate and Deactivate Procedures

The Telemetry Service relies on the AppServers Activate and Deactivate procedures as a central place for initializing the request logging and finalizing the logging and the actual output.

So the AppServer configuration needs to include our Activate and Deactivate procedures, e.g.:

    sessionActivateProc=Consultingwerk/Framework/Server/as_activate.p
    sessionDeactivateProc=Consultingwerk/Framework/Server/as_deactivate.p

Services

The Telemetry Service requires services for the following two interfaces to be loaded:

Consultingwerk.Framework.Server.Telemetry.ITelemetryService
Consultingwerk.Framework.Server.Telemetry.ITelemetryOutputWriter

We provide the file Consultingwerk/Framework/Server/Telemetry/services_telemetry.xml that loads these two services with our default implementations.

The file Consultingwerk/Framework/Server/Telemetry/services_telemetry.xml can for instance be referenced from the loadServices section of the JSON Configuration File Format

   "loadServices": [
        "Consultingwerk/SmartComponentsDemo/Web2/demo_services.xml",
        "Consultingwerk/Framework/Server/Telemetry/services_telemetry.xml",
        "Consultingwerk/OERA/TableStatistics/services_request_monitor.xml",
        "Consultingwerk/OERA/RequestManager/services_request_manager.xml",
        "Consultingwerk/OERA/RestResource/services.xml",
        "Consultingwerk/BusinessEntityDesigner/Web/businessentitydesigner_services.xml"],

Telemetry configuration

The file telemetry.conf needs to be created in a folder contained in the PROPATH of the AppServer (e.g. ablapps/<ablappname>/openedge with content similar to this:

{
    "detailLevel": 5,
    "outputDirectory": "../ablapps/smartpas_stream/telemetry",
    "fileNamePattern": "telemetry_${telemetry.instanceIdentifier}_${t.YYYY}${t.MM}${t.DD}_${t.H}${t.MMM}${t.SS}_${req.agent}_${req.session}.ndjson",
    "instanceIdentifier": "Consultingwerk42.smartpas_stream.124"    
}

Note, the outputDirectory needs to be created before starting the AppServer.

The detailLevel setting is currently not yet used but needs to be specified.

Based on the fileNamePattern the Telemetry Service is using the OpenEdge pattern resolver (https://docs.progress.com/bundle/openedge-abl-develop-services/page/Logging-tokens.html?labelkey=product_openedge_124) to build the file names used to write Telemetry data to. In addition to the logging tokens provided by Progress Software, we have added the telemetry.instanceIdentifier token.

The instanceIdentifier should be a unique identifier for an instance of the application backend.

Output File Format

The default ITelemetryOutputWriter implementation produces a single output file per AppServer session to avoid file locking conflicts. The files are written buffered in the NDJSON file format (http://ndjson.org/ ).

The buffered nature improves the output performance drastically, however most likely cause that the last line in the output files appear to be incomplete until further output is written to the file or the AppServer session that the file belongs to is shut down.

NDJSON files contain a single JSON document per line. The complete NDJSON file however is not a valid JSON document.

We use the following attributes in the JSON file:

Attribute Name	Description

Attribute Name	Description
instanceIdentifier	The unique identifier of the backend installation, matching the instanceIdentifier setting from the telemetry.conf file (see above)
startTime	The time the request has been started
endTime	The time the request has been finished
runTime	The runtime of the request in milliseconds
userName	The authenticated user name
domainName	The domain name of the authenticated user
serviceInterface	The service interface used, e.g. name of the Web Handler class or proSI…. procedure
adapterType	The PASOE Adapter type
agentId	The PASOE agent process ID
sessionId	The PASOE session ID
requestId	The request ID as appearing in the AppServer logfile
proversion	The version of OpenEdge
requestUri	The HTTP URI of the request
requestMethod	The HTTP request method of the request
serviceName	The name of the service component (e.g. Business Entity or Business Task invoked)
serviceRequest	The name of the method executed in the service component
queries	Request details, e.g. the queries property of a FetchDataRequest
key	Key identifying the request, typically composed of the abbreviated service name and service request or service interface
errorNumber	The runtime error message number when the request returned an error
runtimeError	The error messages returned to the client
applicationError	The application error messages returned to the client
stackTrace	The stack trace of an error returned to the client

Not all properties will appear at any time.

Related Information

Consultingwerk Telemetry Toolkit