![\"Ambiten\"](\"https://raw.githubusercontent.com/AmbitenHQ/ambiten/main/assets/ambiten-mark-192x192.png\")
\n
\n Structured logging and runtime-aware telemetry for modern applications.\n
\n\n\n Context-aware logs, transport pipelines, metrics tracking, resilience handling, and production-grade operational visibility for Ambiten systems and standalone Node.js applications.\n
\n\n\n\n---\n\n## Overview\n\n`@ambiten/logger` provides the structured logging and telemetry layer for the Ambiten ecosystem.\n\nIt is designed for runtime-aware systems where logs are not merely developer output, but operational events attached to execution boundaries.\n\nThe logger can operate independently inside standard Node.js applications, APIs, workers, queues, GraphQL servers, and serverless environments. Inside the Ambiten runtime, it becomes context-aware and can automatically enrich log entries with request identifiers, tenant metadata, database targets, collection names, runtime metadata, and execution context.\n\nRather than treating logging as scattered console output, `@ambiten/logger` treats logs as structured runtime events that can move through transport pipelines, observability systems, metrics tracking, resilience layers, and production debugging workflows.\n\n## Installation\n\n```bash\nnpm install @ambiten/logger\n```\n\n## Quick Start\n\n```ts\nimport { createLogger, consoleTransport } from \"@ambiten/logger\";\n\nconst logger = createLogger({\n level: \"info\",\n transports: [\n consoleTransport()\n ]\n});\n\nlogger.info(\"Application started\");\n```\n\nStructured metadata can be attached directly to log entries.\n\n```ts\nlogger.error(\"Query failed\", {\n tenantId: \"tenant-a\",\n requestId: \"req-001\",\n operation: \"findOne\"\n});\n```\n\nThe logger keeps metadata structured internally so transports can serialize, batch, forward, or persist logs without reconstructing runtime meaning from formatted strings.\n\n## What Ambiten Logger Is\n\nAmbiten Logger is not a console wrapper.\n\nIt is a structured telemetry pipeline for runtime execution.\n\nTraditional loggers focus on writing messages. Ambiten Logger focuses on preserving operational meaning as execution moves across requests, middleware, models, workers, transactions, queues, adapters, and distributed infrastructure.\n\nEvery emitted log becomes a structured runtime event that can participate in formatting, filtering, buffering, batching, metrics tracking, transport routing, and resilience handling.\n\n```text\nApplication Runtime\n ↓\nStructured Log Entry\n ↓\nTransport Pipeline\n ↓\nObservability Destination\n```\n\n## Structured Logging\n\nAmbiten Logger preserves logs as structured runtime entries.\n\n```ts\nlogger.info(\"User created\", {\n userId: \"usr_123\",\n tenantId: \"tenant-a\",\n route: \"/register\"\n});\n```\n\nA structured log entry can preserve fields such as timestamps, severity levels, runtime metadata, source information, execution context, and operational payloads.\n\nThis makes logs easier to index, search, filter, aggregate, and correlate inside systems such as Elasticsearch, Loki, OpenSearch, Datadog, CloudWatch, or custom telemetry pipelines.\n\nText output remains useful during local development, but the internal logging model remains structured.\n\n## Context-Aware Logging\n\nWhen used with the Ambiten runtime, the logger can inherit execution metadata from the active runtime context.\n\n```ts\nawait AmbitenContext.run(\n {\n tenantId: \"enterprise-a\",\n requestId: \"req-992\"\n },\n async () => {\n logger.info(\"Processing request\");\n }\n);\n```\n\nLogs emitted during that execution boundary can automatically preserve runtime metadata such as tenant identity, request scope, database name, collection name, operation metadata, transaction state, and logger metadata.\n\nThis is especially valuable in multi-tenant systems and distributed applications where operational visibility depends on being able to reconstruct execution flow across layers.\n\n## Transport Pipeline\n\nAmbiten Logger separates log creation from log delivery.\n\nApplications emit structured runtime events. Transports decide where those events go.\n\n```ts\nimport {\n createLogger,\n consoleTransport,\n createRotatingFileTransporter\n} from \"@ambiten/logger\";\n\nconst logger = createLogger({\n json: true,\n transports: [\n consoleTransport(),\n createRotatingFileTransporter({\n filename: \"./logs/runtime.log\",\n frequency: \"daily\",\n backupCount: 7,\n compress: true\n })\n ]\n});\n```\n\nThe transport layer is composable and can support console output, static files, rotating files, buffered delivery, asynchronous batching, HTTP ingestion, Loki, Elasticsearch, and custom infrastructure.\n\nBecause every transport receives normalized runtime entries, observability infrastructure can evolve without changing application logging logic.\n\n## Metrics and Runtime Signals\n\nThe logger can track operational metrics about the logging pipeline itself.\n\nMetrics can expose activity such as processed log volume, transport dispatches, successful writes, buffer flushes, file rotations, dropped logs, and transport errors.\n\n```ts\nconst logger = createLogger({\n enableMetrics: {\n enabled: true,\n logInterval: 60_000\n }\n});\n```\n\nThese metrics are not application logs. They describe the behavior of the logging infrastructure so teams can understand transport pressure, delivery failures, buffering behavior, and runtime throughput under production workloads.\n\n## Resilience\n\nProduction logging infrastructure can fail.\n\nRemote endpoints may become unavailable, networks may degrade, filesystems may stall, or observability backends may reject ingestion under pressure.\n\nAmbiten Logger supports resilience patterns that help isolate logging failures from application execution.\n\n```ts\nconst transport = createResilientTransporter(\n createHttpTransport(process.env.LOG_INGEST_URL!)\n);\n```\n\nRetries and circuit breaker behavior help prevent unstable observability infrastructure from creating runtime instability.\n\nA transport failure should remain an operational signal, not become an application failure.\n\n## Production Usage\n\nIn production, structured logging should be treated as part of the operational architecture.\n\nA typical production setup uses JSON output, context-aware metadata, persistent or remote transports, graceful shutdown, and selective metrics tracking.\n\n```ts\nconst logger = createLogger({\n level: \"info\",\n json: true,\n transports: [\n createRotatingFileTransporter({\n filename: \"./logs/runtime.log\",\n frequency: \"daily\",\n backupCount: 7,\n compress: true\n })\n ],\n enableMetrics: {\n enabled: true,\n logInterval: 60_000\n }\n});\n```\n\nHigh-throughput systems should prefer buffering or asynchronous batching so logging does not introduce unnecessary filesystem or network pressure during sustained traffic.\n\n## Runtime Environments\n\n`@ambiten/logger` is designed to operate across different execution environments.\n\nIt can be used in local development, production APIs, background workers, queue processors, GraphQL systems, serverless functions, and containerized infrastructure.\n\nThe logging model remains consistent across environments because the logger operates on structured runtime entries before transport delivery occurs.\n\n## Relationship with Ambiten\n\n`@ambiten/logger` is part of the wider Ambiten runtime ecosystem.\n\nIt complements `@ambiten/core`, runtime instrumentation, adapter-driven execution, transaction-aware workflows, middleware pipelines, tenant-aware context propagation, and production observability tooling.\n\nThe package can still be used independently in non-Ambiten systems, but its full value appears when runtime context and structured execution metadata are available.\n\n## Documentation\n\nThe official Ambiten documentation includes guides for structured logging, context-aware telemetry, transport pipelines, production configuration, metrics tracking, resilience handling, testing, shutdown behavior, and observability integration.\n\nDocumentation:\n\nhttps://docs.ambiten.dev\n\n## Philosophy\n\n> Logs should describe runtime behavior, not just developer intent.\n\nAmbiten Logger exists to make operational behavior visible, structured, and traceable across modern runtime systems.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}![\"npm](\"https://img.shields.io/npm/v/@ambiten/logger?color=0ea5e9&label=npm&style=flat-square\")
\n![\"GitHub](\"https://img.shields.io/github/stars/AmbitenHQ/ambiten?style=flat-square&color=1E88E5\")
\n ![\"structured](\"https://img.shields.io/badge/structured-logging-6366f1?style=flat-square\"){kind=icon}
\n![\"context](\"https://img.shields.io/badge/context-aware-14b8a6?style=flat-square\"){kind=icon}
\n