unnbound-logger-sdk 3.1.0-beta.1 → 3.1.1

package/README.md

@@ -22,7 +22,7 @@ logger.trace('Trace information');
 
 // Log with object messages (merged into top level)
 logger.info({ event: 'user_login', userId: '123' }, 'Event received.');
-// Results in: { "event": "user_login", "userId": "123", "message": "Application started", ... }
+// Results in: { "event": "user_login", "userId": "123", "message": "Event received.", ... }
 
 // Log with both string message and metadata (metadata merged into top level)
 logger.info({ userId: '123' }, 'User logged in');
@@ -44,7 +44,7 @@ interface Log<T extends LogType = 'general'> {
   serviceId?: string; // From UNNBOUND_SERVICE_ID environment variable
   deploymentId?: string; // From UNNBOUND_DEPLOYMENT_ID environment variable
   workflowId?: string; // From UNNBOUND_WORKFLOW_ID environment variable
-  environment?: string; // From ENVIRONMENT environment variable
+  environment?: string; // From WORKFLOW_ENV, UNNBOUND_ENVIRONMENT, or ENVIRONMENT, whichever is set first
   err?: unknown; // Only present for Error objects
   duration?: number; // Duration in milliseconds for span operations
   http?: T extends 'http' ? HttpPayload : never;
@@ -87,7 +87,7 @@ export UNNBOUND_DEPLOYMENT_ID="v1.2.3-prod-20231201"
 UNNBOUND_DEPLOYMENT_ID=v1.2.3-prod-20231201
 ```
 
-If the environment variables are not set, the fields will be empty strings. These fields help with:
+If the environment variables are not set, the fields are omitted from the log entry. These fields help with:
 
 - **Workflow ID**: Unique identifier for the workflow (logged in each entry)
 - **Workflow URL**: Used internally for URL construction in webhook endpoints (not logged as a field)
@@ -98,36 +98,55 @@ If the environment variables are not set, the fields will be empty strings. Thes
 
 ## Object Logging Behavior
 
-The logger uses Pino's standard behavior for handling different message types:
+The logger follows Pino's argument order. **The context object comes first and the message comes second.**
 
-### String Messages with Metadata
+The results below show only the fields each call contributes. The leading `...` stands for the
+fields the logger adds itself: `level`, `logId`, and `source` on every entry, plus `workflowId`,
+`serviceId`, `deploymentId`, and `environment` when their environment variables are set, and
+`traceId` and `spanId` when the call runs inside a trace or span. See [Log Format](#log-format).
 
-When you pass a string message with additional metadata, the metadata is merged into the top level:
+### Context Object with a Message
 
 ```typescript
-logger.info('User action completed', { userId: '123', action: 'login' });
-// Result: { "message": "User action completed", "userId": "123", "action": "login", ... }
+logger.info({ userId: '123', action: 'login' }, 'User action completed');
+// Result: { ..., "userId": "123", "action": "login", "message": "User action completed" }
 ```
 
-### Object Messages
+Every property of the object is merged into the top level of the log entry.
+
+A context object always needs a message alongside it. `ILogger` declares each level as
+`(object, message)` or `(message)` and nothing else, so `logger.info({ userId: '123' })` does not
+compile.
+
+### Reversing the Order Drops Your Context
 
-When you pass an object as the message, it's merged into the top level:
+Passing the message first discards the object:
 
 ```typescript
-logger.info({ userId: '123', action: 'login' });
-// Result: { "userId": "123", "action": "login", "message": "Application started", ... }
+logger.info('User action completed', { userId: '123', action: 'login' });
+// Result: { ..., "message": "User action completed" }
+//         userId and action are gone. No error, no warning.
 ```
 
+TypeScript rejects the reversed order, because `info` is declared only as `(object, message)` or
+`(message)`. Running `tsc` reports `Argument of type 'string' is not assignable to parameter of
+type 'object'`, so a build catches the mistake. Transpile-only runners such as `tsx` do not
+type-check, so under those the fields disappear at runtime with no error. Always put the object
+first.
+
 ### Error Objects
 
-Error objects are handled specially and include serialized error information:
+`error` takes an object containing `err` plus a message:
 
 ```typescript
-logger.error({ err: new Error('Something went wrong') });
-// Result: { "message": "Error", "err": { "name": "Error", "message": "Something went wrong", "stack": "..." }, ... }
+logger.error({ err: new Error('Connection refused') }, 'Failed to sync order.');
+// Result: { ...,
+//           "err": { "type": "Error", "message": "Connection refused", "stack": "..." },
+//           "message": "Failed to sync order." }
 ```
 
-This follows Pino's standard behavior where all object properties are merged into the top level of the log entry.
+Errors are serialized by Pino's `stdSerializers.err`, which emits `type`, `message`, and `stack`.
+Unlike the other levels, `error` has no single-argument overload, so the message is required.
 
 ## HTTP Request/Response Logging
 
@@ -206,11 +225,10 @@ const uploadFile = async (filePath: string, content: string) => {
   return await startSpan(
     'SFTP upload operation',
     async () => {
-      // Your SFTP upload logic here
-      logger.info('Uploading file', { filePath, contentLength: content.length });
+      logger.info({ filePath, contentLength: content.length }, 'Uploading file');
       return { success: true, filePath };
     },
-    (result) => ({
+    () => ({
       type: 'sftp',
       sftp: {
         host: 'sftp.example.com',
@@ -291,8 +309,7 @@ In case the function doesn't run inside an HTTP handler (for example a cron job)
 import { withTrace } from 'unnbound-logger-sdk';
 
 const operation = async (value: number) => {
-  // This will log a { traceId, value }
-  logger.info('Processing value', { value });
+  logger.info({ value }, 'Processing value');
   return value * 2;
 };
 
@@ -306,19 +323,14 @@ The `startSpan` function allows you to wrap any async operation with automatic s
 ```typescript
 import { logger, startSpan } from 'unnbound-logger-sdk';
 
-// Example: Wrapping a function with span tracking
 const operation = async (value: number) => {
-  logger.info('Processing value', { value });
+  logger.info({ value }, 'Processing value');
   return value * 2;
 };
 
-// Wrap the function with span tracking
-const result = await startSpan('Processing operation', operation, () => ({
+const result = await startSpan('Processing operation', () => operation(21), () => ({
   operationType: 'calculation',
 }));
-
-// Execute the function
-const result = await startSpan('Processing operation', () => operation(21)); // Returns 42
 ```
 
 _Note: In case the `traceId` is missing from the context, `startSpan` will generate one. It is recommended to use a single `traceId` across your handler though, so always consider using `traceMiddleware` and `withTrace` to inject the `traceId` instead of relying on `startSpan` to create one._
@@ -329,15 +341,15 @@ The span context is maintained across async operations:
 
 ```typescript
 const asyncOperation = async (value: number) => {
-  logger.info('First step', { value });
+  logger.info({ value }, 'First step');
 
   await someAsyncWork();
 
-  logger.info('Second step', { value });
+  logger.info({ value }, 'Second step');
   return value * 2;
 };
 
-const result = await startSpan('Async operation', asyncOperation, () => ({
+const result = await startSpan('Async operation', () => asyncOperation(21), () => ({
   operationType: 'async_calculation',
 }));
 ```
@@ -452,5 +464,5 @@ console.log(traceId); // "550e8400-e29b-41d4-a716-446655440000"
 - `UNNBOUND_SERVICE_ID` - Service identifier (included in all logs)
 - `UNNBOUND_DEPLOYMENT_ID` - Deployment identifier (included in all logs)
 - `UNNBOUND_WORKFLOW_URL` - Base URL for webhook endpoint logging
-- `ENVIRONMENT` - Environment name (included in all logs)
-- `LOG_LEVEL` - Log level (default: 'info')
+- `WORKFLOW_ENV`, `UNNBOUND_ENVIRONMENT`, `ENVIRONMENT` - Environment name, read in that order (included in all logs)
+- `LOG_LEVEL` - Log level (default: 'debug')

package/dist/axios.d.ts

@@ -17,8 +17,10 @@ interface HttpClientOptions extends HttpOptions<GetPayload> {
     silent?: boolean;
 }
 /**
- * Wraps an axios instance to add tracing and span tracking
- * @param axios - The axios instance to wrap
+ * Wraps an axios instance to add tracing and span tracking.
+ *
+ * Repeated calls for the same instance are no-ops; the first call's options remain active.
+ * @param client - The axios instance to wrap
  * @param options - Configuration options for HTTP tracing
  * @returns The wrapped axios instance with span tracking
  */

package/dist/axios.js

@@ -37,9 +37,12 @@ const buildOutgoingHttpPayload = (config, res, redact) => ({
 });
 const getNoopPayload = () => ({});
 const onNoopRequest = (config, callback) => callback(config);
+const tracedMarker = Symbol.for('unnbound-logger-sdk.traceAxios.traced');
 /**
- * Wraps an axios instance to add tracing and span tracking
- * @param axios - The axios instance to wrap
+ * Wraps an axios instance to add tracing and span tracking.
+ *
+ * Repeated calls for the same instance are no-ops; the first call's options remain active.
+ * @param client - The axios instance to wrap
  * @param options - Configuration options for HTTP tracing
  * @returns The wrapped axios instance with span tracking
  */
@@ -49,6 +52,8 @@ const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRout
     getPayload: getNoopPayload,
     onRequest: onNoopRequest,
 }) => {
+    if (tracedMarker in client)
+        return client;
     const redact = typeof redactOptions === 'boolean' ? { response: redactOptions } : redactOptions;
     const createSpanWrappedRequest = (originalMethod, method) => {
         const { headers: defaultHeaders, ...partialDefaultConfig } = client.defaults;
@@ -93,6 +98,7 @@ const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRout
         const func = createSpanWrappedRequest(request, method);
         client[method] = (url, config) => func({ ...config, method, url });
     });
+    Object.defineProperty(client, tracedMarker, { value: true });
     return client;
 };
 exports.traceAxios = traceAxios;

package/dist/logger.js

@@ -11,7 +11,6 @@ const internal_1 = require("./internal");
 const storage_1 = require("./storage");
 const levels = new Set(['debug', 'info', 'warn', 'error']);
 const workflowEnvironment = process.env.WORKFLOW_ENV ?? process.env.UNNBOUND_ENVIRONMENT ?? process.env.ENVIRONMENT;
-const stackEnvironment = process.env.ENVIRONMENT ?? process.env.APP_ENV;
 const formatLevel = (level) => ({ level });
 const formatLog = (log, visited = new WeakSet()) => {
     // Prevent infinite loops from circular references
@@ -56,7 +55,6 @@ const loggerOptions = {
     level: process.env.LOG_LEVEL ?? 'debug',
     base: {
         environment: workflowEnvironment,
-        stack: stackEnvironment,
         workflowId: process.env.UNNBOUND_WORKFLOW_ID,
         serviceId: process.env.UNNBOUND_SERVICE_ID,
         deploymentId: process.env.UNNBOUND_DEPLOYMENT_ID,

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "unnbound-logger-sdk",
   "description": "A structured logging library with TypeScript support using Pino. Provides consistent, well-typed logging with automatic logId, workflowId, traceId, and deploymentId tracking across operational contexts.",
-  "version": "3.1.0-beta.1",
+  "version": "3.1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run src",
+    "typecheck": "tsc --noEmit",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "prepublishOnly": "npm run build",
+    "start:example": "tsx watch examples/node-express.ts",
+    "version:bump": "npm version patch"
+  },
   "keywords": [
     "logging",
     "structured-logging",
@@ -56,14 +66,5 @@
   "engines": {
     "node": ">=22"
   },
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run src",
-    "typecheck": "tsc --noEmit",
-    "format": "biome format --write .",
-    "format:check": "biome format .",
-    "start:example": "tsx watch examples/node-express.ts",
-    "version:bump": "npm version patch"
-  }
-}
+  "sideEffects": false
+}