# corrupt o11y
[](https://github.com/corruptmane/corrupt-o11y-py/actions/workflows/ci.yml)
[](https://codecov.io/gh/mykyta/corrupt-o11y-py)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/uv)
A comprehensive observability library for Python applications with logging, metrics, and tracing.
## Features
- **Structured Logging** - JSON-formatted logs with OpenTelemetry trace correlation
- **Flexible Processor Chain** - PII redaction, field filtering, exception enhancement, conditional processing
- **Prometheus Metrics** - Built-in collectors for GC, platform, and process metrics with custom metric support
- **OpenTelemetry Tracing** - Multiple exporters (OTLP HTTP/gRPC, console)
- **Operational Endpoints** - Health checks, metrics, and service info HTTP server
- **Service Metadata** - Centralized service information management
- **Type Safe** - Strict type checking with mypy
- **Environment-Based Configuration** - All components configurable via environment variables
## Quick Start
```python
from corrupt_o11y import logging, metrics, tracing
from corrupt_o11y.operational import Status, OperationalServerConfig, OperationalServer
from corrupt_o11y.metadata import ServiceInfo
async def main():
# Setup service information
service_info = ServiceInfo.from_env()
# Configure logging
log_config = logging.LoggingConfig.from_env()
logging.configure_logging(log_config)
logger = logging.get_logger(__name__)
# Set up metrics
metrics_collector = metrics.MetricsCollector()
metrics_collector.create_service_info_metric_from_service_info(service_info)
# Configure tracing
trace_config = tracing.TracingConfig.from_env()
tracing.configure_tracing(trace_config, service_info.name, service_info.version)
tracer = tracing.get_tracer(__name__)
# Set up operational server
status = Status()
op_config = OperationalServerConfig.from_env()
server = OperationalServer(op_config, service_info.asdict(), status, metrics_collector)
await server.start()
status.is_ready = True
# Use observability features
logger.info("Service started", extra={"port": 8080})
with tracer.start_as_current_span("process_request"):
# Your business logic here
logger.info("Processing request")
```
## Configuration
All components are configured via environment variables:
### Logging
- `LOG_LEVEL` - Log level (default: INFO)
- `LOG_AS_JSON` - Output JSON format (default: false)
- `LOG_TRACING` - Include trace information (default: false)
### Tracing
- `TRACING_EXPORTER_TYPE` - Exporter type: stdout, http, grpc (default: stdout)
- `TRACING_EXPORTER_ENDPOINT` - OTLP endpoint URL (required for http/grpc)
- `TRACING_INSECURE` - Use insecure connection (default: false)
- `TRACING_TIMEOUT` - Request timeout in seconds (default: 30)
### Metrics
- `METRICS_ENABLE_GC` - Enable GC metrics collector (default: true)
- `METRICS_ENABLE_PLATFORM` - Enable platform metrics collector (default: true)
- `METRICS_ENABLE_PROCESS` - Enable process metrics collector (default: true)
- `METRICS_PREFIX` - Prefix for custom metrics (default: empty)
### Operational Server
- `OPERATIONAL_HOST` - Bind address (default: 0.0.0.0)
- `OPERATIONAL_PORT` - Port number (default: 42069)
### Service Metadata
- `SERVICE_NAME` - Service name (default: unknown-dev)
- `SERVICE_VERSION` - Service version (default: unknown-dev)
- `INSTANCE_ID` - Instance identifier (default: unknown-dev)
- `COMMIT_SHA` - Git commit SHA (default: unknown-dev)
- `BUILD_TIME` - Build timestamp (default: unknown-dev)
## Endpoints
The operational server provides:
- `GET /health` - Liveness check (200 if alive)
- `GET /ready` - Readiness check (200 if ready)
- `GET /metrics` - Prometheus metrics
- `GET /info` - Service information JSON
## Service Info Metric
Following Prometheus best practices, service metadata is exposed as an info metric:
```prometheus
service_info{service="my-service", version="1.2.3", instance="pod-123", commit="abc123"} 1
```
This provides rich metadata without increasing cardinality of other metrics.
## Advanced Usage
### Logging Processors
The library supports flexible processor chains for log processing:
```python
from corrupt_o11y.logging import LoggingCollector
from corrupt_o11y.logging.processors import (
PIIRedactionProcessor,
FieldFilterProcessor,
EnhancedExceptionProcessor,
ConditionalProcessor,
is_level
)
collector = LoggingCollector()
collector.preprocessing().extend([
PIIRedactionProcessor(), # Redact PII (emails, phones, etc.)
FieldFilterProcessor(blocked_fields=["password", "token"]), # Filter sensitive fields
ConditionalProcessor(
condition=is_level("error"),
processor=EnhancedExceptionProcessor() # Enhanced exception info for errors
)
])
logging.configure_logging(config, collector)
```
### Custom Metrics
```python
from prometheus_client import Counter, Histogram
# Create custom metrics
request_counter = Counter(
"http_requests_total",
"Total HTTP requests",
["method", "endpoint", "status"],
registry=None
)
# Register with collector
metrics_collector.register("http_requests", request_counter)
# Use metrics
request_counter.labels(method="GET", endpoint="/api/users", status="200").inc()
```
## Installation
```bash
# With uv (recommended)
uv add corrupt-o11y
```
```bash
# With pip
pip install corrupt-o11y
```
## Development
For contributors (using [uv](https://docs.astral.sh/uv/) as recommended package manager):
```bash
# Install with development dependencies
uv sync --dev
# Install pre-commit hooks
uv run pre-commit install
# Run linting and type checking
uv run ruff check
uv run ruff format --check
uv run mypy
# Run tests with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing --cov-branch
# Or just commit - pre-commit will run all checks automatically
```
With pip:
```bash
pip install -e ".[dev]"
pre-commit install
```
## Requirements
- Python 3.11+
- OpenTelemetry
- Prometheus Client
- structlog
- aiohttp
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "corrupt-o11y",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "logging, metrics, monitoring, observability, opentelemetry, prometheus, tracing",
"author": null,
"author_email": "Mykyta <mykyta@example.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/31/601b3f1240964c90bcac177357aae57cc3601101b7b80bfc6a9a372d1f79/corrupt_o11y-0.2.0.tar.gz",
"platform": null,
"description": "# corrupt o11y\n\n[](https://github.com/corruptmane/corrupt-o11y-py/actions/workflows/ci.yml)\n[](https://codecov.io/gh/mykyta/corrupt-o11y-py)\n[](https://www.python.org/downloads/)\n[](https://github.com/astral-sh/uv)\n\nA comprehensive observability library for Python applications with logging, metrics, and tracing.\n\n## Features\n\n- **Structured Logging** - JSON-formatted logs with OpenTelemetry trace correlation\n- **Flexible Processor Chain** - PII redaction, field filtering, exception enhancement, conditional processing\n- **Prometheus Metrics** - Built-in collectors for GC, platform, and process metrics with custom metric support\n- **OpenTelemetry Tracing** - Multiple exporters (OTLP HTTP/gRPC, console)\n- **Operational Endpoints** - Health checks, metrics, and service info HTTP server\n- **Service Metadata** - Centralized service information management\n- **Type Safe** - Strict type checking with mypy\n- **Environment-Based Configuration** - All components configurable via environment variables\n\n## Quick Start\n\n```python\nfrom corrupt_o11y import logging, metrics, tracing\nfrom corrupt_o11y.operational import Status, OperationalServerConfig, OperationalServer\nfrom corrupt_o11y.metadata import ServiceInfo\n\nasync def main():\n # Setup service information\n service_info = ServiceInfo.from_env()\n\n # Configure logging\n log_config = logging.LoggingConfig.from_env()\n logging.configure_logging(log_config)\n logger = logging.get_logger(__name__)\n\n # Set up metrics\n metrics_collector = metrics.MetricsCollector()\n metrics_collector.create_service_info_metric_from_service_info(service_info)\n\n # Configure tracing\n trace_config = tracing.TracingConfig.from_env()\n tracing.configure_tracing(trace_config, service_info.name, service_info.version)\n tracer = tracing.get_tracer(__name__)\n\n # Set up operational server\n status = Status()\n op_config = OperationalServerConfig.from_env()\n server = OperationalServer(op_config, service_info.asdict(), status, metrics_collector)\n await server.start()\n status.is_ready = True\n\n # Use observability features\n logger.info(\"Service started\", extra={\"port\": 8080})\n\n with tracer.start_as_current_span(\"process_request\"):\n # Your business logic here\n logger.info(\"Processing request\")\n```\n\n## Configuration\n\nAll components are configured via environment variables:\n\n### Logging\n- `LOG_LEVEL` - Log level (default: INFO)\n- `LOG_AS_JSON` - Output JSON format (default: false)\n- `LOG_TRACING` - Include trace information (default: false)\n\n### Tracing\n- `TRACING_EXPORTER_TYPE` - Exporter type: stdout, http, grpc (default: stdout)\n- `TRACING_EXPORTER_ENDPOINT` - OTLP endpoint URL (required for http/grpc)\n- `TRACING_INSECURE` - Use insecure connection (default: false)\n- `TRACING_TIMEOUT` - Request timeout in seconds (default: 30)\n\n### Metrics\n- `METRICS_ENABLE_GC` - Enable GC metrics collector (default: true)\n- `METRICS_ENABLE_PLATFORM` - Enable platform metrics collector (default: true)\n- `METRICS_ENABLE_PROCESS` - Enable process metrics collector (default: true)\n- `METRICS_PREFIX` - Prefix for custom metrics (default: empty)\n\n### Operational Server\n- `OPERATIONAL_HOST` - Bind address (default: 0.0.0.0)\n- `OPERATIONAL_PORT` - Port number (default: 42069)\n\n### Service Metadata\n- `SERVICE_NAME` - Service name (default: unknown-dev)\n- `SERVICE_VERSION` - Service version (default: unknown-dev)\n- `INSTANCE_ID` - Instance identifier (default: unknown-dev)\n- `COMMIT_SHA` - Git commit SHA (default: unknown-dev)\n- `BUILD_TIME` - Build timestamp (default: unknown-dev)\n\n## Endpoints\n\nThe operational server provides:\n\n- `GET /health` - Liveness check (200 if alive)\n- `GET /ready` - Readiness check (200 if ready)\n- `GET /metrics` - Prometheus metrics\n- `GET /info` - Service information JSON\n\n## Service Info Metric\n\nFollowing Prometheus best practices, service metadata is exposed as an info metric:\n\n```prometheus\nservice_info{service=\"my-service\", version=\"1.2.3\", instance=\"pod-123\", commit=\"abc123\"} 1\n```\n\nThis provides rich metadata without increasing cardinality of other metrics.\n\n## Advanced Usage\n\n### Logging Processors\n\nThe library supports flexible processor chains for log processing:\n\n```python\nfrom corrupt_o11y.logging import LoggingCollector\nfrom corrupt_o11y.logging.processors import (\n PIIRedactionProcessor,\n FieldFilterProcessor,\n EnhancedExceptionProcessor,\n ConditionalProcessor,\n is_level\n)\n\ncollector = LoggingCollector()\ncollector.preprocessing().extend([\n PIIRedactionProcessor(), # Redact PII (emails, phones, etc.)\n FieldFilterProcessor(blocked_fields=[\"password\", \"token\"]), # Filter sensitive fields\n ConditionalProcessor(\n condition=is_level(\"error\"),\n processor=EnhancedExceptionProcessor() # Enhanced exception info for errors\n )\n])\n\nlogging.configure_logging(config, collector)\n```\n\n### Custom Metrics\n\n```python\nfrom prometheus_client import Counter, Histogram\n\n# Create custom metrics\nrequest_counter = Counter(\n \"http_requests_total\",\n \"Total HTTP requests\",\n [\"method\", \"endpoint\", \"status\"],\n registry=None\n)\n\n# Register with collector\nmetrics_collector.register(\"http_requests\", request_counter)\n\n# Use metrics\nrequest_counter.labels(method=\"GET\", endpoint=\"/api/users\", status=\"200\").inc()\n```\n\n## Installation\n\n```bash\n# With uv (recommended)\nuv add corrupt-o11y\n```\n\n```bash\n# With pip\npip install corrupt-o11y\n```\n\n## Development\n\nFor contributors (using [uv](https://docs.astral.sh/uv/) as recommended package manager):\n\n```bash\n# Install with development dependencies\nuv sync --dev\n\n# Install pre-commit hooks\nuv run pre-commit install\n\n# Run linting and type checking\nuv run ruff check\nuv run ruff format --check\nuv run mypy\n\n# Run tests with coverage\nuv run pytest tests/ --cov=src --cov-report=term-missing --cov-branch\n\n# Or just commit - pre-commit will run all checks automatically\n```\n\nWith pip:\n```bash\npip install -e \".[dev]\"\npre-commit install\n```\n\n## Requirements\n\n- Python 3.11+\n- OpenTelemetry\n- Prometheus Client\n- structlog\n- aiohttp\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive observability library for Python applications with logging, metrics, and tracing",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/mykyta/corrupt-o11y-py/issues",
"Documentation": "https://github.com/mykyta/corrupt-o11y-py#readme",
"Homepage": "https://github.com/mykyta/corrupt-o11y-py",
"Repository": "https://github.com/mykyta/corrupt-o11y-py.git"
},
"split_keywords": [
"logging",
" metrics",
" monitoring",
" observability",
" opentelemetry",
" prometheus",
" tracing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3753bf5519d37cf922377cab065530cbbb547c4e56cea0750f5de0d7ece43664",
"md5": "3e93a42c85d9feddefb5388f438c1314",
"sha256": "e2a04fd2f7190f8b3d41274f7ee939d294fbde5a384f042ef9de01f2c34b5196"
},
"downloads": -1,
"filename": "corrupt_o11y-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e93a42c85d9feddefb5388f438c1314",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 28230,
"upload_time": "2025-07-11T23:39:24",
"upload_time_iso_8601": "2025-07-11T23:39:24.961944Z",
"url": "https://files.pythonhosted.org/packages/37/53/bf5519d37cf922377cab065530cbbb547c4e56cea0750f5de0d7ece43664/corrupt_o11y-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c231601b3f1240964c90bcac177357aae57cc3601101b7b80bfc6a9a372d1f79",
"md5": "85eac32ddb03dda0d318e0df43d02245",
"sha256": "6821ef14f110fb0dea8f68cc33325f2f0cbc55ad23551b6c896bb9661a27d1d5"
},
"downloads": -1,
"filename": "corrupt_o11y-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "85eac32ddb03dda0d318e0df43d02245",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 21018,
"upload_time": "2025-07-11T23:39:26",
"upload_time_iso_8601": "2025-07-11T23:39:26.522423Z",
"url": "https://files.pythonhosted.org/packages/c2/31/601b3f1240964c90bcac177357aae57cc3601101b7b80bfc6a9a372d1f79/corrupt_o11y-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 23:39:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mykyta",
"github_project": "corrupt-o11y-py",
"github_not_found": true,
"lcname": "corrupt-o11y"
}
JSON
