Logfabric

Drop a Vector-powered unified log fabric into any project in ≤5 min.

🚀 Quick Start

# Install globally
npm install -g logfabric

# Initialize in your project
cd your-project
logfabric init

# Start the logging stack
logfabric up

# Run ANY command with automatic log capture
logfabric run npm run dev

# Watch logs in real-time
make logs

Zero Code Changes Required!

Just prefix any command with logfabric run:

# Instead of:
npm run dev

# Use:
logfabric run npm run dev

# Works with any command:
logfabric run python app.py
logfabric run cargo run
logfabric run java -jar app.jar

📖 Table of Contents

• Features
• Installation
• Getting Started
• Usage
• Integration Options
• Commands
• Configuration
• Examples
• Architecture
• Troubleshooting
• Contributing
• License

✨ Features

• 🚀 5-minute setup - Get unified logging running quickly
• 🎯 Zero code changes - Capture logs from any command with logfabric run
• 📊 Multiple drivers - File-based or Loki with Grafana UI
• 🔧 Smart defaults - Works out of the box with sensible configuration
• 🌐 Multi-platform - Supports Web, Node.js, iOS, and any CLI tool
• 🐳 Docker-powered - Reliable containerized Vector and Loki services
• 📝 Developer friendly - Simple Makefile targets and excellent DX
• 🔍 Powerful filtering - Filter logs by level, source, or custom fields

📦 Installation

Prerequisites

• Node.js ≥ 18.17
• Docker ≥ 24.0 (for container mode)
• npm or yarn

Install via npm (Recommended)

npm install -g logfabric

Install via yarn

yarn global add logfabric

Install from source

git clone https://github.com/jhurray/logfabric.git
cd logfabric
npm install
npm run build
npm link

🏁 Getting Started

1. Initialize Logfabric in Your Project

cd your-project
logfabric init

This creates:

• logfabric.toml - Main configuration file
• devtools/logfabric/ - Vector configuration
• Updates your Makefile with helpful targets
• Updates .gitignore to exclude log files
• Adds integration examples to your README

2. Start the Logging Infrastructure

logfabric up

This starts:

• Vector - High-performance observability data pipeline
• Loki (optional) - Log aggregation system
• Grafana (optional) - Visualization UI

3. Run Your Application with Logging

# Any command automatically logs to logfabric
logfabric run npm run dev
logfabric run python manage.py runserver
logfabric run cargo run --release

4. View Your Logs

# Tail logs in real-time
make logs

# Or use the CLI directly
logfabric tail -f

# Filter by log level
logfabric tail --level error

# View last 50 lines
logfabric tail -n 50

💻 Usage

The Magic of logfabric run

The run command captures ALL output from any process:

# Development servers
logfabric run npm run dev
logfabric run yarn start
logfabric run pnpm dev

# Testing
logfabric run npm test
logfabric run jest --watch
logfabric run pytest

# Any language or tool
logfabric run ruby app.rb
logfabric run go run main.go
logfabric run docker-compose up

Options

# Name your log source
logfabric run --name "api-server" npm start

# Parse JSON logs automatically
logfabric run --json npm run dev

# Suppress stdout (only send to logfabric)
logfabric run --no-stdout ./noisy-script.sh

🔌 Integration Options

Option 1: Zero-Config with logfabric run

No code changes needed - just prefix your commands:

// package.json
{
  "scripts": {
    "dev": "next dev",
    "dev:logged": "logfabric run npm run dev"
  }
}

Option 2: Environment Variables

# .env
export LOGFABRIC_ENDPOINT="http://localhost:8080"
export LOGFABRIC_TOKEN="dev-your-token"

Option 3: SDK Integration

JavaScript/TypeScript (Browser)

npm install @vectordotdev/browser

import { browserLogger } from '@vectordotdev/browser';

browserLogger({
  endpoint: "/_log",              // Rewrite to localhost:8080
  token: "dev-your-token"
});

// All console methods are now captured
console.log('User clicked button', { id: 'submit' });
console.error('Payment failed', { error: 'Card declined' });

Node.js with Pino

import pino from 'pino';

const logger = process.env.LOGFABRIC_ENDPOINT
  ? pino({
      transport: {
        target: '@vectordotdev/pino',
        options: {
          endpoint: process.env.LOGFABRIC_ENDPOINT,
          token: process.env.LOGFABRIC_TOKEN
        }
      }
    })
  : pino();

export default logger;

iOS (Swift)

import LogFabric

let logger = LogFabric(
  endpoint: URL(string: "http://localhost:8080")!,
  token: "dev-your-token"
)

logger.info("User logged in", data: ["userId": 123])

Option 4: Console Interceptor

Add to your app's entry point:

// Automatically created at devtools/logfabric/console-interceptor.js
require('./devtools/logfabric/console-interceptor');

// Now all console.log/error/warn are captured
console.log('This goes to both console AND logfabric!');

📋 Commands

logfabric init

Initialize logfabric in your project.

logfabric init [options]

Options:
  --driver <driver>  Log driver: "file" or "loki" (default: "file")
  --port <port>      HTTP ingest port (default: "8080")

logfabric up

Start Vector and optional Loki services.

logfabric up [options]

Options:
  --detach     Run services in background (default: true)
  --no-ui      Skip Grafana UI for Loki driver
  --native     Use native Vector binary (coming soon)

logfabric run

Run any command with automatic log capture.

logfabric run <command...> [options]

Options:
  --name <name>    Override source name for logs
  --no-stdout      Don't print to stdout
  --json           Parse JSON logs automatically

Examples:
  logfabric run npm start
  logfabric run --name "worker" node worker.js
  logfabric run --json npm run dev

logfabric status

Check the health of running services.

logfabric status

Output:
  ✓ Vector HTTP: healthy
  ✓ Loki API: healthy
  ✓ Grafana UI: healthy

logfabric tail

Tail the unified log output.

logfabric tail [options]

Options:
  -n, --lines <n>    Number of lines to show (default: 20)
  -f, --follow       Follow log output
  --level <level>    Filter by log level

Examples:
  logfabric tail -f
  logfabric tail -n 100 --level error

⚙️ Configuration

Configuration is stored in logfabric.toml:

[project]
  name   = "my-project"
  token  = "dev-f47ac10b58cc"
  driver = "file"      # or "loki"

[ports]
  http  = 8080         # Vector HTTP ingest
  ui    = 5051         # Grafana UI (if driver=loki)

Drivers

File Driver (Default)

• Logs written to logs/combined.log
• Automatic rotation at 50MB
• No additional services needed

Loki Driver

• Logs stored in Loki database
• Grafana UI for querying and visualization
• Better for production/team environments

📚 Examples

Next.js Application

// package.json
{
  "scripts": {
    "dev": "next dev",
    "dev:logged": "logfabric run npm run dev",
    "build": "next build",
    "build:logged": "logfabric run npm run build"
  }
}

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/_log',
        destination: 'http://localhost:8080',
      },
    ];
  },
};

Express Server

// server.js
const express = require('express');
const app = express();

// All console.log statements are automatically captured
console.log('Server starting...');

app.get('/', (req, res) => {
  console.log(`Request: ${req.method} ${req.url}`);
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Run with:

logfabric run node server.js

Python Flask App

# app.py
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    print(f"Request received at {datetime.now()}")
    return "Hello World!"

if __name__ == '__main__':
    app.run(debug=True)

Run with:

logfabric run python app.py

🏗️ Architecture

Your App → logfabric run → Vector HTTP → File/Loki → Viewing (tail/Grafana)
           ↓
        stdout/stderr
           ↓
        Terminal (preserved)

Components

1. logfabric CLI - Manages configuration and services
2. Vector - High-performance data pipeline
3. Loki (optional) - Log aggregation and storage
4. Grafana (optional) - Web UI for log exploration

Log Format

{
  "ts": "2025-06-30T02:33:37.761Z",
  "level": "info",
  "src": "my-app",
  "msg": "Server started",
  "data": {
    "port": 3000,
    "env": "development"
  },
  "seq": 1751250817762
}

🔧 Troubleshooting

Docker not found

# Install Docker from
https://docs.docker.com/get-docker/

Port already in use

# Change port in logfabric.toml
logfabric init --port 8081

Vector unhealthy

# Check Vector logs
docker compose -f docker-compose.logfabric.yml logs vector

# Restart services
make log-down
make log-up

Logs not appearing

1. Check services are running: logfabric status
2. Verify endpoint: curl http://localhost:8080/health
3. Check Docker logs: docker compose -f docker-compose.logfabric.yml logs

🤝 Contributing

We love contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

# Clone the repo
git clone https://github.com/jhurray/logfabric.git
cd logfabric

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Test locally
npm link
cd /tmp/test-project
logfabric init

Development Workflow

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Make your changes
5. Run tests (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Areas for Contribution

• 🐛 Bug fixes
• ✨ New features (S3 sink, ClickHouse driver, etc.)
• 📚 Documentation improvements
• 🧪 More tests
• 🌍 Internationalization
• 🎨 UI improvements for Grafana dashboards
• 🔌 New SDK integrations

Running Tests

# Unit tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

Project Structure

logfabric/
├── src/
│   ├── commands/       # CLI commands
│   ├── utils/          # Utility functions
│   ├── templates/      # Config templates
│   └── types/          # TypeScript types
├── example-app/        # Example application
├── docs/               # Documentation
└── tests/              # Test files

🚧 Not Yet Supported

While logfabric works great on macOS and Linux, there are some features and platforms we don't yet support:

Platforms

• Windows - Not tested or supported (and honestly, not a priority)
• FreeBSD/OpenBSD - May work but untested
• Alpine Linux - Requires additional testing with musl libc

Features Not Yet Implemented

• Native binary mode - Currently requires Docker; native Vector binary support planned
• Kubernetes sidecar - Direct K8s integration without DaemonSet
• Cloud provider integrations:
  • AWS CloudWatch Logs sink
  • Google Cloud Logging sink
  • Azure Monitor Logs sink
• Additional sinks:
  • Elasticsearch/OpenSearch
  • ClickHouse
  • S3/GCS/Azure Blob Storage
  • Kafka/Pulsar
  • Splunk
• Advanced features:
  • Log sampling and rate limiting
  • Automatic secret/PII redaction
  • Log enrichment with GeoIP
  • Custom Vector transforms via CLI
  • Multi-tenant log routing
• Native mobile SDKs:
  • Swift SDK for iOS/macOS
  • Kotlin SDK for Android
  • React Native integration
  • Flutter integration
• Other language examples:
  • PHP/Laravel
  • C#/.NET
  • Elixir/Phoenix
  • Scala/Akka

Coming Soon

• Browser source maps - Unminify JavaScript errors
• Webhook alerts - Send alerts to Slack/Discord/Teams
• Log replay - Replay logs for debugging
• Session recording - Correlate logs with user sessions
• Distributed tracing - OpenTelemetry integration

Want to help implement any of these? Check out our Contributing Guide!

📝 License

MIT © jhurray

🙏 Acknowledgments

• Vector - High-performance observability data pipeline
• Grafana Loki - Log aggregation system
• Commander.js - Node.js command-line interfaces