Helium Logging Service

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

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.

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