unnbound-logger-sdk 2.0.9 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +173 -211
- package/dist/index.js +9 -11
- package/package.json +20 -37
- package/dist/index.d.ts +0 -10
- package/dist/types.d.ts +0 -132
- package/dist/types.js +0 -5
- package/dist/unnbound-logger.d.ts +0 -124
- package/dist/unnbound-logger.js +0 -470
- package/dist/utils/http-status-messages.d.ts +0 -9
- package/dist/utils/http-status-messages.js +0 -55
- package/dist/utils/logger-utils.d.ts +0 -34
- package/dist/utils/logger-utils.js +0 -96
- package/dist/utils/trace-context.d.ts +0 -10
- package/dist/utils/trace-context.js +0 -23
- package/dist/utils/with-trace.d.ts +0 -7
- package/dist/utils/with-trace.js +0 -20
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Unnbound Logger
|
|
2
2
|
|
|
3
|
-
A structured logging library with TypeScript support built on Pino. Provides consistent, well-typed logging across different operational contexts. All logs are output in JSON format for better machine readability and parsing.
|
|
3
|
+
A structured logging library with TypeScript support built on Pino. Provides consistent, well-typed logging across different operational contexts with automatic trace and span tracking. All logs are output in JSON format for better machine readability and parsing.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -11,57 +11,40 @@ npm install unnbound-logger
|
|
|
11
11
|
## Basic Usage
|
|
12
12
|
|
|
13
13
|
```typescript
|
|
14
|
-
import {
|
|
15
|
-
|
|
16
|
-
// Create a new logger instance
|
|
17
|
-
const logger = new UnnboundLogger();
|
|
14
|
+
import { logger } from 'unnbound-logger';
|
|
18
15
|
|
|
19
16
|
// Log with string messages
|
|
20
17
|
logger.info('Application started');
|
|
21
18
|
logger.warn('Resource usage high');
|
|
22
|
-
logger.error(new Error('Database connection failed'));
|
|
19
|
+
logger.error({ err: new Error('Database connection failed') }, 'Something bad happened');
|
|
23
20
|
logger.debug('Debug information');
|
|
24
21
|
|
|
25
|
-
// Log with object messages
|
|
26
|
-
logger.info({
|
|
27
|
-
|
|
28
|
-
userId: '123',
|
|
29
|
-
timestamp: new Date().toISOString()
|
|
30
|
-
});
|
|
31
|
-
|
|
32
|
-
// Log with both string message and metadata
|
|
33
|
-
logger.info('User logged in', {
|
|
34
|
-
userId: '123',
|
|
35
|
-
timestamp: new Date().toISOString()
|
|
36
|
-
});
|
|
22
|
+
// Log with object messages (merged into top level)
|
|
23
|
+
logger.info({ event: 'user_login', userId: '123' }, 'Event received.');
|
|
24
|
+
// Results in: { "event": "user_login", "userId": "123", "message": "Application started", ... }
|
|
37
25
|
|
|
38
|
-
// Log with
|
|
39
|
-
logger.info(
|
|
40
|
-
|
|
41
|
-
{ timestamp: new Date().toISOString() }
|
|
42
|
-
);
|
|
26
|
+
// Log with both string message and metadata (metadata merged into top level)
|
|
27
|
+
logger.info({ userId: '123' }, 'User logged in');
|
|
28
|
+
// Results in: { "userId": "123", "message": "User logged in", ... }
|
|
43
29
|
```
|
|
44
30
|
|
|
45
31
|
## Log Format
|
|
46
32
|
|
|
47
|
-
All logs follow a standardized format:
|
|
33
|
+
All logs follow a standardized format based on Pino with additional context:
|
|
48
34
|
|
|
49
35
|
```typescript
|
|
50
36
|
interface Log<T extends LogType = 'general'> {
|
|
51
|
-
logId: string; // Unique identifier for each log entry
|
|
52
37
|
level: LogLevel; // "info" | "debug" | "error" | "warn"
|
|
53
|
-
type: T; // "general" | "httpRequest" | "httpResponse" | "sftpTransaction" | "dbQueryTransaction"
|
|
54
38
|
message: string;
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
deploymentId
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
duration: number; // Duration in milliseconds
|
|
39
|
+
traceId?: string; // Automatically included when in trace context
|
|
40
|
+
spanId?: string; // Automatically included when in span context
|
|
41
|
+
type?: T; // "general" | "http" | "sftp" | "dbQueryTransaction"
|
|
42
|
+
serviceId?: string; // From UNNBOUND_SERVICE_ID environment variable
|
|
43
|
+
deploymentId?: string; // From UNNBOUND_DEPLOYMENT_ID environment variable
|
|
44
|
+
workflowId?: string; // From UNNBOUND_WORKFLOW_ID environment variable
|
|
45
|
+
environment?: string; // From ENVIRONMENT environment variable
|
|
46
|
+
err?: unknown; // Only present for Error objects
|
|
47
|
+
duration?: number; // Duration in milliseconds for span operations
|
|
65
48
|
}
|
|
66
49
|
```
|
|
67
50
|
|
|
@@ -77,15 +60,15 @@ export UNNBOUND_WORKFLOW_ID="order-processing-12345"
|
|
|
77
60
|
export UNNBOUND_WORKFLOW_URL="https://workflows.example.com/order-processing-12345"
|
|
78
61
|
export UNNBOUND_SERVICE_ID="order-service"
|
|
79
62
|
|
|
80
|
-
# Or in your deployment configuration
|
|
63
|
+
# Or in your deployment configuration
|
|
81
64
|
UNNBOUND_WORKFLOW_ID=order-processing-12345
|
|
82
65
|
UNNBOUND_WORKFLOW_URL=https://workflows.example.com/order-processing-12345
|
|
83
66
|
UNNBOUND_SERVICE_ID=order-service
|
|
84
67
|
```
|
|
85
68
|
|
|
86
69
|
```typescript
|
|
87
|
-
//
|
|
88
|
-
|
|
70
|
+
// Import the logger - workflowId and serviceId are automatically set from environment
|
|
71
|
+
import { logger } from 'unnbound-logger';
|
|
89
72
|
```
|
|
90
73
|
|
|
91
74
|
### Deployment Tracking
|
|
@@ -109,35 +92,49 @@ If the environment variables are not set, the fields will be empty strings. Thes
|
|
|
109
92
|
- **Correlating issues**: Link problems to specific workflows and releases
|
|
110
93
|
- **Monitoring**: Track health and performance across workflows and deployments
|
|
111
94
|
|
|
95
|
+
## Object Logging Behavior
|
|
96
|
+
|
|
97
|
+
The logger uses Pino's standard behavior for handling different message types:
|
|
98
|
+
|
|
99
|
+
### String Messages with Metadata
|
|
100
|
+
|
|
101
|
+
When you pass a string message with additional metadata, the metadata is merged into the top level:
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
logger.info('User action completed', { userId: '123', action: 'login' });
|
|
105
|
+
// Result: { "message": "User action completed", "userId": "123", "action": "login", ... }
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Object Messages
|
|
109
|
+
|
|
110
|
+
When you pass an object as the message, it's merged into the top level:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
logger.info({ userId: '123', action: 'login' });
|
|
114
|
+
// Result: { "userId": "123", "action": "login", "message": "Application started", ... }
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Error Objects
|
|
118
|
+
|
|
119
|
+
Error objects are handled specially and include serialized error information:
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
logger.error({ err: new Error('Something went wrong') });
|
|
123
|
+
// Result: { "message": "Error", "err": { "name": "Error", "message": "Something went wrong", "stack": "..." }, ... }
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
This follows Pino's standard behavior where all object properties are merged into the top level of the log entry.
|
|
127
|
+
|
|
112
128
|
## HTTP Request/Response Logging
|
|
113
129
|
|
|
114
130
|
```typescript
|
|
115
|
-
import {
|
|
131
|
+
import { logger, traceMiddleware } from 'unnbound-logger';
|
|
116
132
|
import express from 'express';
|
|
117
133
|
|
|
118
134
|
const app = express();
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
app.use((req, res, next) => {
|
|
123
|
-
// Log the request and get the request ID
|
|
124
|
-
const requestId = logger.httpRequest(req, {
|
|
125
|
-
startTime: Date.now()
|
|
126
|
-
});
|
|
127
|
-
|
|
128
|
-
// Store the request ID in res.locals for later use
|
|
129
|
-
res.locals.requestId = requestId;
|
|
130
|
-
|
|
131
|
-
// Add response listener to log the response
|
|
132
|
-
res.on('finish', () => {
|
|
133
|
-
logger.httpResponse(res, req, {
|
|
134
|
-
requestId,
|
|
135
|
-
startTime: res.locals.startTime
|
|
136
|
-
});
|
|
137
|
-
});
|
|
138
|
-
|
|
139
|
-
next();
|
|
140
|
-
});
|
|
135
|
+
|
|
136
|
+
// Apply trace middleware for automatic HTTP logging
|
|
137
|
+
app.use(traceMiddleware());
|
|
141
138
|
|
|
142
139
|
// Example route
|
|
143
140
|
app.post('/api/users', (req, res) => {
|
|
@@ -146,11 +143,13 @@ app.post('/api/users', (req, res) => {
|
|
|
146
143
|
});
|
|
147
144
|
```
|
|
148
145
|
|
|
149
|
-
The
|
|
146
|
+
The trace middleware automatically captures:
|
|
147
|
+
|
|
150
148
|
- Request method, URL, body, and headers (filtered for security)
|
|
151
149
|
- Response status code, body, and headers (filtered for security)
|
|
152
150
|
- Request duration
|
|
153
|
-
- Trace ID and
|
|
151
|
+
- Trace ID and span ID for correlation
|
|
152
|
+
- Automatic span tracking for the entire request lifecycle
|
|
154
153
|
|
|
155
154
|
### Full URL Logging for Webhook Endpoints
|
|
156
155
|
|
|
@@ -170,13 +169,12 @@ export UNNBOUND_WORKFLOW_URL="https://api.yourservice.com"
|
|
|
170
169
|
|
|
171
170
|
```typescript
|
|
172
171
|
import express from 'express';
|
|
173
|
-
import {
|
|
172
|
+
import { traceMiddleware } from 'unnbound-logger';
|
|
174
173
|
|
|
175
174
|
const app = express();
|
|
176
|
-
const logger = new UnnboundLogger();
|
|
177
175
|
|
|
178
176
|
// Apply trace middleware for automatic logging
|
|
179
|
-
app.use(
|
|
177
|
+
app.use(traceMiddleware());
|
|
180
178
|
|
|
181
179
|
// Webhook endpoints - URLs automatically logged with full domain
|
|
182
180
|
app.post('/webhooks/stripe', (req, res) => {
|
|
@@ -192,67 +190,6 @@ app.post('/webhooks/github', (req, res) => {
|
|
|
192
190
|
|
|
193
191
|
This ensures webhook logs contain the complete URL for easy debugging and monitoring.
|
|
194
192
|
|
|
195
|
-
## SFTP Transaction Logging
|
|
196
|
-
|
|
197
|
-
For logging SFTP operations:
|
|
198
|
-
|
|
199
|
-
```typescript
|
|
200
|
-
import { UnnboundLogger } from 'unnbound-logger';
|
|
201
|
-
|
|
202
|
-
const logger = new UnnboundLogger();
|
|
203
|
-
|
|
204
|
-
// Log an SFTP upload
|
|
205
|
-
logger.sftpTransaction({
|
|
206
|
-
host: 'sftp.example.com',
|
|
207
|
-
username: 'ftpuser',
|
|
208
|
-
operation: 'upload',
|
|
209
|
-
path: '/uploads/file.txt',
|
|
210
|
-
status: 'success',
|
|
211
|
-
bytesTransferred: 1024
|
|
212
|
-
});
|
|
213
|
-
|
|
214
|
-
// Log an SFTP download with failure
|
|
215
|
-
logger.sftpTransaction({
|
|
216
|
-
host: 'sftp.example.com',
|
|
217
|
-
username: 'ftpuser',
|
|
218
|
-
operation: 'download',
|
|
219
|
-
path: '/downloads/file.txt',
|
|
220
|
-
status: 'failure'
|
|
221
|
-
}, {
|
|
222
|
-
startTime: Date.now() - 5000 // Started 5 seconds ago
|
|
223
|
-
});
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
## Database Query Transaction Logging
|
|
227
|
-
|
|
228
|
-
For logging database operations:
|
|
229
|
-
|
|
230
|
-
```typescript
|
|
231
|
-
import { UnnboundLogger } from 'unnbound-logger';
|
|
232
|
-
|
|
233
|
-
const logger = new UnnboundLogger();
|
|
234
|
-
|
|
235
|
-
// Log a successful database query
|
|
236
|
-
logger.dbQueryTransaction({
|
|
237
|
-
instance: 'localhost:5432',
|
|
238
|
-
vendor: 'postgres',
|
|
239
|
-
query: 'SELECT * FROM users WHERE active = true',
|
|
240
|
-
status: 'success',
|
|
241
|
-
rowsReturned: 150
|
|
242
|
-
});
|
|
243
|
-
|
|
244
|
-
// Log a failed database operation
|
|
245
|
-
logger.dbQueryTransaction({
|
|
246
|
-
instance: 'prod-db-cluster',
|
|
247
|
-
vendor: 'mysql',
|
|
248
|
-
query: 'UPDATE users SET last_login = NOW()',
|
|
249
|
-
status: 'failure',
|
|
250
|
-
rowsAffected: 0
|
|
251
|
-
}, {
|
|
252
|
-
duration: 2500 // Operation took 2.5 seconds
|
|
253
|
-
});
|
|
254
|
-
```
|
|
255
|
-
|
|
256
193
|
## Middleware Usage
|
|
257
194
|
|
|
258
195
|
### Express Trace Middleware
|
|
@@ -260,155 +197,180 @@ logger.dbQueryTransaction({
|
|
|
260
197
|
The library provides a comprehensive trace middleware for Express applications that automatically handles trace context and HTTP logging:
|
|
261
198
|
|
|
262
199
|
```typescript
|
|
263
|
-
import {
|
|
200
|
+
import { traceMiddleware } from 'unnbound-logger';
|
|
264
201
|
import express from 'express';
|
|
265
202
|
|
|
266
203
|
const app = express();
|
|
267
|
-
const logger = new UnnboundLogger();
|
|
268
204
|
|
|
269
205
|
// Apply the comprehensive trace middleware globally
|
|
270
|
-
app.use(
|
|
206
|
+
app.use(traceMiddleware());
|
|
271
207
|
```
|
|
272
208
|
|
|
273
209
|
The trace middleware automatically:
|
|
210
|
+
|
|
274
211
|
- Generates and maintains trace IDs across the request lifecycle
|
|
275
|
-
- Logs incoming requests with method, URL, headers, and body
|
|
212
|
+
- Logs incoming requests with method, URL, headers, and body
|
|
276
213
|
- Logs outgoing responses with status code, headers, body, and duration
|
|
277
214
|
- Measures request duration automatically
|
|
278
215
|
- Handles errors and logs them appropriately
|
|
279
216
|
- Captures response bodies for logging
|
|
217
|
+
- Creates spans for the entire request lifecycle
|
|
280
218
|
|
|
281
219
|
### Axios Trace Middleware
|
|
282
220
|
|
|
283
221
|
For comprehensive logging of outgoing HTTP requests made with Axios:
|
|
284
222
|
|
|
285
223
|
```typescript
|
|
286
|
-
import {
|
|
224
|
+
import { traceAxios } from 'unnbound-logger';
|
|
287
225
|
import axios from 'axios';
|
|
288
226
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
// Add both request and response interceptors for complete HTTP logging
|
|
292
|
-
axios.interceptors.request.use(
|
|
293
|
-
logger.axiosTraceMiddleware.onFulfilled,
|
|
294
|
-
logger.axiosTraceMiddleware.onRejected
|
|
295
|
-
);
|
|
296
|
-
|
|
297
|
-
axios.interceptors.response.use(
|
|
298
|
-
logger.axiosResponseInterceptor.onFulfilled,
|
|
299
|
-
logger.axiosResponseInterceptor.onRejected
|
|
300
|
-
);
|
|
227
|
+
// Create an axios instance and wrap it with tracing
|
|
228
|
+
const client = traceAxios(axios.create());
|
|
301
229
|
|
|
302
|
-
// All requests made with
|
|
303
|
-
|
|
230
|
+
// All requests made with this client will be automatically logged
|
|
231
|
+
client.get('https://api.example.com/data');
|
|
304
232
|
```
|
|
305
233
|
|
|
306
234
|
The Axios middleware:
|
|
307
|
-
|
|
235
|
+
|
|
236
|
+
- Logs outgoing requests with method, URL, headers, and body
|
|
308
237
|
- Maintains trace context across requests by propagating trace IDs
|
|
309
238
|
- Logs successful responses with status, headers, body, and duration
|
|
310
239
|
- Logs error responses with detailed error information
|
|
240
|
+
- Creates spans for each HTTP request
|
|
311
241
|
- Supports request/response filtering through configuration
|
|
312
242
|
|
|
313
|
-
## Function Tracing with
|
|
243
|
+
## Function Tracing with startSpan
|
|
314
244
|
|
|
315
|
-
The `
|
|
245
|
+
The `startSpan` function allows you to wrap any async operation with automatic span tracking and logging. This is particularly useful for maintaining consistent trace IDs across async operations and distributed systems:
|
|
316
246
|
|
|
317
247
|
```typescript
|
|
318
|
-
import {
|
|
319
|
-
import { withTrace } from 'unnbound-logger/utils/with-trace';
|
|
320
|
-
import { traceContext } from 'unnbound-logger/utils/trace-context';
|
|
321
|
-
|
|
322
|
-
const logger = new UnnboundLogger();
|
|
248
|
+
import { logger, startSpan } from 'unnbound-logger';
|
|
323
249
|
|
|
324
|
-
// Example: Wrapping a function with
|
|
325
|
-
const operation = (value: number) => {
|
|
326
|
-
|
|
327
|
-
logger.info('Processing value', { value, traceId });
|
|
250
|
+
// Example: Wrapping a function with span tracking
|
|
251
|
+
const operation = async (value: number) => {
|
|
252
|
+
logger.info('Processing value', { value });
|
|
328
253
|
return value * 2;
|
|
329
254
|
};
|
|
330
255
|
|
|
331
|
-
// Wrap the function with
|
|
332
|
-
const
|
|
256
|
+
// Wrap the function with span tracking
|
|
257
|
+
const result = await startSpan('Processing operation', operation, () => ({
|
|
258
|
+
operationType: 'calculation',
|
|
259
|
+
}));
|
|
333
260
|
|
|
334
261
|
// Execute the function
|
|
335
|
-
const result =
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
### Using Custom Trace IDs
|
|
339
|
-
|
|
340
|
-
You can provide your own trace ID when wrapping a function:
|
|
341
|
-
|
|
342
|
-
```typescript
|
|
343
|
-
const customTraceId = 'custom-trace-123';
|
|
344
|
-
const tracedOperation = withTrace(operation, customTraceId);
|
|
262
|
+
const result = await startSpan('Processing operation', () => operation(21)); // Returns 42
|
|
345
263
|
```
|
|
346
264
|
|
|
347
265
|
### Async Operations
|
|
348
266
|
|
|
349
|
-
The
|
|
267
|
+
The span context is maintained across async operations:
|
|
350
268
|
|
|
351
269
|
```typescript
|
|
352
270
|
const asyncOperation = async (value: number) => {
|
|
353
|
-
|
|
354
|
-
logger.info('First step', { traceId: traceId1 });
|
|
271
|
+
logger.info('First step', { value });
|
|
355
272
|
|
|
356
273
|
await someAsyncWork();
|
|
357
274
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
// traceId1 and traceId2 will be the same
|
|
275
|
+
logger.info('Second step', { value });
|
|
276
|
+
return value * 2;
|
|
361
277
|
};
|
|
362
278
|
|
|
363
|
-
const
|
|
364
|
-
|
|
279
|
+
const result = await startSpan('Async operation', asyncOperation, () => ({
|
|
280
|
+
operationType: 'async_calculation',
|
|
281
|
+
}));
|
|
365
282
|
```
|
|
366
283
|
|
|
367
284
|
### Benefits
|
|
368
285
|
|
|
369
|
-
- Automatic
|
|
286
|
+
- Automatic span ID generation and tracking
|
|
370
287
|
- Consistent trace context across async operations
|
|
371
|
-
-
|
|
288
|
+
- Automatic duration measurement
|
|
289
|
+
- Error handling and logging
|
|
372
290
|
- Type-safe implementation
|
|
373
|
-
- Works with
|
|
374
|
-
- Maintains separate
|
|
375
|
-
|
|
376
|
-
> **Note:** When using
|
|
377
|
-
>
|
|
378
|
-
> ```typescript
|
|
379
|
-
> const operation = (value: number) => {
|
|
380
|
-
> logger.info('Processing value', { value }); // Trace ID is automatically included
|
|
381
|
-
> return value * 2;
|
|
382
|
-
> };
|
|
383
|
-
> ```
|
|
291
|
+
- Works with async functions
|
|
292
|
+
- Maintains separate span contexts for different operations
|
|
293
|
+
|
|
294
|
+
> **Note:** When using the logger within spans, you don't need to manually manage trace IDs. The logger automatically includes the current trace ID and span ID in all log entries.
|
|
384
295
|
|
|
385
296
|
## API Reference
|
|
386
297
|
|
|
387
|
-
###
|
|
298
|
+
### logger
|
|
388
299
|
|
|
389
|
-
The main logger
|
|
300
|
+
The main logger instance that provides all logging functionality using Pino.
|
|
390
301
|
|
|
391
|
-
####
|
|
302
|
+
#### Usage
|
|
392
303
|
|
|
393
304
|
```typescript
|
|
394
|
-
|
|
305
|
+
import { logger } from 'unnbound-logger';
|
|
395
306
|
```
|
|
396
307
|
|
|
397
|
-
|
|
398
|
-
- `traceHeaderKey?: string` - Custom trace header name (default: 'unnbound-trace-id')
|
|
399
|
-
- `ignoreTraceRoutes?: string[]` - Routes to ignore in Express middleware
|
|
400
|
-
- `ignoreAxiosTraceRoutes?: string[]` - Routes to ignore in Axios middleware
|
|
401
|
-
|
|
402
|
-
**Note:** `workflowId`, `serviceId`, and `deploymentId` are configured via environment variables (`UNNBOUND_WORKFLOW_ID`, `UNNBOUND_SERVICE_ID`, `UNNBOUND_DEPLOYMENT_ID`). The `UNNBOUND_WORKFLOW_URL` is used for URL construction in webhook endpoints.
|
|
308
|
+
The logger is a Pino instance with additional context automatically included from environment variables and trace context.
|
|
403
309
|
|
|
404
310
|
#### Methods
|
|
405
311
|
|
|
406
|
-
- `
|
|
407
|
-
- `
|
|
408
|
-
- `
|
|
409
|
-
- `
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
312
|
+
- `logger.info(object: {}, message: string): void`
|
|
313
|
+
- `logger.warn(object: {}, message: string): void`
|
|
314
|
+
- `logger.error(object: {}, message: string): void`
|
|
315
|
+
- `logger.debug(object: {}, message: string): void`
|
|
316
|
+
|
|
317
|
+
### traceMiddleware
|
|
318
|
+
|
|
319
|
+
Express middleware for automatic HTTP request/response logging and trace context management.
|
|
320
|
+
|
|
321
|
+
#### Usage
|
|
322
|
+
|
|
323
|
+
```typescript
|
|
324
|
+
import { traceMiddleware } from 'unnbound-logger';
|
|
325
|
+
|
|
326
|
+
app.use(traceMiddleware(options?: HttpOptions));
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
**HttpOptions:**
|
|
330
|
+
|
|
331
|
+
- `traceHeaderKey?: string` - Custom trace header name (default: 'x-unnbound-trace-id')
|
|
332
|
+
- `ignoreTraceRoutes?: string[]` - Routes to ignore in middleware (default: ['/health', '/healthcheck'])
|
|
333
|
+
|
|
334
|
+
### traceAxios
|
|
335
|
+
|
|
336
|
+
Wraps an Axios instance with automatic request/response logging and trace context propagation.
|
|
337
|
+
|
|
338
|
+
#### Usage
|
|
339
|
+
|
|
340
|
+
```typescript
|
|
341
|
+
import { traceAxios } from 'unnbound-logger';
|
|
342
|
+
import axios from 'axios';
|
|
343
|
+
|
|
344
|
+
const client = traceAxios(axios.create(), options?: HttpOptions);
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### startSpan
|
|
348
|
+
|
|
349
|
+
Creates a span for tracking async operations with automatic logging and duration measurement.
|
|
350
|
+
|
|
351
|
+
#### Usage
|
|
352
|
+
|
|
353
|
+
```typescript
|
|
354
|
+
import { startSpan } from 'unnbound-logger';
|
|
355
|
+
|
|
356
|
+
const result = await startSpan<T>(
|
|
357
|
+
spanName: string,
|
|
358
|
+
callback: () => Promise<T>,
|
|
359
|
+
getter?: LogPayloadGetter<T>
|
|
360
|
+
);
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
**Parameters:**
|
|
364
|
+
|
|
365
|
+
- `spanName`: The name of the span for logging
|
|
366
|
+
- `callback`: The async function to execute within the span
|
|
367
|
+
- `getter`: Optional function to generate log payload based on operation result/error
|
|
368
|
+
|
|
369
|
+
### Environment Variables
|
|
370
|
+
|
|
371
|
+
- `UNNBOUND_WORKFLOW_ID` - Workflow identifier (included in all logs)
|
|
372
|
+
- `UNNBOUND_SERVICE_ID` - Service identifier (included in all logs)
|
|
373
|
+
- `UNNBOUND_DEPLOYMENT_ID` - Deployment identifier (included in all logs)
|
|
374
|
+
- `UNNBOUND_WORKFLOW_URL` - Base URL for webhook endpoint logging
|
|
375
|
+
- `ENVIRONMENT` - Environment name (included in all logs)
|
|
376
|
+
- `LOG_LEVEL` - Log level (default: 'info')
|
package/dist/index.js
CHANGED
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
Object.defineProperty(exports, "
|
|
12
|
-
const logger_utils_1 = require("./utils/logger-utils");
|
|
13
|
-
Object.defineProperty(exports, "clearTraceId", { enumerable: true, get: function () { return logger_utils_1.clearTraceId; } });
|
|
3
|
+
exports.traceMiddleware = exports.traceAxios = exports.startSpan = exports.logger = void 0;
|
|
4
|
+
var logger_1 = require("./logger");
|
|
5
|
+
Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
|
|
6
|
+
var span_1 = require("./span");
|
|
7
|
+
Object.defineProperty(exports, "startSpan", { enumerable: true, get: function () { return span_1.startSpan; } });
|
|
8
|
+
var axios_1 = require("./axios");
|
|
9
|
+
Object.defineProperty(exports, "traceAxios", { enumerable: true, get: function () { return axios_1.traceAxios; } });
|
|
10
|
+
var middleware_1 = require("./middleware");
|
|
11
|
+
Object.defineProperty(exports, "traceMiddleware", { enumerable: true, get: function () { return middleware_1.traceMiddleware; } });
|
package/package.json
CHANGED
|
@@ -1,23 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "unnbound-logger-sdk",
|
|
3
|
-
"version": "2.0.9",
|
|
4
3
|
"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.",
|
|
4
|
+
"version": "3.0.0",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
|
-
"scripts": {
|
|
8
|
-
"build": "tsc",
|
|
9
|
-
"test": "npx jest",
|
|
10
|
-
"test:coverage": "npx jest --coverage",
|
|
11
|
-
"test:watch": "npx jest --watch",
|
|
12
|
-
"lint": "eslint src/**/*.ts",
|
|
13
|
-
"lint:fix": "eslint . --ext .ts --fix",
|
|
14
|
-
"format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
|
|
15
|
-
"format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
|
|
16
|
-
"prepublishOnly": "npm run build && npm test",
|
|
17
|
-
"check-coverage": "ts-node scripts/check-coverage.ts",
|
|
18
|
-
"start:example:node-app": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' examples/node-app.ts",
|
|
19
|
-
"start:example:basic-usage": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' examples/basic-usage.ts"
|
|
20
|
-
},
|
|
21
7
|
"keywords": [
|
|
22
8
|
"logging",
|
|
23
9
|
"typescript",
|
|
@@ -33,11 +19,11 @@
|
|
|
33
19
|
"license": "MIT",
|
|
34
20
|
"repository": {
|
|
35
21
|
"type": "git",
|
|
36
|
-
"url": "https://github.com/unnbound
|
|
22
|
+
"url": "https://github.com/unnbounddev/unnbound-sdks.git"
|
|
37
23
|
},
|
|
38
|
-
"homepage": "https://github.com/unnbound
|
|
24
|
+
"homepage": "https://github.com/unnbounddev/unnbound-sdks#readme",
|
|
39
25
|
"bugs": {
|
|
40
|
-
"url": "https://github.com/unnbound/
|
|
26
|
+
"url": "https://github.com/unnbounddev/unnbound-sdks/issues"
|
|
41
27
|
},
|
|
42
28
|
"dependencies": {
|
|
43
29
|
"axios": "^1.0.0",
|
|
@@ -49,19 +35,7 @@
|
|
|
49
35
|
"@types/express": "^4.17.21",
|
|
50
36
|
"@types/jest": "^29.5.12",
|
|
51
37
|
"@types/node": "^20.11.24",
|
|
52
|
-
"@types/uuid": "^9.0.8"
|
|
53
|
-
"@typescript-eslint/eslint-plugin": "^7.1.0",
|
|
54
|
-
"@typescript-eslint/parser": "^7.1.0",
|
|
55
|
-
"cors": "^2.8.5",
|
|
56
|
-
"dotenv": "^16.5.0",
|
|
57
|
-
"eslint": "^8.57.0",
|
|
58
|
-
"eslint-config-prettier": "^10.1.5",
|
|
59
|
-
"jest": "^29.7.0",
|
|
60
|
-
"nodemon": "^3.1.10",
|
|
61
|
-
"prettier": "^3.2.5",
|
|
62
|
-
"ts-jest": "^29.1.2",
|
|
63
|
-
"ts-node": "^10.9.2",
|
|
64
|
-
"typescript": "^5.3.3"
|
|
38
|
+
"@types/uuid": "^9.0.8"
|
|
65
39
|
},
|
|
66
40
|
"peerDependencies": {
|
|
67
41
|
"axios": "^1.0.0",
|
|
@@ -77,14 +51,23 @@
|
|
|
77
51
|
},
|
|
78
52
|
"files": [
|
|
79
53
|
"dist/src/**/*",
|
|
80
|
-
"dist/index.*",
|
|
81
|
-
"dist/types.*",
|
|
82
|
-
"dist/unnbound-logger.*",
|
|
83
|
-
"dist/utils/**/*",
|
|
84
54
|
"README.md",
|
|
85
55
|
"LICENSE"
|
|
86
56
|
],
|
|
87
57
|
"engines": {
|
|
88
|
-
"node": ">=
|
|
58
|
+
"node": ">=22.0.0"
|
|
59
|
+
},
|
|
60
|
+
"sideEffects": false,
|
|
61
|
+
"scripts": {
|
|
62
|
+
"build": "tsc",
|
|
63
|
+
"test": "jest",
|
|
64
|
+
"test:coverage": "jest --coverage",
|
|
65
|
+
"test:watch": "jest --watch",
|
|
66
|
+
"lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
|
|
67
|
+
"lint:fix": "pnpm lint --fix",
|
|
68
|
+
"format": "prettier --write .",
|
|
69
|
+
"format:check": "prettier --check .",
|
|
70
|
+
"start:example:node-app": "npx tsx --watch examples/node-app.ts",
|
|
71
|
+
"start:example:basic-usage": "npx tsx --watch examples/basic-usage.ts"
|
|
89
72
|
}
|
|
90
|
-
}
|
|
73
|
+
}
|
package/dist/index.d.ts
DELETED
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* unnbound-logger
|
|
3
|
-
*
|
|
4
|
-
* A structured logging library built on Pino with TypeScript support.
|
|
5
|
-
* Provides consistent, well-typed logging across different operational contexts.
|
|
6
|
-
*/
|
|
7
|
-
import { UnnboundLogger } from './unnbound-logger';
|
|
8
|
-
import { LogLevel, LogType, HttpMethod, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, LogTransaction, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog, SerializableError } from './types';
|
|
9
|
-
import { clearTraceId } from './utils/logger-utils';
|
|
10
|
-
export { UnnboundLogger, LogLevel, LogType, HttpMethod, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, LogTransaction, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog, SerializableError, clearTraceId, };
|