@thalorlabs/observability

A TypeScript observability package for ThalorLabs projects, providing shared types, schemas, and utilities for monitoring, logging, and tracing.

Installation

npm install @thalorlabs/observability

Usage

Import All Types

import {
  ServerLogCore,
  ServerLogWithId,
  ServerLogPartial,
  ServerLogSchema,
} from '@thalorlabs/observability';

Import Individual Types

import { ServerLogCore } from '@thalorlabs/observability/types/ServerLog';
import { ServerLogSchema } from '@thalorlabs/observability/serverLogs';

Available Types

Server Log Types

| Type | Description | Usage | | ------------------ | --------------------------------------------- | ------------------------------------ | | ServerLogCore | Core server log data without MongoDB metadata | ServerLogCore.parse(logData) | | ServerLogWithId | Complete server log with MongoDB metadata | ServerLogWithId.parse(fullLogData) | | ServerLogPartial | Partial server log for update operations | ServerLogPartial.parse(updateData) |

Mongoose Schemas

| Schema | Description | Usage | | ----------------- | ----------------------------------- | ----------------------------- | | ServerLogSchema | Mongoose schema for MongoDB storage | new Schema(ServerLogSchema) |

Examples

Basic Server Log Creation

import { ServerLogCore } from '@thalorlabs/observability';

const logData = {
  requestId: 'req-123',
  correlationId: 'corr-456',
  httpMethod: 'GET',
  endpoint: '/api/users',
  queryParams: '?page=1&limit=10',
  ipAddress: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  responseStatus: 200,
  isSuccess: true,
  auditTimer: 150,
  service: 'user-service',
  environment: 'production',
  version: '1.2.3',
  timestamp: new Date(),
};

const serverLog = ServerLogCore.parse(logData);

Error Logging

import { ServerLogCore } from '@thalorlabs/observability';

const errorLog = {
  requestId: 'req-789',
  httpMethod: 'POST',
  endpoint: '/api/orders',
  responseStatus: 500,
  isSuccess: false,
  errorCode: 'DATABASE_ERROR',
  errorMessage: 'Connection timeout',
  errorStack: 'Error: Connection timeout\n    at Database.connect...',
  service: 'order-service',
  environment: 'production',
  timestamp: new Date(),
};

const errorServerLog = ServerLogCore.parse(errorLog);

MongoDB Integration

import { ServerLogWithId, ServerLogSchema } from '@thalorlabs/observability';
import { ObjectId } from 'bson';
import mongoose from 'mongoose';

// Using the Mongoose schema
const ServerLogModel = mongoose.model('ServerLog', ServerLogSchema);

// Creating a complete log with MongoDB metadata
const fullLog = {
  _id: new ObjectId(),
  requestId: 'req-123',
  httpMethod: 'GET',
  endpoint: '/api/users',
  responseStatus: 200,
  isSuccess: true,
  createdAt: new Date(),
  updatedAt: new Date(),
};

const validatedLog = ServerLogWithId.parse(fullLog);

// Save to MongoDB
const savedLog = await ServerLogModel.create(validatedLog);

Partial Updates

import { ServerLogPartial } from '@thalorlabs/observability';

// Update only specific fields
const updateData = {
  responseStatus: 200,
  isSuccess: true,
  auditTimer: 150,
  responseBody: '{"users": []}',
};

const partialLog = ServerLogPartial.parse(updateData);

// Use with MongoDB update operations
await ServerLogModel.updateOne({ requestId: 'req-123' }, { $set: partialLog });

Server Log Fields

Request Information

• requestId - Unique request identifier
• correlationId - Correlation ID for distributed tracing
• httpMethod - HTTP method (GET, POST, etc.)
• endpoint - API endpoint path
• queryParams - Query parameters as string
• requestBody - Request body as string
• requestHeaders - Request headers as string
• userAgent - Client user agent
• ipAddress - Client IP address

Response Information

• responseStatus - HTTP response status code
• responseBody - Response body as string
• responseHeaders - Response headers as string

Performance Metrics

• auditTimer - Request processing time in milliseconds
• requestSize - Request size in bytes
• responseSize - Response size in bytes

Billing Context

• service - Service name for billing attribution

Error Information

• errorCode - Error code identifier
• errorMessage - Human-readable error message
• errorStack - Error stack trace
• isSuccess - Boolean indicating request success

Metadata

• environment - Deployment environment (dev, staging, prod)
• version - Service version
• timestamp - Log timestamp

Project Structure

src/
├── index.ts                    # Main exports
├── types/                      # Type definitions
│   └── ServerLog.ts           # Server log types and schemas
└── serverLogs/                # Mongoose schemas
    ├── index.ts               # Schema exports
    └── serverLogSchema.ts     # Mongoose ServerLog schema

TypeScript Support

This package includes full TypeScript support with:

• Complete type definitions
• Zod schema validation
• IntelliSense support
• Compile-time type checking
• Mongoose integration

Observability Best Practices

Structured Logging

Use consistent field names and types across all services for better log aggregation and analysis.

Performance Tracking

Always include auditTimer to track request processing time and identify performance bottlenecks.

Error Context

Include comprehensive error information (errorCode, errorMessage, errorStack) for effective debugging.

Correlation IDs

Use correlationId to trace requests across multiple services in distributed systems.

Indexing

The Mongoose schema includes optimized indexes for common query patterns:

• endpoint + createdAt
• responseStatus + createdAt
• isSuccess + createdAt

Development

Building

npm run build

Type Checking

npx tsc --noEmit

License

ISC