Aluminumio Log Stream

A command wrapper that executes programs while streaming their output to a remote Busl server. Designed for Platform-as-a-Service (PaaS) deployments to capture build, release, and application logs.

Overview

log-stream is a lightweight wrapper around the busltee library that:

• Executes any command while capturing stdout/stderr
• Streams output to a configured Busl server endpoint
• Preserves the original command's exit code
• Handles environment-based configuration

Installation

git clone https://github.com/aluminumio/log-stream
cd log-stream
go build -o log-stream ./cmd/log-stream

Usage

Basic usage:

log-stream -- <command> [arguments...]

Examples

Stream build output:

export ALUMINUMIO_STREAM_URL_BUILD=http://logs.example.com/streams/build-123
log-stream -- make build

Stream application logs:

export ALUMINUMIO_STREAM_URL_APP=http://logs.example.com/streams/app-456
log-stream -- ./start-server.sh

Stream with verbose logging:

export ALUMINUMIO_VERBOSE=true
export ALUMINUMIO_STREAM_URL_DEBUG=http://logs.example.com/streams/debug-789
log-stream -- python debug_script.py

Configuration

Environment Variables

Variable	Description	Default
ALUMINUMIO_STREAM_URL_*	URL to stream logs to (any suffix after _URL_ works)	None (streaming disabled)
ALUMINUMIO_VERBOSE	Enable verbose logging	false
ALUMINUMIO_TIMEOUT	Command timeout in seconds	1800 (30 minutes)
ALUMINUMIO_RETRY	Number of retries for connection failures	5
DEBUG_HTTP	Enable HTTP debug logging	false

Stream URL Format

The stream URL should point to a Busl server stream endpoint:

http://busl-server:5001/streams/{stream-id}
https://logs.yourpaas.com/streams/{stream-id}

Integration with PaaS

In Buildpacks

#!/bin/bash
# buildpack/bin/compile

BUILD_ID=$(uuidgen)
export ALUMINUMIO_STREAM_URL_BUILD="$BUSL_SERVER/streams/builds/$APP_ID/$BUILD_ID"

log-stream -- npm install
log-stream -- npm run build

In Procfiles

web: log-stream -- bundle exec puma -C config/puma.rb
worker: log-stream -- bundle exec sidekiq
release: log-stream -- bundle exec rake db:migrate

In Docker Containers

FROM alpine:latest
COPY log-stream /usr/local/bin/
ENV ALUMINUMIO_STREAM_URL_APP=http://busl:5001/streams/app
CMD ["log-stream", "--", "/app/start.sh"]

Features

• Zero Configuration: Works without stream URL (just executes command)
• Exit Code Preservation: Returns the same exit code as the wrapped command
• Signal Forwarding: Forwards signals to the child process
• Automatic Retry: Handles temporary network failures
• Concurrent Streaming: Streams while command is running (no buffering)

Building for Different Platforms

# Linux
GOOS=linux GOARCH=amd64 go build -o log-stream-linux ./cmd/log-stream

# macOS
GOOS=darwin GOARCH=amd64 go build -o log-stream-darwin ./cmd/log-stream

# Windows
GOOS=windows GOARCH=amd64 go build -o log-stream.exe ./cmd/log-stream

Comparison with Heroku's log-stream

This implementation is compatible with the original Heroku log-stream but uses:

• ALUMINUMIO_* environment variables instead of HEROKU_*
• Open source Busl server instead of proprietary infrastructure
• Same command-line interface for drop-in replacement

License

MIT License - see LICENSE file for details