Node.js Log Module provided by Digital Platform SRE

Lucy - a log module made by engineers for engineers provided by the Digital Platform - SRE Team

Introduction

Our module has 4 different types of information that will be logged: Types of logging.

• Session Information provided by
  • the user
  • the module
• Log Information provided by
  • the user
  • the module

Obviously the respective module info will be provided by us on the fly. For you as a dev, there is only the need for two things:

• At the very beginning of your software, some lines of codes have to specify session related information about your software
• Withtevery log message you write, you only have to call the modules's method with predefined parameteres and nothing more.

This is everything you have to do to get our full SRE Support on the platform :)

How to use the module

As we haven't deal with the IAM topic at the moment (the final concept will be in V0.4+ implemented), you currently have to include a service account key (that is provided by us) at a specific folder. To set a temp env in linux, only call the method given in step 0.

0. Install npm module

npm i @google-cloud/logging
npm i @google-cloud/monitoring
npm install mms-dp-sre-logmodule

var logging = require('mms-dp-sre-logmodule');

1. Setting ENV and register on GCP Project & set optional flag for local run

//Set Service Account for GCP
logging.setServiceAccount("/user/defined/path/nodejs-dp-play.json"); 

//Set ProjectID
logging.setGCPProjectid("gcp-project-id")

//only for LOCAL run - this will change parts in the background because not all information from K8s could be gathered etc. 
//
//for production set flag to "false" or delete line
logging.setLocalRun(true) 

//If you want to log also to stdout or stderror you can set "stdout" to "true" - by default it is set to "false"
logging.stdout(true)

//You can also deactivate logging to Stackdriver during development for example - therefore you have to set stackdriver to "false", which is "true" by default
logging.stackdriver(false)

2. Call init function for setting up Log Environment

Initialize Lucys entry function to gather environment information needed for complete log information - but you don't have to care about that - only call the init method

logger.init()

3. Write logs as a champ

/**
 * This is the single line that you use for logging with the full power of the module
 * 
 * The method is used as follows: 
 * 
 * logging.SEVERITY("Message to log", "Stacktrace -> if needed or available", "Error Trace ID")
 * 
 * */

logging.alert("This is a testmessage", "none", "35")
logging.error("second test", "null", "35") 


/**
 * You have also the possibility to log only if a condition is met, therefore you can use for every log method the conditional log method: 
 * logging.SEVERITYconditional("Message to log", "Stacktrace" -> if needed or available, "Error Trace ID", "TRUE/FALSE" -> only if parameter == true, the log will be written)
 * */

logging.alertconditional("This is a testmessage for conditional logging", "none", "35", true)

4. Description of Parameters:

• Severity - this is very important as this is one base criteria for alerting.
  • logging.debug - For debugging purposes. This severity isn't allowed in production
  • logging.default Don't use this severity. This severity isn't allowed in production
  • logging.info Use this for any message that is only for informational purpose
  • logging.warning Here you may see a problem as a result of something. But you cannot ensure something is REALLY happenning. Everything that is worse than this will be aggregated and analyzed for alertingn people.
  • logging.notice Things getting serious - you have a bad gut feeling but still cannot ensure seomthing
  • logging.alert Now you can say for sure there is something not as expected, but there isn't anything breaking.
  • logging.error There is something broken but you can handle this with your error handling
  • logging.critical There is something broken and you aren't sure if you can determine what is really going on. Be careful, some events of this will call people!
  • logging.emergency You don't know what's going on but you know the world will perish. One of this event will call a lot of people at the same time. Use this with caution.

5. Writing custom metrics

You also have the possibility to write custom logs. You only need to define what kind of metric should be written and what type of value it will be. Therefore you have the following possibilities:

Metric kinds:

• GAUGE
• DELTA
• CUMULATIVE

Value types:

• BOOLEAN,
• INT64,
• DOUBLE,
• STRING,
• DISTRIBUTION,
• UNKNOWN

To write a custom metric you only need to use the following line:

/**
 * This is the single line that you use for writing custom metrics with the full power of the module
 * 
 * The method is used as follows: 
 * 
 * logging.writeCustomMetrics("metric name", "METRIC KIND", "VALUE TYPE", "value", "metric description")
 * 
 * */

logging.writeCustomMetrics("http_requests_total", "GAUGE", "DOUBLE", "110", "This is a testdescription"); 

If you need more detailed information, or you have questions - feel free to contact us!

Release Notes

V0.0.9 (Release Date 28.02.18)

We defined basic structure of the log module and pure stackdriver log with all needed information is enabled

V1.0.0 (Release Date 05.03.2018)

We published the module to npmjs.org to make it usable via NPM

V1.0.1 (Release Date 06.03.2018)

We improoved the code with methods for reading specific ENV

V1.0.2 (Release Date 20.03.2018)

Error handling of internal error log is included

V1.0.3 (Release Date 23.03.2018)

Updated code section for gathering environment information

V1.0.4 (Release Date 26.03.2018)

Generell code improvment and implementation of API standards

V1.0.4 (Release Date 29.03.2018)

Fixed timestamp information

V1.0.5 (Release Date 03.04.2018)

Added stdout & stackdriver bool and conditional logging

V1.0.6 (Release Date 03.04.2018)

Code improvment

V1.0.7 (Release Date 03.04.2018)

Updated readme information