# Logging and Tracing

### Purpose

The purpose of this document is to describe how microservices should log. As a note, this excludes infrastructure containers since they all have their own log formats. The goal of having a standard logging format for containers is to allow for easier debugging.

### Log Levels

The following standard log levels will be used. A description of each level will also be provided

<table border="1" id="bkmrk-fatal-very-sever-err" style="border-collapse: collapse; width: 100%; height: 178.8px;"><colgroup><col style="width: 10.0618%;"></col><col style="width: 90.0618%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">**FATAL**</td><td style="height: 29.8px;">Very sever errors that will lead to the application crashing. </td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">**ERROR**</td><td style="height: 29.8px;">Events that could be fatal but also allow the application to continue running.</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">**WARN**</td><td style="height: 29.8px;">Events that could lead to potentially harmful situations.</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">**INFO**</td><td style="height: 29.8px;">Informational messages that highlight the current state of the application</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">**DEBUG**</td><td style="height: 29.8px;">Events that will be useful for a developer when debugging</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">**TRACE**</td><td style="height: 29.8px;">Events that provides finer detail than DEBUG. This could be a dump of a data structure, progress of a task ect.</td></tr></tbody></table>

### Standard Logging Format

The standard log format for all services will be a JSON object:

```json
{
	"timestamp": "2022-09-22T10:33:20.123456",
	"level": "FATAL|ERROR|WARN|INFO|DEBUG|TRACE",
	"service": "my-microservice",
	"session_id": "7cddeb94-4d9b-4231-bb5a-2c9ce889926c",
	"user_agent": "User agent here",
	"method": {
		"name": "someMethod",
		"args": ["some", "args"]
	},
	"message": "some super cool message",
  	"stacktrace":"the stacktrace here if there is an error"
}
```

### PII (Personally Identifiable Information)

Personally Identifiable Information shall be removed from all logs. Some PII includes:

- Username
- Passwords
- API Tokens
- API Keys
- Names
- Age
- Addresses
- Phones
- SSN
- Bank account numbers
- Credit card numbers
- Biometric data
- Geographic data
- Date of birth
- ect

If PII should be put in a log message it should be changed to have only 5 \* characters. For instance, the full name "Kyle Heestand" would become "\*\*\*\*\*". This is to not only protect against the data in the database, but also to protect against people guessing who/what the data is based on the size of it. As an example, take a standard login message:

```
{
	"timestamp": "2022-09-22T10:33:20.123456",
	"level": "INFO",
	"service": "LoginService",
	"session_id": "7cddeb94-4d9b-4231-bb5a-2c9ce889926c",
	"user_agent": "User agent here",
	"method": {
		"name": "login",
		"args": ["kheestand", "some-password"]
	},
	"message": "Kyle Heestand has logged in"
}
```

After removing the PII, we will get something like this:

```
{
	"timestamp": "2022-09-22T10:33:20.123456",
	"level": "INFO",
	"service": "LoginService",
	"session_id": "7cddeb94-4d9b-4231-bb5a-2c9ce889926c",
	"user_agent": "User agent here",
	"method": {
		"name": "login",
		"args": ["*****", "*****"]
	},
	"message": "***** has logged in"
}
```

Obviously, you would more than likely have a different message, but we can see that the user's username, password and full name has been removed to preserve their privacy.