tessl/npm-bunyan

A JSON logging library for Node.js services with structured logging and CLI tools

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Tools

Name: tessl/npm-bunyan
Author: tessl

Command-line utility for viewing, filtering, and formatting bunyan JSON log files with human-readable output, powerful filtering capabilities, and multiple display formats.

Capabilities

Basic Usage

View and format bunyan log files from the command line.

# Basic log viewing
bunyan [OPTIONS] [FILE ...]

# Read from stdin
cat app.log | bunyan

# Read from multiple files
bunyan app.log error.log

# Real-time log following
tail -f app.log | bunyan

Output Formats

Control the display format of log output for different use cases.

# Output format options
bunyan -o FORMAT [FILE ...]
bunyan --output FORMAT [FILE ...]

# Available formats:
# long      - Default detailed format (default)
# short     - Compact single-line format  
# simple    - Minimal format with just level, name, and message
# json      - Raw JSON output with 2-space indent
# json-N    - JSON output with N-space indent (e.g. json-4)
# bunyan    - 0-indented JSON, bunyan's native format
# inspect   - Node.js util.inspect output format

# Shortcuts:
bunyan -j [FILE ...]     # Shortcut for -o json
bunyan -0 [FILE ...]     # Shortcut for -o bunyan

Level Filtering

Filter log records by minimum log level to focus on important messages.

# Filter by minimum level
bunyan -l LEVEL [FILE ...]
bunyan --level LEVEL [FILE ...]

# Level names (case insensitive):
# trace, debug, info, warn, error, fatal

# Examples:
bunyan -l warn app.log        # Show only warn, error, fatal
bunyan -l error app.log       # Show only error, fatal
bunyan --level debug app.log  # Show debug and above

Conditional Filtering

Use JavaScript expressions to filter logs based on any field values.

# Conditional filtering
bunyan -c CONDITION [FILE ...]
bunyan --condition CONDITION [FILE ...]

# CONDITION is a JavaScript boolean expression
# Available variables: level, name, hostname, pid, time, msg, and any custom fields

# Examples:
bunyan -c 'this.pid == 1234' app.log
bunyan -c 'this.component == "database"' app.log  
bunyan -c 'this.responseTime > 1000' app.log
bunyan -c 'this.level >= 40 && this.component == "auth"' app.log

Time Range Filtering

Filter logs by time ranges using flexible time specifications.

# Time range filtering
bunyan --time TIME_RANGE [FILE ...]

# TIME_RANGE formats:
# TIME            - From TIME to end of logs
# TIME-TIME       - Between two times
# -TIME           - From start to TIME

# Time formats:
# 2023-01-15                    - Date only
# 2023-01-15T10:30:00           - ISO datetime
# 2023-01-15T10:30:00.123Z      - ISO with milliseconds
# 10:30                         - Time today
# 1h                            - 1 hour ago
# 30m                           - 30 minutes ago
# 2d                            - 2 days ago

# Examples:
bunyan --time '2023-01-15T10:00:00-2023-01-15T11:00:00' app.log
bunyan --time '1h-' app.log                    # Last hour
bunyan --time '-2023-01-15T10:00:00' app.log   # Up to specific time

Process and Host Filtering

Filter logs by process ID or hostname for multi-process applications.

# Process ID filtering
bunyan --pid PID [FILE ...]

# Examples:
bunyan --pid 1234 app.log       # Show only logs from PID 1234
bunyan --pid 1234,5678 app.log  # Multiple PIDs (comma-separated)

Paging and Output Control

Control output paging and display behavior.

# Paging options
bunyan --pager [FILE ...]         # Use default pager (less)
bunyan --no-pager [FILE ...]      # Disable pager
bunyan --color [FILE ...]         # Force colorized output
bunyan --no-color [FILE ...]      # Disable colors

Advanced Options

Additional options for specialized use cases.

# JSON validation and error handling
bunyan --strict [FILE ...]        # Suppress all but legal Bunyan JSON log lines
                                  # (non-JSON and non-Bunyan lines normally pass through)

# DTrace process monitoring (supported platforms only)
bunyan -p PID [FILE ...]          # Process bunyan:log-* probes from specific PID
bunyan -p "*"                     # Monitor all processes  
bunyan -p NAME                    # Monitor processes matching command pattern

# Time display options
bunyan -L [FILE ...]              # Display time in local time instead of UTC
bunyan --time local [FILE ...]    # Same as -L

# Help and version
bunyan --help                     # Show help information
bunyan --version                  # Show version information

Usage Examples:

# Basic log viewing with different formats
bunyan app.log                           # Default long format
bunyan -o short app.log                  # Compact format
bunyan -o simple app.log                 # Minimal format
bunyan -o json app.log                   # Raw JSON

# Level filtering examples
bunyan -l error app.log                  # Errors and above only
bunyan -l debug app.log                  # All messages debug and above

# Combining filters
bunyan -l warn -c 'this.component == "auth"' app.log
bunyan --level error --time '1h-' app.log

# Real-time monitoring
tail -f app.log | bunyan -l warn -o short

# Complex filtering
bunyan -c 'this.responseTime > 100 && this.status >= 400' access.log
bunyan -c 'this.level >= 40 && this.req && this.req.url.includes("/api/")' app.log

# Time-based analysis
bunyan --time '2023-12-01-2023-12-02' app.log
bunyan --time '09:00-17:00' app.log      # Business hours
bunyan --time '30m-' app.log             # Last 30 minutes

# Multi-file processing
bunyan app1.log app2.log error.log       # Multiple files
bunyan *.log                             # All log files
cat *.log | bunyan -l error              # Concatenated input

# Process-specific logs in multi-process environment
bunyan --pid 1234 app.log
ps aux | grep myapp | awk '{print $2}' | xargs -I {} bunyan --pid {} app.log

Output Format Examples

Long Format (Default)

[2023-12-07T10:30:45.123Z]  INFO: myapp/1234 on hostname: User login successful
    user: "alice"
    ip: "192.168.1.100"
    duration: 45

Short Format

10:30:45.123Z  INFO myapp: User login successful (user=alice, ip=192.168.1.100)

Simple Format

INFO myapp: User login successful

JSON Format

{"v":0,"level":30,"name":"myapp","hostname":"hostname","pid":1234,"time":"2023-12-07T10:30:45.123Z","msg":"User login successful","user":"alice","ip":"192.168.1.100","duration":45}

Integration with Log Management

Logrotate Integration

Use bunyan CLI with logrotate for automated log processing:

# In logrotate config
/var/log/myapp/*.log {
    daily
    rotate 30
    compress
    delaycompress
    postrotate
        bunyan -l error /var/log/myapp/*.log > /var/log/myapp/daily-errors.log
    endscript
}

Monitoring and Alerting

Extract specific events for monitoring systems:

# Extract error events for alerting
bunyan -l error -o json app.log | jq '.msg'

# Count errors by component
bunyan -l error -c 'this.component' app.log | \
  bunyan -o json | jq -r '.component' | sort | uniq -c

# Performance monitoring
bunyan -c 'this.responseTime > 1000' access.log -o short

Log Analysis Workflows

Common patterns for log analysis:

# Daily error summary
bunyan --time 'yesterday' -l error app.log | \
  bunyan -o json | jq -r '.component' | sort | uniq -c

# Peak traffic analysis  
bunyan --time '12:00-14:00' access.log | \
  bunyan -c 'this.status >= 200 && this.status < 300' -o json | wc -l

# Error correlation
bunyan -l error --time '1h-' app.log | \
  bunyan -o json | jq -r '.req_id' | sort | uniq | \
  head -10 | xargs -I {} bunyan -c "this.req_id == '{}'" app.log