Logger Usage Quick Reference

🎯 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/pricing/
• ✅ packages/integrations/
• ✅ 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
• Lightweight apps (internal, Cloudflare Workers) can consume packages without OTEL

---

🚀 Apps WITH Full Observability

Use @repo/observability/logger in:

• apps/webapp/
• apps/ts-temporal-worker/

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

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

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

Why?

• Gets full OTEL trace context automatically
• Supports @opentelemetry/api-logs (OTEL_LOGS_EXPORTER=otlp) and @logtail/pino alongside stdout
• Debugging with trace correlation

---

🛠️ Apps WITHOUT Observability

Use @repo/utils/logger in:

• apps/internal/ (Cloud Run with _HAS_OTEL=false)
• Cloudflare Workers (apps/email-worker/, apps/ops-mcp/, apps/content-mcp/, apps/partner-data-api/, apps/tidycal-hubspot-sync/)
• apps/docs/ (static site)

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

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

Why?

• No OTEL overhead
• Faster builds and smaller worker bundles
• Simpler dependencies
• Still get structured Pino logging on Node or formatted console output on Workers/browser

---

🔀 Argument Normalization (Both Call Styles Supported)

Standard Pino expects (mergingObject, message) and silently drops objects passed after the message string. Both @repo/utils/logger (normalizeLogArgs) and @repo/observability/logger (buildOtelLogRecord / toPinoArgs) normalize arguments automatically so both call styles preserve all structured fields:

// ✅ Message-first (with context object and/or Error in any trailing position)
logger.info('Order extracted', { orderId, itemCount: 5 });
logger.error('ERP submission failed', err, { orderId, connectionId });
logger.error('ERP submission failed', { orderId, connectionId }, err);

// ✅ Pino-style object-first
logger.info({ orderId, itemCount: 5 }, 'Order extracted');

• Plain objects are merged into top-level structured log attributes.
• Error instances are automatically extracted (err in @repo/utils/logger; error.message and error.stack in @repo/observability/logger).

---

🔄 Verification 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: Keep Shared Packages on @repo/utils/logger

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

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

Step 3: Verify Apps Build

pnpm --filter webapp build
pnpm --filter internal build

Note: Python services (temporal-worker, dagster, packages/pdf-shared) use pytest and are not tested via pnpm build commands.

---

📋 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
├── pricing/           ← ✅ import from @repo/utils/logger
├── integrations/      ← ✅ import from @repo/utils/logger
└── observability/     ← ✅ Enhanced logger layer (OTEL)

Apps

apps/
├── webapp/             ← 🚀 import from @repo/observability/logger (full OTEL)
├── ts-temporal-worker/ ← 🚀 import from @repo/observability/logger (full OTEL)
├── internal/           ← 🛠️  import from @repo/utils/logger (lightweight)
├── email-worker/       ← 🛠️  import from @repo/utils/logger (Cloudflare Worker)
├── ops-mcp/            ← 🛠️  import from @repo/utils/logger (Cloudflare Worker)
└── docs/               ← 🛠️  import from @repo/utils/logger (static site)

---

🎓 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)

---

⚠️ 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 in shared code; let the app layer handle OTEL.

---

✅ Best Practices

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

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

export function myFunction() {
  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 interpolated 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, { context }); // ✅ Failures

---

📚 Related Documentation

• Logging Configuration - 4-tier logger resolution & argument normalization
• Observability Overview - Platform logging, tracing, and alerting stack

---

Key Takeaway: Use @repo/utils/logger everywhere by default. Only use @repo/observability/logger in TypeScript/JavaScript apps that explicitly run with OpenTelemetry (webapp, ts-temporal-worker).