DE4A Logs and error messages
Overview
In order to standardise the errors and logs handled by each component, some conventions have been taken, as log patterns, error codes definition or messages content.
The information on this page should be used by each partner who develops a DE4A component, also it should be maintained to have a proper messages reference and be aware which information will include.
Apart from the usual reasons of the logging and error handling, in the DE4A project, there are 3 main bullet points on which the definition of messages is based:
- Kafka tracking: messages sent to the Kafka server which can be previewed at: https://de4a-dev-pt.egovlab.eu/#!detail
- Metrics logs: messages marked with a special tag inside the common log file or logged on a separated file, which will be used to analyze and raise some metrics about each system
- Error convention: standardise the error messages and codes
Structure definition
This section will describe the hierarchy and model followed to build the different logs and messages. There are multiple patterns depending on the message nature, but the following tables will be a common reference to understand the rest of information collected in the page.
Layer
The layer concept will be used to name the system level where the message comes from.
| Layer | Layer Code | Description |
|---|---|---|
| Communication | 1 | External connections/communications performed by the Connector |
| Internal failure | 2 | Internal failure of the Connector to be handled and stored in ErrorTypes wrapped in DE4A responses |
| Configuration | 3 | Unexpected situation due to a missing configuration paramater |
| Business | 4 | Unsuccessful situation on the business flow |
Module
A reference to each DE4A module possibly involved in an interaction. A "None" element has been included to represent the situation where a message occurs internally in a certain component.
| Module Name | Module Code |
|---|---|
| IDK | 01 |
| SMP | 02 |
| Connector DR | 03 |
| Connector DT | 04 |
| Data Owner | 05 |
| Data Evaluator | 06 |
| None | 07 |
Type
It is mean to use just for the Connector log messages (metrics and Kafka).
| Log Type | Type code |
|---|---|
| Services | 01 |
| Client | 02 |
| AS4 | 03 |
Error messages
As part of the logging standardisation, some error messages templates have been defined. Those messages will be thrown by each component with the corresponding parameterisation.
| Error message | Code | Parameters |
|---|---|---|
| Service requested {0} not found | 01 | {0}: REST service requested |
| Arguments missing or invalid at {0} - {1} | 02 | {0}: Service requested
{1}: Missing arguments |
| Connection error with {0} - {1} | 03 | {0}: Module name
{1}: Inherited error message |
| Error on response from {0} - {1} | 04 | {0}: Module name
{1}: Inherited error message |
| Object conversion error on {0} - {1} | 05 | {0}: Module name
{1}: Inherited error message |
| Error accessing/saving data on {0} - {1} | 06 | {0}: Module name
{1}: Inherited error message |
| Scheme validation failed for {0} message - {1} | 07 | {0}: Message type
{1}: Inherited error message |
| Error occurred on AS4 Gateway to {0} - {1} | 08 | {0}: Module name
{1}: Inherited error message |
| Failed to establish user identity | 09 | - |
| Error extracting evidence | 10 | - |
| Error in identity matching | 11 | - |
| Unsuccessful completion of preview | 12 | - |
| Preview rejected by user | 13 | - |
| Failed to re-establish user identity | 14 | - |
| Evidence not available yet (delayed) | 15 | - |
| Unsuccessful generation of the canonical evidence | 16 | - |
Connector
Specific messages for the Connector. Each component around the Connector should be aware of the codes and content of these messages to act accordingly on each case.
Error messages
| Layer | #Layer | Module | #Module | Error type | # | Error Code |
|---|---|---|---|---|---|---|
| Communications | 1 | None | 00 | Service requested {0} not found | 01 | 10001 |
| Communications | 1 | None | 00 | Scheme validation failed for {0} message - {1} | 07 | 10007 |
| Communications | 1 | IDK | 01 | Service requested {0} not found | 01 | 10101 |
| Communications | 1 | IDK | 01 | Arguments missing or invalid at {0} - {1} | 02 | 10102 |
| Communications | 1 | IDK | 01 | Error on response from {0} - {1} | 04 | 10104 |
| Communications | 1 | IDK | 01 | Connection error with {0} - {1} | 03 | 10103 |
| Communications | 1 | IDK | 01 | Scheme validation failed for {0} message - {1} | 07 | 10107 |
| Communications | 1 | SMP | 02 | Error on response from {0} - {1} | 04 | 10204 |
| Communications | 1 | SMP | 02 | Service requested {0} not found | 01 | 10201 |
| Communications | 1 | SMP | 02 | Connection error with {0} - {1} | 03 | 10203 |
| Communications | 1 | SMP | 02 | Scheme validation failed for {0} message - {1} | 07 | 10207 |
| Communications | 1 | Data Owner | 05 | Connection error with {0} - {1} | 03 | 10503 |
| Communications | 1 | Data Owner | 05 | Service requested {0} not found | 01 | 10501 |
| Communications | 1 | Data Owner | 05 | Error accessing/saving data on {0} - {1} | 06 | 10506 |
| Communications | 1 | Data Owner | 05 | Error on response from {0} - {1} | 04 | 10504 |
| Communications | 1 | Data Owner | 05 | Scheme validation failed for {0} message - {1} | 07 | 10507 |
| Communications | 1 | Data Evaluator | 06 | Service requested {0} not found | 01 | 10601 |
| Communications | 1 | Data Evaluator | 06 | Error on response from {0} - {1} | 04 | 10604 |
| Communications | 1 | Data Evaluator | 06 | Connection error with {0} - {1} | 03 | 10603 |
| Communications | 1 | Connector DR | 03 | Error occurred on AS4 Gateway to {0} - {1} | 08 | 10308 |
| Communications | 1 | Connector DT | 04 | Error occurred on AS4 Gateway to {0} - {1} | 08 | 10408 |
| Internal failure | 2 | None | 00 | Object conversion error on {0} - {1} | 05 | 20005 |
| Internal failure | 2 | None | 00 | Error accessing/saving data on {0} - {1} | 06 | 20006 |
| Internal failure | 2 | None | 00 | Error occurred on AS4 Gateway to {0} - {1} | 08 | 20008 |
| Internal failure | 2 | None | 00 | Object conversion error on {0} - {1} | 05 | 20005 |
| Configuration | 3 | None | 00 | Error occurred on AS4 Gateway to {0} - {1} | 08 | 30008 |
Log messages
Messages meant to be sent to the Kafka server and also to be printed at the logging files of the Connector.
| Message | #Message | Type | #Type | Parameters | Log code |
|---|---|---|---|---|---|
| RequestTransferEvidenceIM message received: Request ID: {0}, Canonical Evidence Type: {1}, Data Evaluator: {2}, Data Owner: {3} | 01 | Services | 01 | {0}: RequestId
{1}: CanonicalEvidenceType {2}: DataEvaluator {3}: DataOwner |
0101 |
| RequestTransferEvidenceUSI message received - Request ID: {0}, Canonical Evidence Type: {1}, Data Evaluator: {2}, Data Owner: {3} | 02 | Services | 01 | {0}: RequestId
{1}: CanonicalEvidenceType {2}: DataEvaluator {3}: DataOwner |
0102 |
| RequestTransferEvidenceUSIDT message received - Request ID: {0} | 03 | Services | 01 | {0}: RequestId | 0103 |
| RequestLookupRoutingInformation message received - Canonical Evidence Type: {0}, Country Code: {1}, Data Owner: {2} | 04 | Services | 01 | {0}: CanonicalEvidenceType
{1}: CountryCode {2}: DataOwnerId |
0104 |
| Sending request to IDK - URL: {0} | 05 | Services | 01 | {0}: URL | 0105 |
| Looking for Data Owner address - Data Owner: {0} | 06 | Services | 01 | {0}: DataOwnerId | 0106 |
| Data Owner address not found - Data Owner: {0} | 07 | Services | 01 | {0}: DataOwnerId | 0107 |
| Requesting to SMP - Participant: {0}, Document Type: {1}, Message Type: {2} | 01 | Client | 02 | {0}: ParticipantId
{1}: DocumentTypeId {2}: MessageType |
0201 |
| Sending RequestForwardEvidence to the Data Evaluator - Request ID: {0}, Data Evaluator: {1}, Data Owner: {2}, Endpoint: {3} | 02 | Client | 02 | {0}: RequestId
{1}: DataEvaluatorId {2}: DataOwnerId {3}: Endpoint |
0202 |
| Sending RequestExtractEvidence IM to the Data Owner - Request ID: {0}, Canonical Evidence Type: {1}, Data Evaluator: {2}, Data Owner: {3}, Endpoint: {4} | 03 | Client | 02 | {0}: RequestId
{1}: CanonicalEvidenceType {2}: DataEvaluatorId {3}: DataOwnerId {4}: Endpoint |
0203 |
| Sending RequestExtractEvidence USI to the Data Owner - Request ID: {0}, Canonical Evidence Type: {1}, Data Evaluator: {2}, Data Owner: {3}, Endpoint: {4} | 04 | Client | 02 | {0}: RequestId
{1}: CanonicalEvidenceType {2}: DataEvaluatorId {3}: DataOwnerId {4}: Endpoint |
0204 |
| Sending request message via AS4 gateway - Data Evaluator: {0}, Data Owner: {1}, Canonical Evidence Type: {2} | 01 | AS4 | 03 | {0}: DataEvaluatorId
{1}: DataOwnerId {2}: CanonicalEvidenceType |
0301 |
| Sending response message via AS4 gateway - Data Evaluator: {0}, Message type: {1}, Canonical Evidence Type: {2} | 02 | AS4 | 03 | {0}: DataEvaluatorId
{1}: Message tag {2}: CanonicalEvidenceType |
0302 |
| Processing the request received via AS4 gateway - Request ID: {0} | 03 | AS4 | 03 | {0}: RequestId | 0303 |
| Processing the response received via AS4 gateway - Request ID: {0} | 04 | AS4 | 03 | {0}: RequestId | 0304 |
Examples
- Kafka
2021-08-09 14:15:51:657: [de4a-connector-sgad] [INFO] RequestTransferEvidenceUSIDT message received - Request ID: 2ecda60e-3824-4e92-a459-7c4a81258952
- Internal log
[2021-07-13 14:15:51:657] [INFO] [0103] RequestTransferEvidenceUSIDT message received - Request ID: 2ecda60e-3824-4e92-a459-7c4a81258952 - Extra technical information (java source and execution thread)
Final participants DE/DO
The proposal includes specific messages to the final participants which would be part of the metrics and statistics collection. Some basic messages have been defined to identify the possible situations at the Data Evaluator and Data Owner's.
Error warning and local logs to collect
| Layer | #Layer | Module | #Module | Error Type | #Type | #Code |
|---|---|---|---|---|---|---|
| Business | 4 | Data Evaluator | 06 | Failed to establish user identity | 09 | 40609 |
| Business | 4 | Data Owner | 05 | Error extracting evidence | 10 | 40510 |
| Business | 4 | Data Owner | 05 | Evidence not available yet (delayed) | 15 | 40515 |
| Business | 4 | Data Owner | 05 | Error in identity matching | 11 | 40511 |
| Business | 4 | Data Owner | 05 | Unsuccessful completion of preview | 12 | 40512 |
| Business | 4 | Data Owner | 05 | Failed to re-establish user identity | 14 | 40514 |
| Business | 4 | Data Owner | 05 | Preview rejected by user | 13 | 40513 |
| Business | 4 | Data Evaluator | 06 | Preview rejected by user | 13 | 40613 |
| Business | 4 | Data Owner | 05 | Unsuccessful generation of the canonical evidence | 16 | 40516 |