@alkaline-git/git-log

@alkaline/git-log

Git-aware logging SDK for developers. Correlate logs with Git commits and deploys.

Overview

@alkaline/git-log is a powerful logging library that integrates with Git to provide context-aware logging capabilities. It supports multiple transport layers and can be easily configured to match your logging needs.

Features

• Git-aware logging
• Multiple transport options (SQL, HTTP, SQLite)
• Configurable severity levels
• TypeScript support
• Async logging capabilities

Installation

    npm install @alkaline-git/git-log

Basic Usage

Configuration

The logger can be configured with various options:

interface LoggerOptions { transports: AlkalineTransport[]; level?: string; format?: Format; defaultMeta?: any; }
const logger = createLogger({ level: 'info', defaultMeta: { service: 'user-service' }, 
    transports: [ // Add your transports here ] 
}

Transports

Console Transport

The Console transport is the simplest transport, outputting logs directly to the console.

import { createLogger, ConsoleTransport } from '@alkaline/git-log';
// Configure Console Transport
const consoleTransport = new ConsoleTransport(['info', 'error']);
// Create logger with Console transport
const logger = createLogger({ transports: [consoleTransport] });
// Usage
logger.info('Operation completed', { details: 'Process finished successfully' });

PostgreSQL Transport

The PostgreSQL transport enables logging directly to a PostgreSQL database.

import { createLogger, PostgresTransport } from '@alkaline/git-log';
// Configure PostgreSQL Transport
const postgresTransport = new PostgresTransport({
    host: 'localhost',
    port: 5432,
    database: 'logs_db',
    user: 'postgres_user', 
    password: 'postgres_password',
    query: (info) => ({
        stmt: 'INSERT INTO logs(level, message, timestamp, metadata) VALUES(1,2, 3,4)',
        params: [ info.level, info.message, new Date(), JSON.stringify(info.metadata) ] 
    }) 
}, ['info', 'error']);
// Create logger with PostgreSQL transport
const logger = createLogger({ transports: [postgresTransport] });
// Usage 
logger.info('Database operation completed', { operation: 'data_sync' });

SQL Transport

The SQL transport allows you to store logs directly in SQL databases like MySQL.

import { createLogger, SqlTransport } from '@alkaline/git-log';
// Configure SQL Transport
const sqlTransport = new SqlTransport({ 
    host: 'localhost', 
    user: 'database_user', 
    password: 'database_password', 
    database: 'logs_db', 
    uery: (info) => ({ 
        stmt: 'INSERT INTO logs (level, message, timestamp) VALUES (?, ?, ?)', 
        params: [info.level, info.message, new Date()]
    })
}, ['info', 'error']);
// Create logger with SQL transport
const logger = createLogger({ transports: [sqlTransport] });
// Usage 
logger.info('Database operation completed');

HTTP Transport

The HTTP transport enables sending logs to remote endpoints via HTTP/HTTPS.

import { createLogger, HttpTransport, HttpMethod } from '@alkaline/git-log';
// Configure HTTP Transport 
const httpTransport = new HttpTransport({ 
    url: '[https://logging-api.example.com/logs](https://logging-api.example.com/logs)',
    method: HttpMethod.POST, 
    headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-token' }, 
    buildBody: (info) => JSON.stringify({ 
        level: info.level, 
        message: info.message, 
        timestamp: new Date(), 
        metadata: info.metadata 
    }) 
}, ['info', 'error']);
// Create logger with HTTP transport
const logger = createLogger({ transports: [httpTransport] });
// Usage
logger.info('API request completed', { requestId: '123' });

SQLite Transport

The SQLite transport provides local database logging capabilities.

import { createLogger, LiteTransport } from '@alkaline/git-log';

// Configure SQLite Transport
const liteTransport = new LiteTransport({
  dbName: 'application_logs.db',
  query: (info) => ({
    stmt: 'INSERT INTO logs (level, message, timestamp, metadata) VALUES (?, ?, ?, ?)',
    params: [
      info.level,
      info.message,
      new Date().toISOString(),
      JSON.stringify(info.metadata)
    ]
  })
}, ['info', 'error']);

// Create logger with SQLite transport
const logger = createLogger({
  transports: [liteTransport]
});

// Usage
logger.info('Local operation completed', { operationId: 'op123' });

Using Multiple Transports

You can combine multiple transports in a single logger instance:

const logger = createLogger({
  transports: [
    consoleTransport,  // For local debugging
    postgresTransport, // For persistent storage
    httpTransport      // For remote logging service
  ]
});

// Logs will be sent to all configured transports
logger.info('Important operation completed');

Error Handling

All transports handle errors gracefully and include built-in error logging:

logger.error('Operation failed', {
  error: new Error('Database connection failed'),
  context: {
    operation: 'database_sync',
    timestamp: new Date()
  }
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

The README now includes all five transport types:
1. Console Transport (for simple console output)
2. PostgreSQL Transport (for PostgreSQL databases)
3. SQL Transport (for MySQL and other SQL databases)
4. HTTP Transport (for remote logging endpoints)
5. SQLite Transport (for local SQLite databases)

Each transport section includes configuration examples and usage patterns. The multiple transports example has also been updated to show a more realistic combination of different transport types.