react-native-xlogger v1.1.11
react-native-xlogger
A very simple logger for React Native that supports console, Reactotron and Sentry. There are more complex loggers available that support pluggable transport. This ain't that.
If you're looking for a more feature rich logger that supports multiple, and self-written, transports, check out: https://github.com/onubo/react-native-logs.
TL;DR;
- Import and configure XLogger
- Calls to
XLogger.logXXX
will then format and forward messages toconsole
, Reactotron and Sentry depending on the config and log level settings.
import * as XLogger from 'react-native-xlogger';
const { LogLevel } = XLogger;
XLogger.configure({
logLevel: __DEV__ ? LogLevel.silly : LogLevel.warn,
printLogLevel: true,
printLogTime: true,
useSentry: true,
useReactotron: __DEV__,
reactotronInstance: __DEV__ ? configuredReactotron : undefined,
});
XLogger.silly('This is a silly message');
// squelch the logger
XLogger.setLogLevel( LogLevel.silent );
Log Levels
RNX supports the following log levels:
LogLevel.silent
: all logs, except direct logs (see below), are squelchedLogLevel.error
: equivalent ofconsole.error
. Maps toSeverity.Error
for SentryLogLevel.warn
: equivalent ofconsole.warn
. Maps toSeverity.Warning
for SentryLogLevel.debug
: equivalent ofconsole.log
. Maps toSeverity.Debug
for SentryLogLevel.info
: equivalent ofconsole.log
. Maps toSeverity.Log
for SentryLogLevel.verbose
: equivalent ofconsole.log
. Maps toSeverity.Debug
for SentryLogLevel.silly
: equivalent ofconsole.log
. Maps toSeverity.Debug
for Sentry
When a log level is set for RNX, messages of that level and above are enabled. For example, if you set the
log level to debug
then only debug
, warn
and error
messages will be logged.
Sentry has additional default squelch settings in order to reduce noise on the Sentry Dashboard (see below).
Console Logger
RNX uses console
to log to the JS console. The method chosen (.log
, .warn
or .error
) depends on the log level
and the useCorrespondingConsoleMethod
config boolean. You may want to disable the corresponding method feature,
and use only console.log
, if your app is throwing a lot of noisy red/yellow screen RN errors.
Log Level | useCorrespondingConsoleMethod | console method |
---|---|---|
error | true | console.error |
false | console.log | |
warn | true | console.warn |
false | console.log | |
All others | true /false | console.log |
The console logger also supports prepending string messages with time and/or log level.
Setting printLogLevel
to true will prepend strings with the level. For example:
[ warn ] Something possibly bad happened.
Setting printLogTime
to true will prepend strings with the current hh:mm:ss.ms
. For example:
[ 13:27.51.265 ] Something happened.
They can be combined:
[ 13:27.51.265 ][ error ] Something bad happened around 130 PM.
Note: Prepending with the time and level is only for console logs. Reactotron and Sentry have their own mechanisms for this. Also, prepending does not occur for parameters that are not a string or number (for obvious reasons).
Reactotron Logger
One of the reasons XLogger was written was to avoid the suggested "monkey patching" of console
by the
Reactotron team ("console.tron
"). In XLogger, all Reactotron calls are wrapped to enable easy disable of Reactotron
in production. This wrapping also checks to see whether a configured Reactotron instance exists before trying to
log. The monkey patching approach does not do this, and can result in crashes.
To enable Reactotron logging, you must pass both a configured Reactotron instance and enable it with the useReactotron
flag. In addition, you can directly access special purpose Reactotron log methods via the XLogger.reactotron
object.
Method | Maps to |
---|---|
XLogger.reactotron.log | Reactotron.log |
XLogger.rectotron.logImportant | Reactotron.logImportant |
XLogger.rectotron.display | Reactotron.display |
Why would you use XLogger.reactotron
instead of calling the Reactotron methods directly? To avoid issues in
production with a non-existent Reactotron instance, of course!
Sentry Logger
The Sentry logger wraps Sentry.captureMessage
and Sentry.captureException
. Sentry.captureEvent
is not supported,
but of course, you can still use this method in your own code.
The Sentry logger will only automatically forward LogLevel.warn
and LogLevel.error
to Sentry
regardless of the log level (as long as the log level is warn
or higher). This is to prevent too much noise
from going to Sentry.
OK, that was probably confusing. Here's how it works:
1. Inbound messages are filtered per the log level and then forwarded to the Sentry logger.
2. If the filtered message is a warn
or error
it will be sent to Sentry by default. (See the BypassParams below for
more clarity).
Like the Reactotron logger, the Sentry logger has some special purpose methods. These all map to Sentry.captureMessage
,
but map the Severity
differently in order to support levels that RNX does not have.
Method | Maps to |
---|---|
XLogger.sentry.log | Sentry.captureMessage with Severity set according to the mapping shown in Log Levels, above |
XLogger.sentry.logCritical | Sentry.captureMessage with Severity.Critical |
XLogger.sentry.logFatal | Sentry.captureMessage with Severity.Fatal |
API
XLogger.configure(params: Partial<XLoggerConfig>)
Configures XLogger on startup. Params are defined in the interface XLoggerConfig
.
Any or all params can be passed:
logLevel: LogLevel
: one of the log levels available in the enum LogLevel. Defaults to.debug
.useCorrespondingConsoleMethod: boolean
: see above. Defaults totrue
useSentry: boolean
: turn on/off Sentry logging. Defaults tofalse
.printLogLevel: boolean
: see above, defaults tofalse
.printLogTime: boolean
: see above, defaults tofalse
.reactotronInstance?: ReactotronInstance
: defaults toundefined
.useReactotron: boolean
: defaults tofalse
All of these parameters have corresponding setters shown below.
Logging Methods
All logging methods have the same call signature. Example:
XLogger.logDebug( message: Message, bypassParams?: BypassParams );
message
can be a primitive (string, number) or an object.
bypassParams
is an optional object with the shape { bypassReactotron: boolean, bypassSentry: boolean }
. You would use this
optional parameter to squelch specific messages from going to either Reactotron or Sentry. There are defaults are shown
below for each log level.
As an example of using bypass, let's say you had a specific .warn
message you wanted to see in console
and Reactotron, but not
forward to Sentry. You would:
XLogger.warn('Do not send to Sentry', { bypassSentry: true });
Method | Synonym | Bypass Defaults |
---|---|---|
XLogger.logError | .error | { bypassReactotron: false , bypassSentry: false } |
XLogger.logWarn | .warn | { bypassReactotron: false , bypassSentry: false } |
XLogger.logDebug | .log , .debug | { bypassReactotron: false , bypassSentry: true } |
XLogger.logInfo | .info | { bypassReactotron: false , bypassSentry: true } |
XLogger.logVerbose | .verbose | { bypassReactotron: false , bypassSentry: true } |
XLogger.logSilly | .silly | { bypassReactotron: false , bypassSentry: true } |
XLogger.out | none | { bypassReactotron: false , bypassSentry: true } |
XLogger.out
is a special case that ignores all log levels except .silent
and will call the following:
console.log
Reactotron.log
if Reactotron is enabled.Sentry.captureMessage
(by way of XLogger.sentry.log) withSeverity.Log
. Note that if you want this call to actually hit Sentry, you need to setbypassSentry
tofalse
.
Additional Configuration Methods
XLogger.setReactronInstance(instance: ReactotronInstance)
is used to set the configured Reactotron instance. You don't need to
call this if you have passed it in the configure
call above.
XLogger.setUseReactotron(shouldUse: boolean)
: turn on/off Reactotron logging.
XLogger.setUseSentry(shouldUse: boolean)
: turn on/off Sentry logging.
XLogger.setLogLevel(level: LogLevel)
: self explanatory :).
Xlogger.setUseCorrespondingConsoleMethod(shouldUse: boolean)
: see explanation of this flag above.
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago