Docs

2025-02-12 11:29:01 -06:00
parent 66280fd731
commit f3312fdd11
2 changed files with 25 additions and 80 deletions
@@ -1,99 +1,45 @@
 # Logger
-Simple logger for Bluesky. Supports log levels, debug contexts, and separate
+Simple logger for Bluesky.
 transports for production, dev, and test mode.
 ## At a Glance
 ```typescript
-import { logger } from '#/logger'
+import { logger, Logger } from '#/logger'
-logger.debug(message[, metadata, debugContext])
+// or, optionally create new instance with custom context
-logger.info(message[, metadata])
+// const logger = Logger.create(Logger.Context.Notifications)
 logger.log(message[, metadata])
 logger.warn(message[, metadata])
 logger.error(error[, metadata])
 ```
-#### Modes
+// for dev-only logs
 logger.debug(message, {})
-The "modes" referred to here are inferred from `process.env.NODE_ENV`,
+// for production breadcrumbs
-which matches how React Native sets the `__DEV__` global.
+logger.info(message, {})
-#### Log Levels
+// seldom used, prefer `info`
 logger.log(message, {})
-Log levels are used to filter which logs are either printed to the console
+// for non-error issues to look into, seldom used, prefer `error`
-and/or sent to Sentry and other reporting services. To configure, set the
+logger.warn(message, {})
 `EXPO_PUBLIC_LOG_LEVEL` environment variable in `.env` to one of `debug`,
 `info`, `log`, `warn`, or `error`.
-This variable should be `info` in production, and `debug` in dev. If it gets too
+// for known errors without an exception, use a string
-noisy in dev, simply set it to a higher level, such as `warn`.
+logger.error(`known error`, {})
-## Usage
+// for unknown exceptions
 ```typescript
 import { logger } from '#/logger';
 ```
 ### `logger.error`
 The `error` level is for... well, errors. These are sent to Sentry in production mode.
 `error`, along with all log levels, supports an additional parameter, `metadata: Record<string, unknown>`. Use this to provide values to the [Sentry
 breadcrumb](https://docs.sentry.io/platforms/react-native/enriching-events/breadcrumbs/#manual-breadcrumbs).
 ```typescript
 try {
  // some async code
 } catch (e) {
-  logger.error(e, { ...metadata });
+  logger.error(e, {message: `explain error`}])
 }
 ```
-### `logger.warn`
+#### Log Levels
-Warnings will be sent to Sentry as a separate Issue with level `warning`, as
+Log level defaults to `info`. You can set this via the `EXPO_PUBLIC_LOG_LEVEL`
-well as as breadcrumbs, with a severity level of `warning`
+env var in `.env.local`.
-### `logger.log`
+#### Filtering debugs by context
-Logs with level `log` will be sent to Sentry as a separate Issue with level `log`, as
+Debug logs are dev-only, and not enabled by default. Once enabled, they can get
-well as as breadcrumbs, with a severity level of `default`.
+noisy. So you can filter them by setting the `EXPO_PUBLIC_LOG_DEBUG` env var
-
+e.g. `EXPO_PUBLIC_LOG_DEBUG=notifications`. These values can be comma-separated
-### `logger.info`
+and include wildcards.
 The `info` level should be used for information that would be helpful in a
 tracing context, like Sentry. In production mode, `info` logs are sent
 to Sentry as breadcrumbs, which decorate log levels above `info` such as `log`,
 `warn`, and `error`.
 ### `logger.debug`
 Debug level is really only intended for local development. Use this instead of
 `console.log`.
 ```typescript
 logger.debug(message, { ...metadata });
 ```
 Inspired by [debug](https://www.npmjs.com/package/debug), when writing debug
 logs, you can optionally pass a _context_, which can be then filtered when in
 debug mode.
 This value should be related to the feature, component, or screen
 the code is running within, and **it should be defined in `#/logger/debugContext`**.
 This way we know if a relevant context already exists, and we can trace all
 active contexts in use in our app. This const enum is conveniently available on
 the `logger` at `logger.DebugContext`.
 For example, a debug log like this:
 ```typescript
 logger.debug(message, {}, logger.DebugContext.composer);
 ```
 Would be logged to the console in dev mode if `EXPO_PUBLIC_LOG_LEVEL=debug`, _or_ if you
 pass a separate environment variable `LOG_DEBUG=composer`. This variable supports
 multiple contexts using commas like `LOG_DEBUG=composer,profile`, and _automatically
 sets the log level to `debug`, regardless of `EXPO_PUBLIC_LOG_LEVEL`._
@@ -133,9 +133,8 @@ export class Logger {
 *
 *   `logger.debug(message[, metadata])`
 *   `logger.info(message[, metadata])`
 *   `logger.log(message[, metadata])`
 *   `logger.warn(message[, metadata])`
 *   `logger.error(error[, metadata])`
 *   `logger.disable()`
 *   `logger.enable()`
 */
 export const logger = Logger.create(Logger.Context.Default)