agent-logger-library

Purpose-built logging for AI-enabled services. This library standardizes how agent backends describe server traffic, LLM provider calls, and failures so teams can read logs faster and diagnose incidents with less guesswork.

It prints structured, multi-line logs with a consistent prefix on every line. Each call generates one log block, and the block is composed from the context you pass.

Example output:

[LOG] 2026-02-06T15:41:16.034Z - agent-logger-library - development - SERVER - service:ready
[LOG] 2026-02-06T15:41:16.034Z - agent-logger-library - development - SERVER - GET - /health
[LOG] 2026-02-06T15:41:16.036Z - agent-logger-library - development - LLM - outbound request
[LOG] 2026-02-06T15:41:16.036Z - agent-logger-library - development - LLM - provider Gemini
[LOG] 2026-02-06T15:41:16.036Z - agent-logger-library - development - LLM - https://generativelanguage.googleapis.com/v1/models

📦 Install

npm install agent-logger-library

🚀 Quick Start

import { createLogger } from 'agent-logger-library';

const logger = createLogger({
  serviceName: 'backlog-structurer-agent',
  env: process.env.NODE_ENV ?? 'development',
});

logger.info('service:ready', { scope: 'SERVER' });

logger.info('inbound request', {
  scope: 'SERVER',
  req: { method: 'POST', url: '/api/v1/backlog/structure' },
});

logger.info('outbound request', {
  scope: 'LLM',
  llmProvider: 'Gemini',
  llmEndpoint: 'https://generativelanguage.googleapis.com/v1/models',
});

🧭 Typical Use Cases

🖥️ Server Request Flow

logger.info('inbound request', {
  scope: 'SERVER',
  req: { method: 'POST', url: '/api/v1/backlog/structure' },
});

// ...handler logic

logger.info('request success', { scope: 'SERVER' });

🧠 LLM Provider Flow

logger.info('outbound request', {
  scope: 'LLM',
  llmProvider: 'Gemini',
  llmEndpoint: 'https://generativelanguage.googleapis.com/v1/models',
});

// ...invoke provider

logger.info('request success', { scope: 'LLM' });

🧯 Error Handling

try {
  // ...invoke provider
} catch (err) {
  logger.error('request error', { scope: 'LLM', err });
  logger.error('request error', { scope: 'SERVER', err });
}

If includeStack is enabled (default in development), the logger prints the first stack line inline, then a stacktrace block:

[LOG] ... - LLM - request error
[LOG] ... - LLM - LLM unavailable or invalid output | stack: Error: LLM unavailable or invalid output
[LOG] ... - LLM - Error stacktrace
    at handler (index.ts:10:4)
    at run (index.ts:20:2)

🧩 API

• createLogger(options) creates a logger instance.
• Methods: info, warn, error, debug, trace, fatal, child.

⚙️ Options

type LoggerOptions = {
  serviceName: string;
  env?: string;
  now?: () => Date;
  includeStack?: boolean;
};

🧾 Context Fields

type LogContext = {
  scope?: string;
  req?: { url?: string; method?: string };
  err?: unknown;
  llmProvider?: string;
  llmEndpoint?: string;
  [key: string]: unknown;
};

Notes:

• scope defaults to APP when omitted.
• includeStack defaults to true when env is development.
• debug and trace log only in development.

🤝 Contributing

Read the contribution guide in CONTRIBUTING.md.

🐛 Issues

Open issues at https://github.com/AuronForge/agent-logger-library/issues.

📄 License

Apache-2.0. See LICENSE.

👨‍💻 Author

José Eduardo Trindade E Marques Company: AuronForge 🚀 Email: [email protected] LinkedIn: https://linkedin.com/in/edu-marques29