# grip **Repository Path**: mirrors_mongodb/grip ## Basic Information - **Project Name**: grip - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-09 - **Last Updated**: 2025-10-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ======================================================= ``grip`` -- A Go Library for Logging and Error Handling ======================================================= ``grip`` isn't any thing special, but it does a few pretty great things: #. Provide a common logging interface with support for multiple logging backends including syslog, systemd's journal, slack, xmpp, a JSON logging system, and others. #. Provides some simple methods for handling errors, particularly when you want to accumulate and then return errors. #. Provides tools for collecting structured logging information. *You just get a grip, folks.* Use --- Download: :: go get -u github.com/mongodb/grip Import: :: import "github.com/mongodb/grip" Components ---------- Output Formats ~~~~~~~~~~~~~~ Grip supports a number of different logging output backends: - systemd's journal (linux-only) - syslog (unix-only) - writing messages to standard output. (default) - writing messages to a file. - sending messages to a slack's channel - sending messages to a user via XMPP (jabber.) The default logger interface has methods to switch the backend to the standard output (native; default), and file-based loggers. The SetSender() and CloneSender() methods allow to replace the sender implementation in your logger. See the documentation of the `Sender interface `_ for more information on building new senders. Logging ~~~~~~~ Provides a fully featured level-based logging system with multiple backends (e.g. send.Sender). By default logging messages are printed to standard output, but backends exists for many possible targets. The interface for logging is provided by the Journaler interface. By default ``grip.std`` defines a standard global instances that you can use with a set of ``grip.`` functions, or you can create your own ``Journaler`` instance and embed it in your own structures and packages. Defined helpers exist for the following levels/actions: - ``Debug`` - ``Info`` - ``Notice`` - ``Warning`` - ``Error`` - ``Critical`` - ``Alert`` - ``Emergency`` - ``EmergencyPanic`` - ``EmergencyFatal`` Helpers ending with ``Panic`` call ``panic()`` after logging the message message, and helpers ending with ``Fatal`` call ``os.Exit(1)`` after logging the message. These are primarily for handling errors in your main() function and should be used sparingly, if at all, elsewhere. ``Journaler`` instances have a notion of "default" log levels and thresholds, which provide the basis for verbosity control and sane default behavior. The default level defines the priority/level of any message with an invalid priority specified. The threshold level, defines the minimum priority or level that ``grip`` sends to the logging system. It's not possible to suppress the highest log level, ``Emergency`` messages will always log. ``Journaler`` objects have the following, additional methods (also available as functions in the ``grip`` package to manage the global standard logger instance.): - ``SetName()`` to reset the name of the logger. ``grip`` attempts to set this to the name of your program for the standard logger. - ``SetDefault()`` change the default log level. Levels are values between ``0`` and ``7``, where lower numbers are *more* severe. ``grip`` does *not* forbid configurations where default levels are *below* the configured threshold. - ``SetThreshold()`` Change the lowest log level that the ``grip`` will transmit to the logging mechanism (either ``systemd`` ``journald`` or Go's standard logging.) Log messages with lower levels are not captured and ignored. The ``Journaler.InvertFallback`` flag (bool) switches a ``Journaler`` instance to prefer the standard logging mechanism rather than ``systemd``. By default: - the log level uses the "Notice" level (``5``) - the minimum threshold for logging is the "Info" level (``6``) (suppressing only debug.) - fallback logging writes to standard output. Collector for "Continue on Error" Semantics ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to do something other than just swallow errors, but don't need to hard abort, the ``MultiCatcher`` object makes this pattern swell, a la: :: func doStuff(dirname string) (error) { files, err := ioutil.ReadDir(dirname) if err != nil { // should abort here because we shouldn't continue. return err } catcher := grip.NewCatcher() for _, f := range files { err = doStuffToFile(f.Name()) catcher.Add(err) } return catcher.Resolve() } Simple Error Catching ~~~~~~~~~~~~~~~~~~~~~ Use ``grip.Catch()`` to check and print error messages. There are also helper functions on ``Journaler`` objects that check and log error messages using either the default (global) ``Journaler`` instance, or as a method on specific ``Journaler`` instances, at all levels: - ``CatchDebug`` - ``CatchInfo`` - ``CatchNotice`` - ``CatchWarning`` - ``CatchError`` - ``CatchCritical`` - ``CatchAlert`` - ``CatchEmergency`` - ``CatchEmergencyPanic`` - ``CatchEmergencyFatal`` Conditional Logging ~~~~~~~~~~~~~~~~~~~ ``grip`` incldues support for conditional logging, so that you can only log a message in certain situations, by adding a Boolean argument to the logging call. Use this to implement "log sometimes" messages to minimize verbosity without complicating the calling code around the logging. These methods have a ``When<>`` format. For example: ``AlertWhen``, ``AlertWhenln``, ``AlertWhenf``. Composed Logging ~~~~~~~~~~~~~~~~ If the production of the log message is resource intensive or complicated, you may wish to use a "composed logging," which delays the generation of the log message from the logging call site to the message propagation, to avoid generating the log message unless neccessary. Rather than passing the log message as a string, pass the logging function an instance of a type that implements the ``MessageComposer`` interface: :: type MessageComposer interface { String() string Raw() interface{} Loggable() bool Priority() level.Priority SetPriority(level.Priority) error } Composed logging may be useful for some debugging logging that depends on additional database, API queries, or data serialization. Composers are also the mechanism through which the ``Catch<>`` methods are implemented, Grip uses composers internally, but you can pass composers directly to any of the basic logging method (e.g. ``Info()``, ``Debug()``) for composed logging. Grip includes a number of message types, including those that collect system information, process information, stacktraces, or simple user-specified structured information.