Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions decisions/2026-06-01-logging-observability-hardening.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,3 +113,7 @@ escalation); the ESLint rule needs a tuning period; incremental sweep spans seve
required, warn allowed for whitelisted best-effort).
- Lucky scales to multiple instances → in-memory caches (guild-context, suggestions) move to
Postgres.

## Tracking

Status and per-track delivery tracked in umbrella issue [#1286](https://github.com/LucasSantana-Dev/Lucky/issues/1286).
91 changes: 91 additions & 0 deletions docs/logging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Logging

Lucky uses shared logging utilities that forward errors to Sentry for observability. This document describes correct usage and a common footgun to avoid.

## The logging utils

The shared logging layer (`packages/shared/src/utils/general/log/`) exports four main functions:

- **`errorLog(params)`** — logs an error and sends it to Sentry; call when an exceptional condition occurs.
- **`warnLog(params)`** — logs a warning and adds a breadcrumb; use for expected fallbacks or degradation.
- **`infoLog(params)`** — logs informational messages; adds a breadcrumb.
- **`debugLog(params)`** — logs debug-level messages; respects the configured log level.

All accept a `LogParams` object:

```typescript
type LogParams = {
message: string // Required: human-readable message
error?: unknown // Optional: the caught exception or error object
data?: unknown // Optional: structured context (guildId, userId, etc.)
correlationId?: string // Optional: request or operation id for tracing
}
```

## The footgun: errorLog without the error object

Calling `errorLog({ message: "..." })` with only a message (omitting the `error` property) **silently degrades to an info-level event in Sentry**, losing the error context and stack trace.

The service checks whether `params.error` exists (line 106 in `service.ts`):
Comment thread
LucasSantana-Dev marked this conversation as resolved.
Resolved

- **If `error` is present**: calls `captureException()` → Sentry receives a full exception with stack.
- **If `error` is absent**: calls `captureMessage()` with level `'error'` → **Sentry receives a message, not an exception**, and the context is much weaker for debugging.

## Correct pattern

Always include the error object when calling `errorLog`:

```typescript
// ✅ CORRECT — Sentry captures the full exception + stack
try {
await spotifyApi.search(query)
} catch (err) {
errorLog({
message: 'Spotify search failed',
error: err,
data: { query, guildId: ctx.guildId }
})
return fallback
}
```

```typescript
// ❌ INCORRECT — Sentry records only a message; stack is lost
catch (err) {
errorLog({
message: 'Spotify search failed'
})
return fallback
}
```

For expected fallbacks (e.g., feature-toggle off, timeout, retrying), use `warnLog` instead:

```typescript
// ✅ CORRECT for degradation
if (!featureToggle.enabled) {
warnLog({ message: 'Feature disabled, using fallback' })
return fallback
}
```

## Structured context

Include relevant IDs and state in the `data` field for better debugging:

```typescript
errorLog({
message: 'Discord API rate-limited',
error: err,
data: {
guildId: guild.id,
userId: user.id,
operation: 'getUserGuilds',
retryAfter: err.response?.headers?.['retry-after']
}
})
```

## Related decision

See ADR [2026-06-01 — logging-observability-hardening](../decisions/2026-06-01-logging-observability-hardening.md) for the full logging strategy, including silent-catch enforcement (ESLint rule) and request-id threading.
Loading