Amadis

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Current »

What to include when reporting a technical issue?

This section describes the information that must be included when reporting any issues to the technical support. Depending on the type of issue, the required information is different. Additional information may be requested by the technical support afterwards.

An API call fails

If an API call fails, the following artifacts shall be included in the incident report:

  • A description of what you were trying to accomplish

  • the API call URL. Mask the token value if its value is sensitive or at least a part of it. Leave the token tag.

  • The API call payload

  • The Detailed View of the all the related Application Log Entries which include success and failure messages

  • If the return code from the server is 500, the error logs from Apache2 on Atheos Server are required.

  • Optionally, a database dump may be given. It might be requested if further information is required to complete the investigation.

An API call doesn’t return the expected results

If an API call doesn’t return the expected results, the following artifacts shall be included in the incident report:

  • A description of what you were trying to accomplish

  • The expected results including the difference between the actual results and the expected ones.

  • The API call URL. Mask the token value if its value is sensitive or at least a part of it. Leave the token tag.

  • The API call payload

  • the Detailed View of the all the related Application Log Entries which include success and failure messages

  • Optionally, a database dump may be given. It might be requested if further information is required to complete the investigation.

A POI configuration is missing some parameters

Take note that a POI configuration will be made available up to 2 minutes after it has been deployed.

The artifacts to join to the incident report are:

  • What are the missing parameters including their names and values.

  • AtheosGateway Controller Logs. Their location and an example are given below.

  • AtheosGateway Control files. Their location and an example are given below.

  • The POI configuration files. The complete structure shall be included with the incident report. Their location and an example are given below

  • Optionally, a database dump may be given. It might be requested if further information is required to complete the investigation.

A POI doesn’t get a newly deployed configuration

In this case, a few things could have gone wrong.

  • The deployment failed

  • The configuration building process failed

  • Atheos Gateway could not deliver the configuration

The deployment failed

The deployment may have failed in Atheos Server. Depending on the failure message, more artifacts might be required. So, any incident report shall include:

  • the Detailed View of the all the related Application Log Entries which include success and failure messages

  • The POI configuration files. The complete structure shall be included with the incident report. Their location and an example are given below.

  • Optionally, a database dump may be given. It might be requested if further information is required to complete the investigation.

The configuration building process failed

The POI configuration has not been created. Take note that a POI configuration will be made available up to 2 minutes after it has been deployed. The artifacts to join to the incident report are:

  • AtheosGateway Controller Logs. Their location and an example are given below.

  • AtheosGateway Control files. Their location and an example are given below.

  • The POI configuration files. The complete structure shall be included with the incident report. Their location and an example are given below.

Atheos Gateway could not deliver the configuration

The artifacts to join to the incident report are:

  • Any messages exchanged between the POI and AtheosGateway. Their location and an example are given below.

  • Atheos Gateway logs. Their location and an example are given below.

  • The POI configuration files. The complete structure shall be included with the incident report. Their location and an example are given below.

The POI doesn’t get configured even if it has received its configuration

This problem is likely caused by an incompatible configuration.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

The artifacts to join to the incident report are:

  • The POI configuration files. The complete structure shall be included with the incident report. Their location and an example are given below.

The POI crashes when it receives its configuration

It is probably caused by a faulty configuration. So, include the following to the incident report.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

The artifacts to join to the incident report are:

  • The POI configuration files. The complete structure shall be included with the incident report. Their location and an example are given below.

UI Crashes

UI crashes mainly happen when a user tries to perform an action using the UI and an issue with the application triggers a UI crash. These issue shall always be reported to the technical support.

The following information should be included in the incident report:

  • A description of what the user was trying to accomplish and what was the expected results.

  • The URL on which the error occurred.

  • A screenshot of the crash dump. An example is given below.

Security Violation

A security violation occurs when a user tries to perform an action from the user’s interface. Prior to reporting the issue to the technical support, the roles and users definitions shall be review. Technical support shall be notified if the application doesn’t behave as expected. A security violation message looks like:

The following information should be included in the incident report:

  • A description of what the user was trying to accomplish

  • The detailed view of the corresponding Application Log entry. An example is given below.

Artifact Examples and Locations

UI Crash Dump

This artifact is displayed in the user’s browser window.

Security Violation Application Log Entry

The application log can be access using the Atheos UI under System Admin. >> Application Logs. The detailed view of an Application Log Entry related to a Security Violation looks like:

AtheosGateway Controller Logs

This log is located generally on each AtheosGateway instances in the directory /var/log/amadis. Its file name is AtheosGWController.log. If your installation has more than one AtheosGateway, include all of them with the incident report.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

The content of this log among other things will contains lines like

2020-03-30 18.05.02 I Processing file 20200330-180408-b512706d-8e2f-4487-89b5-8b3bdb6d2950
2020-03-30 18.05.02 I Deploying CARNET11
2020-03-30 18.06.01 I Processing file 20200330-180408-b512706d-8e2f-4487-89b5-8b3bdb6d2950
2020-03-30 18.06.01 I Deploying CARNET11
2020-03-31 14.12.01 I Processing file 20200331-141110-3db95d3d-a886-4995-b222-7e90fcc98fa0
2020-03-31 14.12.01 I Deploying CARNET11
2020-03-31 14.12.01 I Processing file 20200331-141135-037a8b67-378f-4672-aa41-cda294667530
2020-03-31 14.12.01 I Deploying CARNET11
2020-03-31 18.43.01 I Processing file 20200331-184231-ffaf8164-8381-453c-953b-5306f5ca947b
2020-03-31 18.43.01 I Deploying CARNET11
AtheosGateway Controller command files

AtheosGateway Control Files

The processed command files are listed in the AtheosGateway Controller Logs. The processed files are stored in the directory /home/amadis/control/attic or may still be in the /home/amadis/control directory if the issue prevented from moving it into the attic sub-directory.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

Find the files related to the POI having an issue and include them to the incident report.

This file is a JSON file without any formatting. A typical file starts with:

{"version":1,"actions":[{"action":"DeployPOI","payload":{"version":"2021-03-10 18:04:22","profileData":{"version":"2021-03-10 18:04:22","profileId":"3","templateE0":"df140004434f5252\ndf15000356414c\ndf16000156\
n","templateE1":"9f4000056000f0a001\ndf1200026672\ndf670004fc020000\ndf17000101\ndf18000101\ndf40002aa000000003008ca000000003008da0000000030096a0000000040002a0000000420002a0000000420003\ndf490015a000000003008ca0
000000040002a0000000420002\n9f330003e0b8c8\n9f1a00020250\ndf34

Messages exchanged between the POI and AtheosGateway

They can be retrieved from the Atheos Server User’s interface under POIS >> Nexo Messages. Find the messages related to the POI you are trying to configure and join to the incident report:

  • The detailed view of the message

  • A text version (cut/paste) of the message itself labelled “Nexo Message” in the detailed view.

Take note that the messages are sent to Atheos Server within 2 minutes after they were generated.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

If no messages are found, send the content of the directory structure typically found in /home/amadis/files . They may be “stuck” into this directory structure.

Atheos Gateway logs

The Atheos Gateway logs contains the connection log with the POIS. It is typically found in the /var/log/amadis directory structure. Their naming convention is atheosgw.log.*. Include all the relevant files in the incident report.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

A typical file looks like:

2020-08-04 12.07.35 I Atheos Gateway 02.01.05 started using configuration /etc/amadis/atheosgw.conf
2020-08-04 12.07.35 I Copyright ©2005-2020 - 9164-4187 QUEBEC INC (“AMADIS”), All Rights Reserved
2020-08-04 16.40.01 I Accepted a connection from 70.80.252.205, port 3992
2020-08-04 16.40.01 I Connection closed by peer 70.80.252.205, port 3992
2020-08-04 16.40.01 I Closing the connection with 70.80.252.205, port 3992
2020-08-04 16.40.23 I Accepted a connection from 70.80.252.205, port 56200
2020-08-04 16.40.23 I Connection closed by peer 70.80.252.205, port 56200
2020-08-04 16.40.23 I Closing the connection with 70.80.252.205, port 56200
2020-08-04 16.43.58 I Accepted a connection from 70.80.252.205, port 41903
2020-08-04 16.43.59 I Connection closed by peer 70.80.252.205, port 41903
2020-08-04 16.43.59 I Closing the connection with 70.80.252.205, port 41903
2020-08-04 16.46.26 I Accepted a connection from 70.80.252.205, port 48512
2020-08-04 16.46.26 I Connection closed by peer 70.80.252.205, port 48512
2020-08-04 16.46.26 I Closing the connection with 70.80.252.205, port 48512
2020-08-04 17.10.33 I Accepted a connection from 70.80.252.205, port 58263
2020-08-04 17.10.33 I Connection closed by peer 70.80.252.205, port 58263
2020-08-04 17.10.33 I Closing the connection with 70.80.252.205, port 58263

POI configuration files

The POI configuration files are typically found in the directory /home/amadis/poi/????? where ????? is the POI ID. The complete structure shall be included with the incident report.

If your installation has more than one AtheosGateway, include the artifacts of all them with the incident report.

It contains 2 sub-directories with files having the date and time as the filename and an .FIN extension. They contain some XML fragment as shown below.

MgtPlan subdirectory

A typical file looks like:

<DataSet><Id><Nm>Management Plan</Nm><Tp>MGTP</Tp><Vrsn>2021-01-28 21:49:45</Vrsn><CreDtTm>2021-01-28T21:52:01</CreDtTm></Id><Cntt><Actn><Tp>DWNL</Tp><TermnlMgrId><Id>ATHEOS-TMS</Id><Tp>MTMG</Tp></TermnlMgrId><D
ataSetId><Tp>PARA</Tp><Vrsn>2021-01-28 21:49:45.FIN</Vrsn><CreDtTm>2021-01-28T21:52:01</CreDtTm></DataSetId><ReTry><Dely>00000001</Dely><MaxNb>3</MaxNb></ReTry><Trggr>MANU</Trggr></Actn></Cntt></DataSet>

Param subdirectory

A typical file starts with:

<DataSet><Id><Tp>PARA</Tp><Vrsn>2021-01-28 21:49:45</Vrsn><CreDtTm>2021-01-28T21:52:01</CreDtTm></Id><POIId><Id>SOFT0003</Id><Tp>OPOI</Tp><ShrtNm>SoftPOI #3</ShrtNm></POIId><Cntt><RplcCfgtn>true</RplcCfgtn><Mrch
ntParams><ActnTp>UPDT</ActnTp><MrchntId>00000NEXOMER001</MrchntId><Vrsn>2021-01-28 21:49:45</Vrsn></MrchntParams><TMSPrtcolParams><ActnTp>UPDT</ActnTp><TermnlMgrId><Id>ATHEOS-TMS01</Id></TermnlMgrId><MntncSvc>MT
MG</MntncSvc><Vrsn>2021-01-28 21:49:45</Vrsn><HstId>TMS001</HstId></TMSPrtcolParams><HstComParams><ActnTp>UPDT</ActnTp><HstId>TMS001</HstId><Adr><Adr><NtwkTp>IPNW</NtwkTp><AdrVal>51.79.49.100:1054</AdrVal></Adr>
</Adr></HstComParams>

Apache2 error log

They are typically found in /var/log/apache2/error.log. The filename may be different depending on your installation. These logs are particularly important when Atheos Server returns a 500 error code.

[Wed Mar 31 00:00:01.739566 2021] [mpm_prefork:notice] [pid 1670] AH00163: Apache/2.4.41 (Ubuntu) configured -- resuming normal operations
[Wed Mar 31 00:00:01.739591 2021] [core:notice] [pid 1670] AH00094: Command line: '/usr/sbin/apache2'
[Thu Apr 01 00:00:02.441062 2021] [mpm_prefork:notice] [pid 1670] AH00171: Graceful restart requested, doing restart
AH00112: Warning: DocumentRoot [/var/www/html/atheosserver/public] does not exist
AH00112: Warning: DocumentRoot [/var/www/html/PoiMessagesSinkHole] does not exist
AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to suppress this message
  • No labels