Logger Usage Quick Reference

May contain stale references

This document was audited on 2026-06-22 and contains references that need updating: packages/crm does not exist. Cross-check critical details against the current codebase before relying on them.

🎯 The Rule

Category	Import From	Reason
Shared Packages	@repo/utils/logger	Never pull in observability
Apps WITH Observability	@repo/observability/logger	Full OTEL support
Apps WITHOUT Observability	@repo/utils/logger	Lightweight, no OTEL

📦 Shared Packages (Use Base Logger)

Always use @repo/utils/logger in:

• ✅ packages/auth/
• ✅ packages/db/
• ✅ packages/utils/
• ✅ packages/ai/
• ✅ packages/crm/
• ✅ packages/ui/ (if logging)
• ✅ packages/observability/ (for any app-independent code)

Example:

packages/auth/src/middleware.ts

import { logger } from '@repo/utils/logger';

export async function validateRequest(req: Request) {
  logger.info('Validating request');
  // ...
}

Why?

• Keeps shared packages independent
• Avoids circular dependencies
• Prevents forced observability bundling
• CRM (and other apps) can use without OTEL

---

🚀 Apps WITH Full Observability

Use @repo/observability/logger in:

apps/webapp/

import { logger } from '@repo/observability/logger';

export const POST: APIRoute = async ({ request }) => {
  logger.info('Processing request'); // ✅ Includes trace context
  // ...
};

Note: Python apps (pdf-api, pdf-worker) use their own Python-based logging and OpenTelemetry instrumentation, not the TypeScript @repo/observability package.

Why?

• Gets full OTEL trace context automatically
• Logs sent to observability backend
• Performance metrics included
• Debugging with trace correlation

---

🛠️ Apps WITHOUT Observability

Use @repo/utils/logger in:

apps/crm/src/utils/logger.ts

import { logger } from '@repo/utils/logger';

export default logger;

New lightweight app (hypothetical)

import { logger } from '@repo/utils/logger';

logger.info('App started');
logger.error('Something failed', error);

Why?

• No OTEL overhead
• Faster builds
• Simpler dependencies
• Still get structured Pino logging

---

🔄 Migration Checklist

Step 1: Identify Current Imports

# Find all logger imports
grep -r "from '@repo/observability/logger'" packages/*/src
grep -r "from '@repo/observability/logger'" apps/*/src

Step 2: Update Shared Packages

Change all imports in these packages:

// ❌ BEFORE
import { logger } from '@repo/observability/logger';

// ✅ AFTER
import { logger } from '@repo/utils/logger';

Packages to update:

• packages/auth/
• packages/db/ (if used)
• packages/ai/
• packages/crm/
• packages/utils/ (internal usages)

Step 3: Verify Apps Still Work

# TypeScript/JavaScript apps should continue to work unchanged
pnpm --filter @erp-unlocked/webapp build

# CRM should now build without OTEL errors
pnpm --filter @erp-unlocked/crm build

Note: Python services (pdf-api, pdf-worker) use Python-based testing tools (pytest) and are not tested via pnpm commands.

Step 4: Test Everything

pnpm build
pnpm test
pnpm lint

---

📋 Complete Package Summary

Base Packages (use @repo/utils/logger)

packages/
├── auth/              ← ✅ import from @repo/utils/logger
├── db/                ← ✅ import from @repo/utils/logger
├── ui/                ← ✅ import from @repo/utils/logger
├── utils/             ← ✅ import from @repo/utils/logger
├── ai/                ← ✅ import from @repo/utils/logger
├── crm/               ← ✅ import from @repo/utils/logger
└── observability/     ← ✅ Enhanced logger layer (OTEL)

Apps

apps/
├── webapp/            ← 🚀 import from @repo/observability/logger (full OTEL)
├── crm/               ← 🛠️  import from @repo/utils/logger (lightweight)
└── marketing/         ← 🛠️  import from @repo/utils/logger (static site)

Note: Python services (pdf-api, pdf-worker) use their own Python-based logging and OpenTelemetry instrumentation, not the TypeScript @repo/observability package.

---

🎓 Understanding the Architecture

Base Logger Loads Once, On-Demand

// First import
import { logger } from '@repo/utils/logger';

// Pino not loaded yet (lazy)
logger.info('Message'); // ← Pino loads here

// Next import - reuses same instance
import { logger as logger2 } from '@repo/utils/logger';
logger2.info('Message'); // ← Uses cached instance

Environment-Specific Behavior

import { logger } from '@repo/utils/logger';

// Node.js server
logger.info('message'); // → Pino structured log to stdout

// Browser/Client
logger.info('message'); // → console.log

// Astro build time
logger.info('message'); // → Simple Pino (no transports)

// With OTEL enabled
// (if app initializes observability)
logger.info('message'); // → Pino + OTEL instrumentation

---

⚠️ Common Mistakes

❌ DON’T: Import observability logger in shared packages

packages/auth/src/server.ts

import { logger } from '@repo/observability/logger'; // ❌ WRONG

Problem: Forces OTEL on all consumers

Solution: Import from utils instead

import { logger } from '@repo/utils/logger'; // ✅ CORRECT

❌ DON’T: Conditionally import based on observability

let logger;
if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
  logger = await import('@repo/observability/logger');
} else {
  logger = await import('@repo/utils/logger');
}

Problem: Confusing and unnecessary

Solution: Always use base logger, let app layer handle OTEL

import { logger } from '@repo/utils/logger'; // ✅ SIMPLE

// Observability is app-level concern, not package-level

❌ DON’T: Re-export logger with new names

packages/crm/src/logger.ts

export { logger as crmLogger } from '@repo/observability/logger'; // ❌ WRONG

Problem: Defeats the purpose of the architecture

Solution: Re-export base logger if needed

export { logger } from '@repo/utils/logger'; // ✅ CORRECT

---

✅ Best Practices

1. Always import at module level (not in functions)

// ✅ GOOD
import { logger } from '@repo/utils/logger';

export function myFunction() {
  logger.info('message');
}

// ❌ BAD (creates new import each time)
export function myFunction() {
  const { logger } = await import('@repo/utils/logger');
  logger.info('message');
}

2. Use child loggers for context

// ✅ GOOD - adds context to all child logs
const requestLogger = logger.child({ requestId, userId });
requestLogger.info('Processing');
requestLogger.error('Failed');

3. Log structured data, not strings

// ✅ GOOD
logger.info('User created', { userId, email, timestamp: Date.now() });

// ❌ BAD
logger.info(`User ${userId} created at ${new Date()}`);

4. Use appropriate log levels

logger.debug('Detailed trace info'); // ✅ Development
logger.info('Normal operation'); // ✅ Important events
logger.warn('Recoverable issue'); // ✅ Warnings
logger.error('Error details', { error }); // ✅ Failures

---

📚 Related Documentation

• LOGGER_ARCHITECTURE.md - Detailed architecture
• LOGGER_MIGRATION_GUIDE.md - Step-by-step migration
• LOGGER_SOLUTION_SUMMARY.md - Solution overview
• BEFORE_AFTER_COMPARISON.md - Problem vs solution

---

Key Takeaway: Use @repo/utils/logger everywhere by default. Only use @repo/observability/logger in TypeScript/JavaScript apps that explicitly need full observability (e.g., webapp).