polyglot-logger 0.2.0

Python bindings for the Polyglot native structured logger

Polyglot Logger (Python)

Idiomatic Python bindings (polyglot-logger) for the Polyglot native structured logger.

Part of the Polyglot modular monorepo — see polyglot-go for the core Go implementation and other language bindings.

Quick Start

from polyglot_logger import Logger, Level

with Logger("payments-api", environment="prod", file_path="/var/log/payments.log") as log:
    log.set_fields({"traceId": "abc"})
    log.info("order created", order_id=123, amount=42.5)
    log.log_simple(Level.ERROR, "payment failed")
    print(log.stats())

Features

• ✅ Auto-initialization: Place polyglot.yaml in project root, logger auto-discovers & loads it
• ✅ Bundled binaries: Pre-compiled native libraries for Windows/macOS/Linux included in wheel
• ✅ Zero config: Works immediately after pip install without manual setup
• ✅ Thread-safe: Concurrent log/flush/stats/set_fields calls safe on one instance
• ✅ Type hints: Full PEP 484 annotations in source

Installation

pip install polyglot-logger

All native binaries (.so, .dll, .dylib) are included in the wheel. No separate compilation needed.

Building from Source

To build from the core repository with all language bindings:

git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot

# Build native library and all bindings
make build-native
pip install -e bindings/python

Configuration

Place a polyglot.yaml in your project root:

service: payments-api
environment: prod
logging:
  level: info
  async: true
file:
  enabled: true
  path: /var/log/payments.log

On first import, the logger auto-discovers this config and initializes automatically.

Alternatively, set environment variables:

export POLYGLOT_CONFIG_PATH=/path/to/polyglot.yaml
export POLYGLOT_CONFIG_FILE=/path/to/config.json

Documentation

Resource	Description
Python API	Language-specific API reference
User Guide	Logging concepts, fields, async modes
Configuration	Full schema & examples
Getting Started	Build & run first log
Architecture	Design & internals
Repositories Overview	How all 4 repos work together

Usage Examples

Basic Logging

from polyglot_logger import Logger, Level

log = Logger("my-app", environment="prod")
log.info("Application started")
log.error("Something went wrong", error="connection timeout")
log.close()

With Context Fields

log.set_fields({"user_id": "u123", "request_id": "r456"})
log.info("user action")  # Includes user_id & request_id automatically

Multiple Sinks

log = Logger(
    service="payments-api",
    environment="prod",
    file_path="/var/log/payments.log",
    http_endpoint="https://logs.company.com/ingest",
)
log.info("payment processed")  # Sent to both file and HTTP endpoint

Statistics

stats = log.stats()
print(stats.queued)    # Entries currently in queue
print(stats.flushed)   # Entries successfully written
print(stats.dropped)   # Entries dropped due to overflow
print(stats.errors)    # Write errors

Thread Safety

A single logger instance is safe for concurrent calls to:

log.log_simple(level, message)  # Thread-safe
log.info(msg, **fields)         # Thread-safe
log.flush()                     # Thread-safe
log.stats()                     # Thread-safe
log.set_fields(fields)          # Thread-safe
log.reload_config()             # Thread-safe

Only close() should be called by a single thread (one owner of the logger lifecycle).

Native Library Auto-Discovery

The binding automatically discovers the native library:

1. Checks for bundled binary in polyglot_logger/bin/
2. Falls back to POLYGLOT_LOGGER_LIB environment variable (if set)
3. If neither found: error with helpful message

Troubleshooting

"native library not found"

# Verify package has binaries
pip show polyglot-logger | grep Location
# Check if bin/ folder exists
ls ~/.venv/lib/python3.x/site-packages/polyglot_logger/bin/

# Set explicit path
export POLYGLOT_LOGGER_LIB=/path/to/liblogger.so

"polyglot.yaml not found"

# Create config in your project root
touch polyglot.yaml

# Or set environment variable
export POLYGLOT_CONFIG_PATH=/path/to/config.yaml

ImportError on macOS

Ensure you're using Python 3.9+:

python3 --version
pip install --upgrade polyglot-logger

Version Management

This binding is independently versioned. Each release:

• Includes latest C ABI from polyglot-go
• Pre-compiled native binaries for all platforms
• Complete source with type hints

Check polyglot-go releases to see which core version this binding is based on.

Repository Links

• This repo (Python bindings): polyglot-py
• Core (Go logger): Polyglot
• Node.js bindings: polyglot-node
• .NET bindings: polyglot-csharp

Contributing

To contribute to Python bindings:

# Clone core with all submodules
git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot/bindings/python

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Make changes
vim polyglot_logger/__init__.py

# Run tests
python -m pytest tests/

# Commit and push to polyglot-py
git add polyglot_logger/
git commit -m "fix: description"
git push origin main

# Update core submodule reference
cd ../..
git add bindings/python
git commit -m "chore: bump python binding"
git push origin main

License

MIT — see LICENSE in this repository