Varicon Observability

Unified observability package for logs, traces, and metrics across all Varicon services.

Features

• Universal Log Capture: Captures all logs regardless of how they're created
• Distributed Tracing: Automatic trace correlation across services
• Metrics: System telemetry and performance metrics
• Zero Code Changes: Works with existing logging code
• Framework Support: Auto-detects and instruments Django, FastAPI, Celery
• Async DB spans: instrument_sqlalchemy() traces SQLAlchemy + asyncpg engines (psycopg2 auto-instrumentation doesn't cover async)
• Content redaction: strips LLM prompt/response content (ADK / GenAI-semconv / OpenInference / Traceloop) from spans before export — on by default, fails closed
• Local span inspection: dump spans to an NDJSON file (OTEL_SPAN_FILE_EXPORT) and run in file-only mode with no backend

Installation

From Local Source (Development)

cd varicon_observability
pip install -e .

# Or with optional dependencies
pip install -e ".[full]"

From Git Repository

pip install git+https://github.com/your-org/varicon-observability.git

# With optional dependencies
pip install "git+https://github.com/your-org/varicon-observability.git#egg=varicon-observability[full]"

Build and Install from Source

cd varicon_observability
python -m build
pip install dist/varicon_observability-*.whl

Installation Options

• Basic: pip install varicon-observability
• Django: pip install varicon-observability[django]
• FastAPI: pip install varicon-observability[fastapi]
• Celery: pip install varicon-observability[celery]
• AWS platform attributes: pip install varicon-observability[aws] — adds cloud.platform, aws.ecs.* and friends to the Resource. Not included by [django]/[fastapi]/[celery]; already in [full]. Without it, platform detection is a silent no-op rather than an error.
• Full: pip install varicon-observability[full]

Quick Start

Django (varicon)

# varicon/varicon/asgi.py or settings.py
from varicon_observability import setup_observability

setup_observability(service_name="varicon-django")

FastAPI (integrations_service)

# integrations_service/main.py
from varicon_observability import setup_observability

setup_observability(service_name="integration-service")

Configuration

Set environment variables:

OTEL_ENABLED=true
OTEL_SERVICE_NAME=my-service
OTEL_SERVICE_VERSION=v1.2.3-4-gabc1234  # build id; defaults to "unset" (see below)
OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=grpc  # or http
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=your-key
OTEL_METRIC_EXPORT_INTERVAL=60000  # Export metrics every 60 seconds (ms)

# Span filtering (independent)
OTEL_FILTER_DATABASE_SPANS=true       # set false to KEEP DB spans (asyncpg DB observability)
OTEL_FILTER_HEALTH_CHECK_SPANS=true   # drop health-check spans, independent of DB filtering
OTEL_FILTER_EMPTY_QUEUE_POLLS=true    # drop SQS ReceiveMessage spans that succeeded and returned nothing
                                      # (failed polls and polls that returned work are always kept)
OTEL_FILTER_UNATTRIBUTED_ROOT_PROBE=true  # drop the `HEAD /` probe (17% of prod server spans).
                                      # NOT a health check - separate flag on purpose

# LLM/agent content redaction (on by default, fails closed)
OTEL_REDACT_SPAN_CONTENT=true
OTEL_REDACT_SPAN_ATTRIBUTES=          # extra content attribute keys, comma-separated

# Local inspection: dump spans to NDJSON; enables file-only mode with no OTLP endpoint
OTEL_SPAN_FILE_EXPORT=                # e.g. /tmp/spans.ndjson

service.version

Prefer the parameter over the env var when the value comes from application code:

setup_observability(service_name="my-service", version=settings.APP_VERSION)

ObservabilityConfig reads OTEL_SERVICE_VERSION from the environment once, at import time. So os.environ["OTEL_SERVICE_VERSION"] = ... in your startup path is silently ignored whenever this package was imported earlier in the process — which, in a Django app, it usually was. The parameter assigns the class attribute that resource_attributes() reads at provider-build time, exactly as service_name= already does.

The default is "unset", not a version-shaped placeholder. A default like 1.0.0 is indistinguishable from a genuinely versioned service, so service.version looks populated while telling you nothing — which is how the Varicon monolith ran unversioned across every tier unnoticed (VDP-1656). If you see unset in Honeycomb, that service is not passing a build id.

An empty or whitespace-only OTEL_SERVICE_VERSION also falls back to "unset" rather than shipping blank, since --build-arg FOO=""-style plumbing sets the variable without giving it a value.

See EXAMPLES.md for instrument_sqlalchemy(), content redaction, and local span inspection.

What Gets Captured

• All Python logging (logging.getLogger(), IntegrationLogger(), etc.)
• Framework logs (Django, FastAPI, Uvicorn, Celery)
• HTTP requests (requests, httpx)
• Database queries (PostgreSQL via psycopg2; SQLAlchemy + asyncpg via instrument_sqlalchemy())
• Redis operations
• Custom traces and metrics

Custom Metrics

Create custom metrics for Signoz using get_meter() or the built-in helpers:

from varicon_observability import setup_observability, get_meter, get_request_counter

setup_observability(service_name="my-service")

# Option 1: Use get_meter() for full control
meter = get_meter()
my_counter = meter.create_counter("custom.events", unit="1", description="Custom events")
my_counter.add(1, {"event_type": "signup"})

# Option 2: Use built-in helpers
request_counter = get_request_counter()
request_counter.add(1, {"endpoint": "/api/users"})

Note: SQLAlchemy logs are disabled by default (set ENABLE_SQLALCHEMY_LOGS=true to enable)

Architecture

Application Code
    ↓
Python Logging (any pattern)
    ↓
Root Logger Handler
    ↓
OpenTelemetry LoggingHandler
    ↓
OTLP Exporter
    ↓
SigNoz

All logs automatically include trace context for correlation.