Logging | Alepha

alepha@docs:~/docs/guides/observability$
cat 1-logging.md
2 min read
Last commit: 
#Loggingconsole.log is fine for debugging. It's not fine for production.
Alepha has a structured logging system that knows where logs come from, supports log levels, and outputs pretty colors in dev or JSON in production.
#Basic LoggingUse $logger() in any service:
typescript
import { $logger } from "alepha/logger"; class PaymentService {  log = $logger();   async processPayment(orderId: string, amount: number) {    this.log.info("Processing payment", { orderId, amount });     try {      await this.stripe.charge(amount);      this.log.info("Payment successful", { orderId });    } catch (error) {      this.log.error("Payment failed", { orderId, error });      throw error;    }  }}
Output in development (pretty):

    bash
    
  
[14:32:05.123] INFO <app.PaymentService> Processing payment { orderId: "ord_123", amount: 99.99 }
[14:32:05.456] INFO <app.PaymentService> Payment successful { orderId: "ord_123" }
Output in production (JSON, one line):
json
{"level":"info","time":"2024-01-15T14:32:05.123Z","module":"app.PaymentService","msg":"Processing payment","orderId":"ord_123","amount":99.99}
JSON logs are parseable by Datadog, Grafana Loki, CloudWatch, etc.
#Log DestinationBy default, logs go to stdout and are synchronous. This means every log.info() call blocks until the message is written.
For development, this is fine. You want logs immediately, and the performance hit is negligible.
For high-throughput production systems, synchronous logging can become a bottleneck. An async destination with buffering is planned for a future release. For now, if you're logging thousands of messages per second, consider:
Reducing log verbosity (LOG_LEVEL=warn)
Logging to a file and tailing it
Using an external log shipper (Fluentd, Vector)
#Log LevelsAlepha supports six levels (from quietest to noisiest):
typescript
// SILENT - nothing loggedthis.log.error("Something broke");           // ERROR - redthis.log.warn("Something unexpected");       // WARN - yellowthis.log.info("Normal operations");          // INFO - default visiblethis.log.debug("Detailed debugging info");   // DEBUG - hidden by defaultthis.log.trace("Very detailed tracing");     // TRACE - extremely verbose
#Configuring Log LevelSet via LOG_LEVEL environment variable:

    bash
    
  
LOG_LEVEL=debug npx alepha dev    # see debug and above
LOG_LEVEL=warn npx alepha start   # quiet production, only warnings+
LOG_LEVEL=trace npx alepha dev    # see absolutely everything
LOG_LEVEL=silent npx alepha start # complete silence
#Per-Module Log LevelsThis is where Alepha shines. You can set different levels for different modules:

    bash
    
  
# global info, but debug for payments module
LOG_LEVEL="info,app.payments:debug" npx alepha dev

# multiple module configs
LOG_LEVEL="alepha.core:trace,app.users:debug,warn" npx alepha dev

# use equals or colon - both work
LOG_LEVEL="app.payments=debug,info" npx alepha dev

# semicolon separator also works
LOG_LEVEL="alepha:trace;app:debug;info" npx alepha dev
#Wildcard PatternsNeed to debug an entire namespace? Use wildcards:

    bash
    
  
# all alepha.* modules at debug level
LOG_LEVEL="alepha.*:debug,info" npx alepha dev

# all modules ending in .test at silent
LOG_LEVEL="*.test:silent,info" npx alepha dev
#How Matching WorksThe logger uses first match wins with prefix matching:
typescript
// config: "alepha:debug,alepha.core:trace,info" // "alepha.core" matches "alepha" first → DEBUG (not TRACE!)// order matters: put specific patterns first // better: "alepha.core:trace,alepha:debug,info"// now "alepha.core" matches first → TRACE
This is huge. You can turn on trace logging for just the one service causing problems without drowning in noise from the rest of the app.
#Context-Aware LoggingThe logger automatically includes the module name. If you're using $module, logs show the full path:
typescript
const PaymentsModule = $module({  name: "app.payments",  services: [PaymentService, RefundService],}); // logs from PaymentService show: <app.payments.PaymentService>
This makes it trivial to filter logs in production:

    bash
    
  
grep "app.payments" /var/log/myapp.log
#Request LoggingWant to log every HTTP request? Alepha does it automatically when you enable the server module. You'll see:

    bash
    
  
[14:32:05.100] INFO <alepha.server> --> GET /api/users
[14:32:05.150] INFO <alepha.server> <-- GET /api/users 200 50ms
#Comparison: Winston vs Pino vs AlephaWinston:
typescript
// lots of configurationconst logger = winston.createLogger({  level: 'info',  format: winston.format.combine(    winston.format.timestamp(),    winston.format.json()  ),  transports: [new winston.transports.Console()],}); logger.info("message", { orderId: "123" });// doesn't know which service it came from
Pino:
typescript
// fast, but manual setupconst logger = pino({ level: 'info' });const childLogger = logger.child({ module: 'PaymentService' });childLogger.info({ orderId: "123" }, "message");
Alepha:
typescript
// zero config, automatic contextclass PaymentService {  log = $logger();  // knows it's PaymentService   doThing() {    this.log.info("message", { orderId: "123" });    // output includes module name automatically  }}
#Best Practices
#Log at Boundariestypescript
// log when entering/exiting important operationsasync processOrder(order: Order) {  this.log.info("Processing order", { orderId: order.id });   // ... lots of internal work ...   this.log.info("Order processed", { orderId: order.id, duration: elapsed });}
#Include Contexttypescript
// badthis.log.error("Payment failed"); // goodthis.log.error("Payment failed", {  orderId,  amount,  customerId,  errorCode: error.code,});
#Don't Log Secretstypescript
// bad - password in logsthis.log.info("User login", { email, password }); // goodthis.log.info("User login", { email });
#Use Appropriate Levelstypescript
this.log.trace("Entering function with args", { args });  // extreme detailthis.log.debug("Cache hit for key xyz");                  // debugging infothis.log.info("User created");                            // normal operationsthis.log.warn("Rate limit approaching");                  // concerning but not brokenthis.log.error("Database connection lost");               // something broke
#Summary

Need
Solution


Basic logging
$logger()

JSON logs for production
LOG_FORMAT=json (default in prod)

Debug specific module
LOG_LEVEL="module.name:debug,info"

Debug with wildcards
LOG_LEVEL="app.*:debug,info"
Logging is unglamorous but essential. Alepha makes it structured, filterable, and production-ready out of the box.
On This Page
No headings found...

Need	Solution
Basic logging	`$logger()`
JSON logs for production	`LOG_FORMAT=json` (default in prod)
Debug specific module	`LOG_LEVEL="module.name:debug,info"`
Debug with wildcards	`LOG_LEVEL="app.*:debug,info"`

ready
│main│TypeScript
│UTF-8│guides_observability_logging.md│