{"_id":"@arborship/logger","name":"@arborship/logger","dist-tags":{"latest":"1.0.164"},"versions":{"1.0.164":{"name":"@arborship/logger","version":"1.0.164","description":"Structured logging for Marsman ecosystem with correlation ID support","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"build":"rm -rf dist tsconfig.tsbuildinfo && corepack yarn tsc -p tsconfig.json","typecheck":"tsc --noEmit --incremental --tsBuildInfoFile tsconfig.typecheck.tsbuildinfo","prepublishOnly":"corepack yarn build"},"keywords":["logging","structured","pino","correlation-id","levi"],"author":{"name":"MarsMan LLC"},"license":"Apache-2.0","dependencies":{"@opentelemetry/api":"^1.9.0","pino":"^9.0.0"},"publishConfig":{"registry":"https://registry.npmjs.org/","access":"public"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0","vitest":"^4.0.18"},"repository":{"type":"git","url":"git+https://github.com/arborship/arborship.git","directory":"packages/infrastructure/logger"},"homepage":"https://github.com/arborship/arborship/tree/main/packages/infrastructure/logger#readme","bugs":{"url":"https://github.com/arborship/arborship/issues"},"engines":{"node":">=18.0.0"},"_id":"@arborship/logger@1.0.164","_integrity":"sha512-Vo/wOspHMzntsRJLMYqMhgRLIgJjXL9FKqvuRkGNATVQouJQ/lL2/cvDM3qgLVAcJgMghEB/KFs4q/EnBRVTVg==","_resolved":"/tmp/logger.tgz","_from":"file:/tmp/logger.tgz","_nodeVersion":"22.23.2","_npmVersion":"11.19.0","dist":{"integrity":"sha512-Vo/wOspHMzntsRJLMYqMhgRLIgJjXL9FKqvuRkGNATVQouJQ/lL2/cvDM3qgLVAcJgMghEB/KFs4q/EnBRVTVg==","shasum":"ff770f1bcc035738bc196b4a4a0c127ad44db6f0","tarball":"https://registry.npmjs.org/@arborship/logger/-/logger-1.0.164.tgz","fileCount":7,"unpackedSize":39801,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDlpB+q8WETKtNXbpRtWhDrrn/cCjFzyHY8/cWcF3bdWAIgVZOr5pn+2bfSxGobcVPc+Kcob4zNOx8qyEFj4Gm+6/c="}]},"_npmUser":{"name":"arborship-official","email":"patrickjholloway@gmail.com"},"directories":{},"maintainers":[{"name":"arborship-official","email":"patrickjholloway@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/logger_1.0.164_1788485888343_0.07435531572116139"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-04T01:38:08.089Z","1.0.164":"2026-09-04T01:38:08.484Z","modified":"2026-09-04T01:38:08.750Z"},"maintainers":[{"name":"arborship-official","email":"patrickjholloway@gmail.com"}],"description":"Structured logging for Marsman ecosystem with correlation ID support","homepage":"https://github.com/arborship/arborship/tree/main/packages/infrastructure/logger#readme","keywords":["logging","structured","pino","correlation-id","levi"],"repository":{"type":"git","url":"git+https://github.com/arborship/arborship.git","directory":"packages/infrastructure/logger"},"author":{"name":"MarsMan LLC"},"bugs":{"url":"https://github.com/arborship/arborship/issues"},"license":"Apache-2.0","readme":"# @arborship/logger\n\nStructured JSON logging for the Levi ecosystem with correlation ID support.\n\n## OTEL Scope (MAR-41)\n\nThis package is responsible for **structured log emission only**. It depends on\n`@opentelemetry/api` (the zero-dependency facade) to read the active span and inject\n`trace_id` / `span_id` fields into log lines when tracing is active.\n\n**In scope for this package:**\n- Structured NDJSON log records emitted to stdout via pino.\n- Automatic `trace_id` / `span_id` injection when an active OTEL span is present.\n- `correlationId` fallback when no OTEL span is active.\n\n**Out of scope (handled by `@arborship/otel`):**\n- OTEL SDK initialisation (`NodeSDK.start` / `shutdown`).\n- Span creation, propagation, or OTLP export.\n- Metrics collection or export.\n\nServices that want distributed tracing must call `initOtel()` from\n`@arborship/otel` before the first log call. If the SDK is absent the api\nfalls back to a no-op provider and logs carry only `correlationId`.\n\n## Installation\n\n```bash\nnpm install @arborship/logger\n```\n\n## Quick Start\n\n```typescript\nimport { createLogger, setCorrelationId } from '@arborship/logger';\n\nconst logger = createLogger({ component: 'levi' });\n\nlogger.info({ vmName: 'job-123' }, 'VM spawned');\n// Output: {\"level\":\"INFO\",\"time\":\"...\",\"component\":\"levi\",\"vmName\":\"job-123\",\"msg\":\"VM spawned\"}\n\n// With correlation ID\nsetCorrelationId('job-abc');\nlogger.info('Job started');\n// Output: {\"level\":\"INFO\",\"time\":\"...\",\"component\":\"levi\",\"correlationId\":\"job-abc\",\"msg\":\"Job started\"}\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `LOG_LEVEL` | `info` | Log level: trace, debug, info, warn, error, fatal |\n| `LOG_FORMAT` | `json` | Output format: `json` or `pretty` |\n\n## Features\n\n- **Structured JSON logging** - Easy to parse and query\n- **Correlation ID propagation** - Trace requests across components\n- **Component attribution** - Know which service logged what\n- **Child loggers** - Add persistent context to log groups\n- **Pino-powered** - Fast, low-overhead logging\n\n## Components\n\nAll Levi ecosystem components use the same logger:\n\n- `levi` - Supervisor API server\n- `levi` - VM orchestrator CLI\n- `vm-agent` - Worker agent in spawned VMs\n- `stackenv` - Tool configuration manager\n\n## API Reference\n\n### createLogger(config)\n\nCreate a logger instance.\n\n```typescript\ncreateLogger({\n  component: 'levi',           // Required: component name\n  level: 'debug',                // Optional: log level\n  format: 'json',                // Optional: 'json' or 'pretty'\n  baseFields: { env: 'prod' },   // Optional: additional fields\n});\n```\n\n### setCorrelationId(id) / getCorrelationId(id)\n\nManage correlation ID for cross-component tracing.\n\n```typescript\nsetCorrelationId('job-abc-123');\nconst id = getCorrelationId(); // 'job-abc-123'\n```\n\n### childLogger(logger, context)\n\nCreate a child logger with persistent context.\n\n```typescript\nconst vmLogger = childLogger(logger, { vmName: 'job-123' });\nvmLogger.info('VM starting'); // Always includes vmName\n```\n\n## Log Format\n\nAll logs are structured JSON:\n\n```json\n{\n  \"level\": \"INFO\",\n  \"time\": \"2025-01-16T22:30:00.000Z\",\n  \"component\": \"levi\",\n  \"correlationId\": \"job-abc-123\",\n  \"vmName\": \"job-123\",\n  \"msg\": \"VM spawned\"\n}\n```\n\n## Log format with active OTEL span\n\nWhen `@arborship/otel` has been initialised and a span is active, logs include\n`trace_id` and `span_id` instead of `correlationId`:\n\n```json\n{\n  \"level\": \"INFO\",\n  \"time\": \"2025-01-16T22:30:00.000Z\",\n  \"component\": \"leviathan\",\n  \"trace_id\": \"4bf92f3577b34da6a3ce929d0e0e4736\",\n  \"span_id\": \"00f067aa0ba902b7\",\n  \"jobId\": \"job-abc\",\n  \"msg\": \"Job dispatched\"\n}\n```\n\nSee `@arborship/otel` for the full OTEL scope decision and span boundary policy.\n\n## License\n\nApache-2.0 — see the LICENSE file in this package.\n","readmeFilename":"README.md","_rev":"1-12cd427a030f8a395a15240a4675b6a9"}