SmartComponent Library Telemetry Service

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.:

1 2 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 https://consultingwerk.atlassian.net/wiki/spaces/SCL/pages/8094594

1 2 3 4 5 6 7 "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:

1 2 3 4 5 6 { "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.