---
title: Team Hydra Logger (LLM)
description: Migrate from the old logger package to hepgg/logger, the hepgg package overview, and the logger reference.
---

# Team Hydra Logger (hepgg package)

The logger ships inside the unified `hepgg` package. Subpath: `hepgg/logger`.
Node 20+. Colour is bundled and forced on by default (honours NO_COLOR). Output:
dim [timestamp], colour-bracketed uppercase [LEVEL] padded to a uniform width,
then the message. Default export is a shared singleton.

## Migrating from the old `logger` package

The standalone `logger` package is deprecated. Change the import only:
  - from: const logger = require("logger");   (or: import logger from "logger";)
  - to:   const logger = require("hepgg/logger");
The singleton, all methods (debug/info/warning/error/severe/log), and
setLevel/time/write behave the same. New: trace, success, warn, fatal, child(),
createLogger().

## Install

  npm install hepgg --registry https://npm.hep.gg

## The hepgg package (other modules)

Same install also provides (most documented on docs.hep.gg):
  hepgg/id      https://docs.hep.gg/llms/idgen/sdk
  hepgg/sms     https://docs.hep.gg/llms/sms/sdk
  hepgg/email   https://docs.hep.gg/llms/email/sdk
  hepgg/uploader https://docs.hep.gg/llms/uploader/sdk
  hepgg/paste   https://docs.hep.gg/llms/snippets/sdk
  hepgg/secrets https://docs.hep.gg/llms/secrets/sdk
  hepgg/ai      https://docs.hep.gg/llms/ai/sdk
  hepgg/login   https://docs.hep.gg/llms/login/sdk
Full migration guide: https://docs.hep.gg/llms/migrating

## Import

  import logger from "hepgg/logger";                 // singleton (default export)
  const logger = require("hepgg/logger");            // CJS: module IS the singleton
  import { Logger, createLogger } from "hepgg/logger";

## Levels (low -> high severity)

  trace, debug, info, success, warn, error, fatal
Methods: logger.trace/debug/info/success/warn/error/fatal(...args).
Aliases: warning -> warn, severe -> fatal, log -> info.
Threshold: a message prints when its severity >= the current level. Set via LEVEL
env var or logger.setLevel(name). Default level: info.

## Scopes and instances

  logger.child("db")                -> prints a coloured [db] tag
  logger.child("api").child("auth") -> tag [api:auth]
  createLogger(options)             -> independent instance

## File logging

  Default: appends plain-text lines to events.log:
  "YYYY/MM/DD HH:MM:SS [LEVEL  ] message" (no ANSI).
  Disable/redirect: option file: false | "/path", or env LOG_FILE.

## Colour

  Forced truecolor by default (works in pm2 and pipes). NO_COLOR disables.
  Default hex: trace #6b7280, debug #9ca3af, info #38bdf8, success #22c55e,
  warn #f59e0b, error #ef4444, fatal white on red (#b91c1c).

## createLogger(options)

  level     string                       default LEVEL env or "info"
  color     boolean | "auto"             default forced on
  timestamp "datetime" | "time" | "iso" | ((date)=>string) | false   default "datetime"
            datetime = "MM/DD/YYYY - hh:mm AM/PM"
  file      boolean | string             default "events.log"
  colors    Partial<Record<level,string>> per-level hex overrides
  scope     string                       scope tag (usually via child())
  stream    WritableStream               default process.stdout

Preserved API: level, levels, setLevel(level), time() (HH:MM:SS),
write(type, message), child(scope).