[RFC] Append a prefix to reporter methods automatically

[alvis]

Often we append the plugin name (e.g. [gatsby-plugin-your-plugin]) to a message when we log it via the reporter in the Node API.

The benefit is obvious because if we don't know where does the message come from, it misses the purpose of logging.

So why can't we have a feature that automatically appends the plugin name to each message? It will save every single plugin developer to add the prefix manually in each of the messages!

[herecydev]

I don't get how "if we don't know where does the message come from" correlates with "it misses the purpose of logging". Surely the point of logging is to get clear information across.

Is "Running static queries" not obvious, do I need to know the plugin name to know what it's doing?

In addition surely just running the following is easy:

const addPluginToLog(message) => `[My-Wonderful-Plugin] ${message}`

[alvis]

No. Admittedly it is not a difficult thing at all, both the current workaround and implementation. But it’s also a small thing most plug-in developers do today based on my observation.

The RFC here is to invite developers to post their views and help analysing the pros and cons if such idea get implemented.

[LekoArts]

It's currently not documented (and we need to change it both in the API docs and in the source plugin tutorial) but there's a reporter.setErrorMap function. Example:

gatsby/packages/gatsby-source-shopify/src/gatsby-node.ts

Lines 263 to 299 in 2eb57c7

	export function onPreInit({ reporter }: NodePluginArgs): void {
	reporter.setErrorMap({
	[errorCodes.bulkOperationFailed]: {
	text: getErrorText,
	level: `ERROR`,
	category: `USER`,
	},
	[errorCodes.apiConflict]: {
	text: (): string => shiftLeft`
	Your operation was canceled. You might have another production site for this Shopify store.
	Shopify only allows one bulk operation at a time for a given shop, so we recommend that you
	avoid having two production sites that point to the same Shopify store.
	If the duplication is intentional, please wait for the other operation to finish before trying
	again. Otherwise, consider deleting the other site or pointing it to a test store instead.
	`,
	level: `ERROR`,
	category: `USER`,
	},
	/**
	* If we don't know what it is, we haven't done our due
	* diligence to handle it explicitly. That means it's our
	* fault, so THIRD_PARTY indicates us, the plugin authors.
	*/
	[errorCodes.unknownSourcingFailure]: {
	text: getErrorText,
	level: `ERROR`,
	category: `THIRD_PARTY`,
	},
	[errorCodes.unknownApiError]: {
	text: getErrorText,
	level: `ERROR`,
	category: `THIRD_PARTY`,
	},
	})
	}

You can define custom errors with IDs and when you use error, panic or panicOnBuild. I haven't tried it with reporter.warn yet.

Anyways, it'll prefix the error with the name of the plugin:

[alvis]

@LekoArts Thanks for pointing out this method. It's an interesting API as it can give more context to each message.
I saw this mysterious API usage in some plugins before and was wondering what's that for. Now I know.

However, unfortunately, it only works with error, panic and panicOnBuild, not warn, nor info and log.
So every time you use this method, you would end up exiting the build process prematurely.

My use case is to give info when my plugin is busy fetching data from external APIs. But none of these methods is suitable.

Anyhow, for those who are interested in logging an error only, here is a minimum viable code demonstrating how it can log an erro properly.

const prefixMessage = ({ message }: { message: string }) =>
  `[gatsby-my-plugin] ${message}`;

const MessageCode = {
  APIFetchingError: `10000`
};

enum ReporterLevel {
  Debug = 'DEBUG',
  Info = 'INFO',
  Warning = 'WARNING',
  Error = 'ERROR',
}

enum ReporterCategory {
  // error caused by user such as misconfiguration
  User = 'USER',
  // third party relative to Gatsby Cloud
  ThirdParty = 'THIRD_PARTY',
  // error caused by gatsby process
  System = 'SYSTEM',
}

const ErrorMap = {
  [MessageCode.APIFetchingError]: {
    text: prefixMessage,
    level: ReporterLevel.Info,
    category: ReporterCategory.ThirdParty,
  },
};

export const onPreInit: GatsbyNode['onPreInit'] = async ({ reporter }) => {
  // old versions of Gatsby does not have this method
  if (reporter.setErrorMap) {
    reporter.setErrorMap(ErrorMap);
  }
};

Then, somewhere in your catch block, you can report an error like this:

reporter.error({
    id: MessageCode.APIFetchingError,
    context: { message: 'Something wrong with the third-party API' },
  });

[LekoArts]

If you use reporter.setErrorMap you don't need the prefixMessage as that will happen automatically.