Helium Logging Service

Owned by Jacques Marais
Last updated: Jan 11, 2021
2 min read




Overview

The Logging Service is a web service providing a real-time stream of app-specific 

  • exceptions (such as error messages originating on the Helium server) and
  • log statements (i.e. the Mez:log(s) built-in functions),

using the Websocket protocol.

The URI is wss://{host}/api/ws2/logging and it takes a URL parameter appId. appId, represents the unique app id for your app. If you are uncertain how to obtain this id please consult the documentation here.

For example, if you're debugging on preprod.mezzanineware.com for an app with app id 46942734-64e0-49cd-a83b-b0e096e372d4 the URI will look like this:

wss://preprod.mezzanineware.com/api/ws2/logging?appId=46942734-64e0-49cd-a83b-b0e096e372d4

Previously, debugging in the DSL relied on inspecting Glassfish server logs directly. If you come across reference to this methodology, be aware that using the logging service replaced it.

Authentication

The connecting Websocket client will need to authenticate itself. For this you will need API credentials for the specific environment/Helium server that you are developing against. If you are able to deploy apps to a Helium server, it means you already have API credentials for that server. If, however, you still need to request API credentials, please refer to the process mentioned here.



Example using "WebSocket cat" (wscat)

$ wscat -c wss://preprod.mezzanineware.com/api/ws2/logging?appId=46942734-64e0-49cd-a83b-b0e096e372d4 --auth {username}:{password}

The output will look something like this, as long as the connection stays open:

connected (press CTRL+C to quit)

< {"id":"61275314-0ed7-4c10-b84a-43067596846b","key":"INFO","value":"AdminMenu-->AdminFixesAndFeatureTests","millis":1484291539567,"appId":"83a02315-e6a0-41c4-d190-a0ff7c435d1a","appUserId":null}

< {"id":"a2e8ffba-e60c-4a1a-bde2-4f0aa3f23fd0","key":"INFO","value":"AdminMenu-->AdminFixesAndFeatureTests-->Hd1034TestCasesMenu","millis":1484291565277,"appId":"83a02315-e6a0-41c4-d190-a0ff7c435d1a","appUserId":null}

< {"id":"7486b693-8b49-4925-a14b-0dfb2cf4f8ef","key":"helium.ProgramFacade.processViewResponse","value":"[Hd1034:108] Division by zero","millis":1484291574441,"appId":"83a02315-e6a0-41c4-d190-a0ff7c435d1a","appUserId":"bf8eb8dc-02c0-4b68-82bd-24896e2b7519"}

< {"id":"8d2b864e-4376-47c2-bb41-0665e968d84b","key":"helium.ProgramFacade.processViewResponse","value":"[Hd1034:64] Null pointer exception","millis":1484291583081,"appId":"83a02315-e6a0-41c4-d190-a0ff7c435d1a","appUserId":"bf8eb8dc-02c0-4b68-82bd-24896e2b7519"}

>

If an error occurs opening the websocket stream, the expected behaviour is for you to see that it "connected" and immediately "disconnected". An example cause of this is when you specify an incorrect appId, e.g. one for which an app does not exist on the server.


Note that if you have any non-alphanumeric characters such as $ or ! in your password, it might be interpreted incorrectly from the command line. To overcome this, surround your credentials, or simply the password, with single quotation marks. This will force the value to be interpreted as a single string.

About wscat

If you have not yet found or baked your own client: WebSocket cat is a nodejs tool that implements the WebSocket client (and can also act as a server). Install it with

$ npm install -g wscat

and you're good to go. See more about wscat with

$ wscat -h

https://www.npmjs.com/package/wscat

https://github.com/websockets/wscat



Other Clients

Amongst other websocket testing/debugging clients you'll find e.g. Simple WebSocket Client, which is a Chrome extension. Note that for this to work (and which is also true for other websocket clients), you'll need to pass the credentials for HTTP basic authentication in the URL itself, which is standard. These clients provide a single text field for the server location, and you'll input something like:

wss://{username}:{password}@preprod.mezzanineware.com/api/ws2/logging?appId=46942734-64e0-49cd-a83b-b0e096e372d4

Give the "Simple WebSocket Client" the wrong appId, though, and it won't show that opening the websocket stream has failed, which can mislead your debugging efforts.

Chrome Extension: Simple WebSocket Client

Script by Ryan Dewhurst



Additional Logging

In addition to the logging service described here, Helium provides some additional logging though the browser console that prints the name of the last view that was loaded by Helium. This can be used to identify which view in source code corresponds to the current app view that is presented in a browser session and can thus be used as an additional source of information when troubleshooting.