Loki Logger SDK

A simple TypeScript wrapper for pushing logs to Grafana Loki with dynamic schema generation and strong type safety.

Setup

1. Install dependencies:

yarn install

2. Set up environment variables for Loki:

export LOKI_USERNAME="your-username"
export LOKI_PASSWORD="your-password"

Schema Management

You can define schemas in two ways:

• Enum style (values): provide a list of allowed strings.
• Full schema style (schema): provide an OpenAPI 3.0 schema object for full flexibility (string, number, object, arrays, etc.).

Both styles are supported simultaneously. Example schemas.json:

[
  {
    "key": "Environment",
    "values": ["Development", "Production"]
  },
  {
    "key": "Service",
    "values": ["alert", "auth", "vehicle", "maps"]
  },
  {
    "key": "UserId",
    "schema": { "type": "string", "format": "uuid", "description": "User identifier" }
  },
  {
    "key": "Metadata",
    "schema": {
      "type": "object",
      "description": "Arbitrary metadata object",
      "additionalProperties": { "type": "string" }
    }
  }
]

Generate SDK

If you're developing the logger:

yarn generate

If you're using the package from npm:

# Install globally
npm install -g @altmobility/loki-logger

# Create schemas.json in your project
echo '[
    {
        "key": "JobType",
        "values": ["test-job", "prod-job"]
    }
]' > schemas.json

# Generate SDK
npx loki-logger-generate

This command will:

• Read schemas (enums or full schemas)
• Generate openapi.json spec
• Generate TypeScript models, services, and type definitions
• Build the project

Usage

Basic Usage

import { LogsService } from '@altmobility/loki-logger';
import { JobType, Environment, Service } from '@altmobility/loki-logger';

const logger = new LogsService({
    jobType: JobType.TEST_JOB,
    environment: Environment.DEVELOPMENT,
    service: Service.AUTH
});

await logger.info('Hello World');
await logger.warn('Warning message');
await logger.error('Error message');

Type-Safe Configuration

The logger provides full IntelliSense support for configuration. Use Ctrl + Space (or Cmd + Space on Mac) to see available options:

const logger = new LogsService({
    jobType: JobType.    // Press Ctrl + Space to see available job types
    environment: Environment.    // Press Ctrl + Space to see available environments
    service: Service.    // Press Ctrl + Space to see available services
});

File vs HTTP Logging

The logger supports both file and HTTP (Loki) logging:

// For file logging
process.env.LOGS_HTTP_PROCESSING = 'false';

// For Loki HTTP logging
process.env.LOGS_HTTP_PROCESSING = 'true';

Core Types

The logger includes several core types:

• LogLevel: 'info' | 'warn' | 'error'
• JobType: Custom job types from schemas.json
• Environment: Custom environments from schemas.json
• Service: Custom services from schemas.json
• Module: Custom modules from schemas.json

Development Workflow

1. Update schemas.json with new enum values
2. Run yarn generate to update the SDK
3. TypeScript types and models are automatically updated
4. IntelliSense will show the new options

Environment Variables

# Required for Loki HTTP logging
export LOKI_USERNAME="your-username"
export LOKI_PASSWORD="your-password"

# Optional
export NODE_ENV="development"  # Enables console logging
export LOGS_HTTP_PROCESSING="true"  # Enable HTTP logging (default)

File Logging Configuration

When using file logging (LOGS_HTTP_PROCESSING=false):

• Logs are written to combined.log
• Maximum file size: 5MB
• Maximum files: 50
• Files are automatically rotated and archived

Example with All Features

import { LogsService } from '@altmobility/loki-logger';
import { JobType, Environment, Service, Module } from '@altmobility/loki-logger';

// Full type-safe configuration
const logger = new LogsService({
    jobType: JobType.TEST_JOB,
    environment: Environment.DEVELOPMENT,
    service: Service.AUTH,
    module: Module.EVENTS
});

// Async logging with different levels
await logger.info('Processing started');
await logger.warn('Resource usage high');
await logger.error('Process failed');

// Logs will include all configured metadata
// Example output:
// {
//   "level": "info",
//   "message": "Processing started",
//   "jobType": "test-job",
//   "environment": "development",
//   "service": "auth",
//   "module": "events",
//   "timestamp": "2025-09-30T12:00:00.000Z"
// }