https://github.com/mccann-hub/express-log-smith
Skillfully forges logs for Express.js applications
https://github.com/mccann-hub/express-log-smith
express-middleware expressjs logger-middleware logging morgan morgan-middleware typescript typescript-library
Last synced: 5 months ago
JSON representation
Skillfully forges logs for Express.js applications
- Host: GitHub
- URL: https://github.com/mccann-hub/express-log-smith
- Owner: McCann-Hub
- Created: 2024-11-27T16:59:15.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-12-06T02:04:13.000Z (over 1 year ago)
- Last Synced: 2025-10-24T18:23:17.807Z (8 months ago)
- Topics: express-middleware, expressjs, logger-middleware, logging, morgan, morgan-middleware, typescript, typescript-library
- Language: TypeScript
- Homepage:
- Size: 229 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Express Log Smith
Express Log Smith is a middleware library for Express.js designed to enhance logging and request tracing.
It simplifies request/response observability by integrating structured logging and unique identifiers like
`correlationId`, `traceId`, and `spanId` into your application.
## Features
- **Request ID Middleware**: Automatically assigns correlationId, traceId, and spanId to each request.
- **Contextual Logger**: Attaches a logger with enriched metadata to the request object for consistent, contextual logging.
- **Request Logger**: Logs structured details of incoming requests and outgoing responses.
- **Customizable**: Configure ID generation, log formats, and skip conditions as needed.
- **Plug-and-Play**: Works seamlessly with any logger implementing the provided ILogger interface.
## Installation
Install ExpressLogSmith via npm:
```bash
npm install @mccann-hub/express-log-smith
```
## Basic Usage
A simple example integrating the middlewares into an Express.js application:
```typescript
import express from "express";
import {
dexter,
requestId,
requestLogger,
} from "@mccann-hub/express-log-smith";
// Import your logger (must implement ILogger)
import myLogger from "./myLogger";
const app = express();
// Add request ID middleware to generate unique IDs
app.use(requestId());
// Add contextual logger middleware
app.use(dexter(myLogger));
// Add request logging middleware
app.use(requestLogger(myLogger));
// Define routes
app.get("/", (req, res) => {
req.logger.info("Processing request", { custom: "metadata" });
res.send("Hello, world!");
});
app.listen(3000, () => {
console.log("Server is running on port 3000");
});
```
## Exported Middlewares
### `requestId(options?: RequestIdOptions)`
Adds `correlationId`, `traceId`, and `spanId` to each request.
These IDs help trace logs across distributed systems.
#### Options
- **correlation (optional)**: Configuration for the correlation ID.
- **headerName**: The header name for the correlation ID (default: X-Correlation-Id).
- **generator**: A custom ID generation function.
- **setHeader**: Whether to include the correlation ID in the response headers (default: true).
- **trace (optional)**: Configuration for the trace ID.
- Same properties as correlation.
- **span (optional)**: Configuration for the span ID.
- **headerName**: The header name for the span ID (default: X-svc2svc-Id).
- **setHeader**: Whether to include the span ID in the response headers (default: true).
#### Example
```typescript
app.use(
requestId({
correlation: { headerName: "X-My-Correlation-Id" },
trace: { generator: () => `trace-${Date.now()}` },
}),
);
```
### `dexter(logger: ILogger)`
Logs structured details of incoming requests and outgoing responses.
The default format includes:
- correlation_id
- trace_id
- span_id
- HTTP method, content type, user agent, URI path
- Response time and status
#### Customization
You can customize logging behavior by providing a skip function:
```typescript
app.use(
dexter(myLogger, {
skip: (req) => req.url === "/health",
}),
);
```
### `requestLogger(logger: ILogger)`
Attaches a logger to the request object.
The logger includes metadata from the request, such as `correlationId`, `traceId`, and `spanId`.
#### Requirements
The provided logger must implement the ILogger interface.
#### Example
```typescript
app.use(requestLogger(myLogger));
app.get("/test", (req, res) => {
req.logger.info("This is a test log");
res.send("Logged successfully!");
});
```