Getting Started with SO-Log — Quick Tutorial for BeginnersSO-Log is a lightweight logging system designed to help developers capture, store, and analyze application events with minimal setup. This tutorial walks you through core concepts, installation, basic usage patterns, configuration options, and best practices so you can start using SO-Log in your projects quickly and confidently.
What is SO-Log?
SO-Log is a structured logging library aimed at simplicity and flexibility. It emphasizes:
- Structured JSON logs for easier parsing and querying.
- Minimal configuration to get started fast.
- Pluggable backends so you can write logs to files, consoles, or remote services.
- Extensible formatters to adapt logs to your monitoring stack.
When to use SO-Log
Use SO-Log if you want:
- Clear, machine-readable logs that integrate with log processors (ELK, Splunk, Datadog).
- A logging solution that’s easy to adopt in small services or microservices.
- Lightweight tooling without the overhead of heavy frameworks.
Installation
Install SO-Log using your package manager. Examples:
-
npm (Node.js)
npm install so-log
-
pip (Python)
pip install so-log
(Adjust the command for your environment and language bindings.)
Basic Concepts
- Logger: the main object used to emit logs.
- Level: severity (e.g., DEBUG, INFO, WARN, ERROR).
- Handler/Transport: where logs are sent (console, file, remote).
- Formatter: transforms log records into the desired format (JSON, plain text).
- Context: structured fields attached to logs (request_id, user_id).
Quick Start (Example: JavaScript)
Create a simple logger and write messages:
const SOLog = require('so-log'); const logger = new SOLog({ level: 'info', transports: [ new SOLog.transports.Console() ], formatter: SOLog.formatters.json() }); logger.info('Server started', { port: 8080 }); logger.debug('Debugging details'); // won't appear because level is 'info' logger.error('Unhandled exception', { error: err.message });
Output (JSON):
{"timestamp":"2025-08-30T12:34:56.789Z","level":"info","message":"Server started","port":8080}
Quick Start (Example: Python)
from so_log import Logger, ConsoleTransport, JSONFormatter logger = Logger(level='INFO', transports=[ConsoleTransport()], formatter=JSONFormatter()) logger.info('Server started', extra={'port': 8080}) logger.debug('Debug info') # won't show at INFO level logger.error('Unhandled exception', extra={'error': str(err)})
Configuration Options
Common options you’ll encounter:
- level: minimum log level.
- transports: list of handlers (console, file, HTTP).
- formatter: json, compact, or custom.
- timestamp_format: ISO8601, epoch, or custom pattern.
- buffering: batch writes for performance.
- retention: log rotation and cleanup policy.
Example (config file JSON):
{ "level": "debug", "transports": [ { "type": "console" }, { "type": "file", "path": "/var/log/myapp.log", "maxSize": "10m", "maxFiles": 5 } ], "formatter": "json", "timestamp_format": "iso8601" }
Adding Context Automatically
Attach contextual data (request IDs, user IDs) so every log carries important trace information.
JavaScript middleware example (Express):
app.use((req, res, next) => { req.logger = logger.child({ request_id: req.headers['x-request-id'] || generateId() }); next(); }); app.get('/', (req, res) => { req.logger.info('Handling root endpoint'); res.send('OK'); });
Python (Flask) example:
@app.before_request def add_logger(): g.logger = logger.with_context({'request_id': request.headers.get('X-Request-ID', gen_id())})
Transports and Remote Logging
Common transports:
- Console — good for local dev.
- File — persistent local logs; use rotation.
- HTTP/HTTPS — send to log collectors or SaaS (Logstash, Datadog).
- Syslog — for system integration.
Example: send logs to a remote collector with batching and retries to avoid losing messages on network failures.
Filtering and Sampling
To reduce noise and cost:
- Filter out low-value logs at source.
- Sample repetitive logs (e.g., only 1% of DEBUG).
- Use dynamic sampling based on error rates.
Example: sample 1 in 100 debug messages:
logger.debug('Cache miss', { sampleRate: 0.01 });
Log Rotation and Retention
Rotate files by size or time; retain only necessary history. Configure maxSize, maxFiles, or use external tools (logrotate).
Searching and Analyzing Logs
Because SO-Log outputs structured logs, indexes and queries are more powerful. Common workflows:
- Send JSON logs to Elasticsearch and use Kibana for dashboards.
- Use Datadog or Papertrail for alerting and traces.
- Use grep/jq for quick local searches.
Best Practices
- Use structured fields instead of embedding data in messages.
- Always include timestamps and levels.
- Attach request/user context early.
- Avoid logging sensitive data (PII, secrets). Mask or omit them.
- Use sampling and rate-limiting for high-frequency events.
- Test logging under load to ensure performance.
Troubleshooting
- No logs appearing: check level, transport configuration, and process permissions.
- Missing fields: ensure formatter supports context and you’re passing extra data.
- Performance issues: enable batching, increase buffer sizes, or offload remote sending.
Example: End-to-End Setup
- Install SO-Log.
- Configure JSON formatter and console + file transports.
- Add request-context middleware.
- Send logs to ELK with an HTTP transport.
- Create Kibana dashboards for errors and latency.
Resources and Next Steps
- Read the SO-Log API docs for advanced features (child loggers, custom formatters).
- Integrate with your observability stack (tracing, metrics).
- Add unit tests asserting important logs appear.
SO-Log makes structured logging approachable for beginners while providing the flexibility needed in production. Follow the quick examples above to integrate it into a small app, then iterate on configuration and transports as your needs grow.