API logs - Best practices

How to log information in APIs?

Logging the right information will save you hours of debugging and improve code flow visibility.

• Do not console.log or println etc... Because,
  • These logs are directly added to the terminal where the server runs.
  • This is difficult to read and record.
• Use a library or create a separate service for logging. Better to save them in a separate file at a secure location if not using any existing libraries.
• Avoid logging sensitive data. Like,
  • usernames
  • tokens
  • password
  • Database config data
• Avoid logging each stage of the API like, starting, started, processing, done. Instead add details like,
  • Non-sensitive but critical input data that determine the API flow. Ex: flags or reference ids.
  • Log any third party integrated APIs. Ex: "Firebase Authentication response: 200 success", but do not log the actual response.
• Make it as meaningful as possible with limited data.
• Add a header for easy filtering. Ex: "Login API: ...." or "Get user details: ...
• Add enough facts or information for debugging the issue. Not just plain sentences like as it will be easy to cross refer and confirm the understanding. Ex:
  • Avoid: "Received response from firebase"
  • Better: "User authenticated by firebase: " or "Firebase authentication failed: "
• Add only suspicious or areas where logs could help. Ex: Third party integration - It will help decide if our code went wrong or third party API returned wrong.
  • Avoid adding in simple get APIs. Where there is no much data processing, only data retrieving. So, no need of detailed logging here.
• Do not forget to remove when not necessary. It will save a log of time when viewing and filtering the logs.
• Do not add logs in core areas like (index.js, routes, middlewares, etc…)

Log types

• Error: This is used when you need to log any error like DB connection failed or uncaught error thrown.
• Debug: This is debugging logs. This is used to log any information that can will used for better understanding of the API flow. Ex: "Third party auth succeed".
• Warn: This is used when logging issues that may or suspected to cause issues. Like malformed data from any third party or any API header missing.
• Log: This is a general log type.