From f3312fdd1194637a32e4b521aa5482ed51ddbca3 Mon Sep 17 00:00:00 2001
From: Eric Bailey <git@esb.lol>
Date: Wed, 12 Feb 2025 11:29:01 -0600
Subject: [PATCH] Docs

---
 src/logger/README.md | 102 ++++++++++---------------------------------
 src/logger/index.ts  |   3 +-
 2 files changed, 25 insertions(+), 80 deletions(-)

diff --git a/src/logger/README.md b/src/logger/README.md
index 8da7deb14e..e3476efdf6 100644
--- a/src/logger/README.md
+++ b/src/logger/README.md
@@ -1,99 +1,45 @@
 # Logger
 
-Simple logger for Bluesky. Supports log levels, debug contexts, and separate
-transports for production, dev, and test mode.
+Simple logger for Bluesky.
 
 ## At a Glance
 
 ```typescript
-import { logger } from '#/logger'
+import { logger, Logger } from '#/logger'
 
-logger.debug(message[, metadata, debugContext])
-logger.info(message[, metadata])
-logger.log(message[, metadata])
-logger.warn(message[, metadata])
-logger.error(error[, metadata])
-```
+// or, optionally create new instance with custom context
+// const logger = Logger.create(Logger.Context.Notifications)
 
-#### Modes
+// for dev-only logs
+logger.debug(message, {})
 
-The "modes" referred to here are inferred from `process.env.NODE_ENV`,
-which matches how React Native sets the `__DEV__` global.
+// for production breadcrumbs
+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
-and/or sent to Sentry and other reporting services. To configure, set the
-`EXPO_PUBLIC_LOG_LEVEL` environment variable in `.env` to one of `debug`,
-`info`, `log`, `warn`, or `error`.
+// for non-error issues to look into, seldom used, prefer `error`
+logger.warn(message, {})
 
-This variable should be `info` in production, and `debug` in dev. If it gets too
-noisy in dev, simply set it to a higher level, such as `warn`.
+// for known errors without an exception, use a string
+logger.error(`known error`, {})
 
-## Usage
-
-```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
+// for unknown exceptions
 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
-well as as breadcrumbs, with a severity level of `warning`
+Log level defaults to `info`. You can set this via the `EXPO_PUBLIC_LOG_LEVEL`
+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
-well as as breadcrumbs, with a severity level of `default`.
-
-### `logger.info`
-
-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`._
+Debug logs are dev-only, and not enabled by default. Once enabled, they can get
+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
+and include wildcards.
diff --git a/src/logger/index.ts b/src/logger/index.ts
index 8008c658c9..1e84fdcfdd 100644
--- a/src/logger/index.ts
+++ b/src/logger/index.ts
@@ -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)