Add some JSDoc types to @overleaf/logger (#19153)

* Add some JSDoc types to `@overleaf/logger`

* Update `logger.error` calls

* Fixup `logger.err` JSDoc

* Update `logger.err` calls

* Fix `args` type

* Remove "Error message" description

* Replace `arguments` by actual arguments of the method

* Fix: "ESLint: Unnecessary '.apply()'.(no-useless-call)"

* Add JSDoc params to `debug` `info` `warn`

* Remove extra `args` param in JSDoc so developers aren't invited to use it

Not sure if this is the best thing to do because it creates a warning in the IDE: "Parameter args is not described in JSDoc"

* Add comment about serialization of `err` `req` `res`

* Allow strings as first param in `debug` `info` `warn`

* Fix syntax for optional parameters in JSDoc

* Add 2 signatures, to avoid "string, string" params

* Fix `@signature` names copy-pastes

Co-authored-by: Jakob Ackermann <jakob.ackermann@overleaf.com>

* Revert the double `@param attributes`. It doesn't work

---------

Co-authored-by: Jakob Ackermann <jakob.ackermann@overleaf.com>
GitOrigin-RevId: 086dee8bbf30d577c5e1f844a9df5e518c46aca7
This commit is contained in:
Antoine Clausse 2024-06-27 10:10:31 +02:00 committed by Copybot
parent 1dbbe5af9d
commit 01188589f8
4 changed files with 48 additions and 11 deletions

View file

@ -9,6 +9,9 @@ const {
} = require('./log-level-checker')
const LoggingManager = {
/**
* @param {string} name - The name of the logger
*/
initialize(name) {
this.isProduction =
(process.env.NODE_ENV || '').toLowerCase() === 'production'
@ -34,14 +37,30 @@ const LoggingManager = {
this.sentryManager = new SentryManager()
},
debug() {
return this.logger.debug.apply(this.logger, arguments)
/**
* @param {Record<string, any>|string} attributes - Attributes to log (nice serialization for err, req, res)
* @param {string} [message] - Optional message
* @signature `debug(attributes, message)`
* @signature `debug(message)`
*/
debug(attributes, message, ...args) {
return this.logger.debug(attributes, message, ...args)
},
info() {
return this.logger.info.apply(this.logger, arguments)
/**
* @param {Record<string, any>|string} attributes - Attributes to log (nice serialization for err, req, res)
* @param {string} [message]
* @signature `info(attributes, message)`
* @signature `info(message)`
*/
info(attributes, message, ...args) {
return this.logger.info(attributes, message, ...args)
},
/**
* @param {Record<string, any>} attributes - Attributes to log (nice serialization for err, req, res)
* @param {string} [message]
*/
error(attributes, message, ...args) {
if (this.ringBuffer !== null && Array.isArray(this.ringBuffer.records)) {
attributes.logBuffer = this.ringBuffer.records.filter(function (record) {
@ -54,14 +73,29 @@ const LoggingManager = {
}
},
err() {
return this.error.apply(this, arguments)
/**
* Alias to the error method.
* @param {Record<string, any>} attributes - Attributes to log (nice serialization for err, req, res)
* @param {string} [message]
*/
err(attributes, message, ...args) {
return this.error(attributes, message, ...args)
},
warn() {
return this.logger.warn.apply(this.logger, arguments)
/**
* @param {Record<string, any>|string} attributes - Attributes to log (nice serialization for err, req, res)
* @param {string} [message]
* @signature `warn(attributes, message)`
* @signature `warn(message)`
*/
warn(attributes, message, ...args) {
return this.logger.warn(attributes, message, ...args)
},
/**
* @param {Record<string, any>} attributes - Attributes to log (nice serialization for err, req, res)
* @param {string} [message]
*/
fatal(attributes, message) {
this.logger.fatal(attributes, message)
if (this.sentryManager) {

View file

@ -165,7 +165,7 @@ if (!module.parent) {
// Called directly
app.listen(port, host, error => {
if (error) {
logger.error('Error starting Filestore', error)
logger.error({ err: error }, 'Error starting Filestore')
throw error
}
logger.debug(`Filestore starting up, listening on ${host}:${port}`)

View file

@ -35,7 +35,10 @@ module.exports = {
if (url === '/check') {
if (!language) {
logger.error('"language" field should be included for spell checking')
logger.error(
{},
'"language" field should be included for spell checking'
)
return res.status(422).json({ misspellings: [] })
}

View file

@ -119,7 +119,7 @@ const main = async () => {
if (require.main === module) {
main()
.then(() => {
logger.error('Done.')
logger.info('Done.')
process.exit(0)
})
.catch(err => {