1.0.0 • Published 3 years ago
@elliemae/pui-logger v1.0.0
UI Logger
Logging spec
Web applications shall produce only structured log records in a standard JSON format.
Log records shall be organized into types. Each type is identified by a code. The type code is globally unique.
All log records have a standard set of fields. But each type may have its data schema in its data structure.
The type largely replaces the message.
Each web application shall publish its log record types in a log record catalog.
Having a standard, structured, and schema-driven logging format has the following benefits:
- Makes support tasks easier, as it allows smooth transition between different applications and services when inspecting the log files due the consistency of its structure and properties
- Easier automation of log related tasks, such as: log filters, queries and alerts in systems like Kibana or Splunk.
- Easier processing and aggregation of log data
- Allows non-engineering support staff to more easily understand the significance of specific log records
{
"emLog": "1.0",
"index": "pui",
"time": "2001-07-04T12:08:56.235Z",
"code": "puiweb001",
"message": "An attempt to approve loan failed",
"severity": "error",
"logger": "ice.pui.logger",
"team": "LOC",
"appName": "LOC.Pipeline",
"appVersion": "21.1.0",
"correlationId": "ac0676c1304e47e997451fa3ddd21cb8",
"instanceId": "lmAcme",
"userId": "jdoe",
"puiweb001": {
"loanId": "102034356",
}
}Log record format
The log record format is identified by a root field called emLog. The value of this field is the version of the format.
The format calls for the following fields.
All properties are mandatory unless otherwise noted.
| Property | Definition | Examples |
|---|---|---|
| emLog | The version of the overall log record schema that we are using | 1.0 |
| time | The timestamp when the log record is emitted in ISO 8601 format, ideally with millisecond level resolution, with time zone specifier. yyyy-MM-dd'T'HH:mm:ss.SSS'Z' | |
| code | A code uniquely identifying record type.The format is [product][app][number], where [product] and [app] are each three-character alphanumerical strings and [number] is a 3-digit number. The context refers to the bounded context to which the web application belongs. If this is a framework-generated log entry, product becomes pui | puiweb001locpip002 |
| message | Optional. Describes the current log record type.It could also be a free-form message that is only used when severity is DEBUG and type/data properties are absent. This field is intended to allow developers to create short-term debug log records more easily. Structured log records with strict schema is required for all other levels. | "GetLoans method entered""GetLoans method finished with 14 loans returned." |
| severity | One of the standard severity levels defined in this document. See Severities | infowarn |
| logger | The fully qualified name of the logger or class that emitted the log record. | ice.pui.logger |
| team | An identifier of the team that owns the current web application, in camelCase | LOCECC |
| appName | The unique name of the web application, optimally qualified with a bounded context name. | LOC.PipelineECC.Admin |
| appVersion | The release version of the web application that generated the log record. | 20.2.121.1.0 |
| correlationId | Unique correlation id associated with a user generated request. This correlation id should have the same value in all the log records produced within the scope of the same request, across multiple services. Should be a 128-bit (32-digit) hexadecimal string without dashes. | 1ce99b3cc5c6416a82e748ad5daecdfa |
| instanceId | Optional. The identifier of the client/customer that is in context when this log record is generated. | 72a79e56lmacmeBE924939 |
| userId | Optional. The identifier of the user that in context when this log record is generated. | 718182801 |
| type-specific data | Optional. The key is the same as the code of the record type. A JSON object containing the type-specific data of the log record that are not covered by the standard fields. | {"loanId":"1232121"} |
| context | Optional. A map that contains additional contextual data not specific to the record type and not covered by any of the root-level fields. Values must be strings to avoid type collisions. |
Severities
Services shall output only the following severity levels, and these are their definitions:
| Level | Definition |
|---|---|
| TRACE | Informational events that do not need to appear in production logs; finer-grained than debug |
| DEBUG | Informational events that do not need to appear in production logs |
| INFO | Informational events that must appear in production logs |
| WARN | A possible error condition that might indicate a problem; it doesn't necessarily need to be addressed. |
| ERROR | A definite error condition that must be addressed. It interrupts the current operation but does not cause the entire service to crash. |
1.0.0
3 years ago