Skip to content

feat: add namespaced debug logging inspired by npm's debug package - #83

Merged
steve-calvert-glean merged 3 commits into
mainfrom
feat/debug-logging
Apr 10, 2026
Merged

feat: add namespaced debug logging inspired by npm's debug package#83
steve-calvert-glean merged 3 commits into
mainfrom
feat/debug-logging

Conversation

@steve-calvert-glean

Copy link
Copy Markdown
Collaborator

Summary

  • Adds internal/debug package providing zero-cost namespaced debug logging, inspired by npm's debug package
  • Activated via GLEAN_DEBUG env var with glob patterns (e.g. GLEAN_DEBUG=auth:*) or --verbose/-v flag
  • Instruments the full auth flow, HTTP transport layer, config resolution, streaming chat, session persistence, and TUI initialization
  • Replaces silent error swallowing (_ = err) with debug-logged best-effort operations
  • Adds "Tip: re-run with -v or GLEAN_DEBUG=auth:* for details" hint on auth failures

Namespaces

Namespace What it traces
auth:login Overall login flow orchestration
auth:resolve-host Host resolution and domain lookup
auth:discovery OAuth endpoint discovery (RFC 9728, OIDC, RFC 8414)
auth:dcr Dynamic Client Registration
auth:token Token load, expiry, refresh
auth:email Email extraction from JWT/OIDC
http:request Outgoing HTTP method + URL
http:response HTTP status + round-trip timing
client:resolve Credential source selection (API token vs OAuth)
config:load Config source priority (env → keyring → file)
config:keyring Keyring access attempts and failures
stream:connect SSE connection lifecycle
stream:parse NDJSON line parsing and malformed line skipping
session:persist Session save/load failures
tui:init TUI component initialization

Example

$ GLEAN_DEBUG=auth:*,config:* glean auth status
  config:load       env: host=false token=false +0ms
  config:keyring    get host: secret not found in keyring +12ms
  config:keyring    get token: secret not found in keyring +12ms
  config:load       after keyring: host=false token=false +0ms
  config:load       loaded config file: ~/.glean/config.json (53 bytes) +0ms
  config:load       after file: host=true token=false +0ms
  config:load       resolved host=company-be.glean.com token=false +0ms
✓ Authenticated as user@company.com (company-be.glean.com)
  Token expires 2026-04-16T21:11:36Z (in 165h14m0s)

Test plan

  • go test ./... -count=1 — 419 tests pass
  • golangci-lint run — clean
  • mise run build — binary builds
  • Debug disabled by default — ./glean auth status shows no debug output
  • GLEAN_DEBUG=* — full trace to stderr
  • GLEAN_DEBUG=config:keyring — only keyring logs shown
  • GLEAN_DEBUG='*,-config:keyring' — negation works
  • ./glean -v auth status — verbose flag enables all debug
  • Auth failure shows "Tip: re-run with -v" hint (suppressed when debug active)
  • Race detector passes: go test ./internal/debug/... -race

🤖 Generated with Claude Code

@steve-calvert-glean steve-calvert-glean added the enhancement New feature or request label Apr 10, 2026
@steve-calvert-glean
steve-calvert-glean requested a review from a team April 10, 2026 00:20
steve-calvert-glean and others added 3 commits April 10, 2026 08:17
Add an internal/debug package that provides zero-cost namespaced debug
logging, activated via GLEAN_DEBUG env var (with glob patterns) or the
existing --verbose/-v flag. This makes auth failures, HTTP issues, and
config resolution debuggable without code changes.

Namespaces: auth:*, http:*, config:*, client:*, stream:*, session:*,
tui:*. Example: GLEAN_DEBUG=auth:* glean auth login

Key changes:
- Wire the previously unused --verbose flag to debug.Enable()
- Instrument HTTP transport (all 8 call sites via single RoundTrip)
- Replace silent error swallowing in auth flow with debug logging
- Add config/keyring resolution tracing (critical for macOS issues)
- Add NDJSON parse error visibility in streaming chat
- Show "Tip: re-run with -v" hint on auth failures

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes gocritic ifElseChain lint failure in CI.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Document that CI runs golangci-lint v2 with gocritic and other strict
linters, and that local lint must pass before pushing. Adds explicit
note about version mismatch risk.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

@rwjblue-glean rwjblue-glean left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great. It's a great base to build on even more stuff if we want to in the future as well.

@steve-calvert-glean
steve-calvert-glean merged commit f03ea3a into main Apr 10, 2026
7 checks passed
@steve-calvert-glean
steve-calvert-glean deleted the feat/debug-logging branch April 10, 2026 15:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants