feat(logging): introduce logging configuration and infrastructure

[ryanbonial]

Description

Adds a complete logging infrastructure for the Sanity SDK

This PR introduces a flexible, namespace-based logging system that will help both SDK users and maintainers debug issues across the codebase. The infrastructure supports:

• Multi-level logging (error, warn, info, debug, trace) with namespace filtering
• Automatic instance context injection - logs automatically include [project:x] [dataset:y] when available, making multi-instance debugging much easier
• Global configuration via configureLogging() - simple, single source of truth
• Sensitive data sanitization - automatically redacts tokens, passwords, etc.
• Performance timing utilities for measuring operation durations
• Tree-shakeable - can be stripped in production builds

Why? Currently, there's no systematic way to debug what's happening inside the SDK. This makes it difficult to troubleshoot auth issues, document sync problems, query behavior, etc. This infrastructure provides the foundation for adding meaningful debug logs throughout the codebase.

Note: This PR contains only the infrastructure - no actual logging is added to stores or operations yet. Future PRs will incrementally add logging to auth, document, query, and other modules.

What to review

Key files to review:

1. packages/core/src/utils/logger.ts (~400 lines)

   • Core logging implementation
   • Check: namespace filtering logic, instance context injection, sanitization

2. packages/core/src/utils/logger.test.ts (~480 lines)

   • 28 comprehensive tests covering all functionality
   • Check: test coverage is adequate

3. packages/core/src/config/loggingConfig.ts (~110 lines)

   • Public API wrapper
   • Check: JSDoc examples are clear and helpful

4. packages/core/src/utils/logger-usage-example.md (~140 lines)

   • Usage guide for SDK maintainers
   • Check: examples make sense

5. packages/core/src/_exports/index.ts (+1 line)

   • Exports the public API

What's affected:

• Nothing! This is pure infrastructure with zero behavioral changes
• No existing code is modified beyond adding the export
• The logging system is opt-in via configureLogging()

Example usage:

import {configureLogging} from '@sanity/sdk'

// Enable logging in development
configureLogging({
  level: 'info',
  namespaces: ['auth', 'document']
})

// Outputs:
// [INFO] [sdk] Logging configured
// [INFO] [auth] [project:abc] [dataset:production] User logged in### Testing

✅ Comprehensive automated testing:

• 28 unit tests covering all functionality
• Tests for: configuration, namespace filtering, log levels, instance context injection, sanitization, performance timers, message formatting
• All tests passing with no linter errors

Manual testing:

• Verified log output format with different configurations
• Tested with/without instance context
• Confirmed sensitive data redaction works correctly

Future PRs (not included here) will add logging to individual modules (auth, document, query, etc.) and will include tests for those specific integrations.

Fun gif

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
sdk-docs	Ready	Preview	Comment	Dec 1, 2025 11:59pm
sdk-kitchensink-react	Ready	Preview	Comment	Dec 1, 2025 11:59pm

[Copilot]

Pull request overview

This PR introduces a comprehensive logging infrastructure for the Sanity SDK, providing namespace-based, multi-level logging capabilities. The implementation follows a clean separation between public API and internal utilities, with the logging system designed to be opt-in and tree-shakeable for production builds.

Key Changes

• Logging core implementation with namespace filtering, log levels, instance context injection, and sensitive data sanitization
• Public API wrapper (configureLogging) that provides a clean interface for SDK users to control logging behavior
• Comprehensive test suite with 28 tests covering configuration, filtering, formatting, and context handling
• Developer documentation with usage examples for both SDK users and maintainers

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/core/src/utils/logger.ts	Core logging implementation with logger creation, formatting, sanitization, and utility functions for timers and RxJS logging
packages/core/src/utils/logger.test.ts	Comprehensive test suite covering all major logging functionality including configuration, levels, namespaces, sanitization, and instance context
packages/core/src/config/loggingConfig.ts	Public API wrapper that exports configureLogging function with extensive JSDoc examples for users and maintainers
packages/core/src/utils/logger-usage-example.md	Usage documentation showing real-world examples for SDK users, maintainers, and multi-instance scenarios
packages/core/src/_exports/index.ts	Adds export of public logging API (configureLogging, LoggerConfig, LogLevel types)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 11 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.