Send Django Traces, Metrics, and Logs to SigNoz

Problem statement

You want APM-style visibility, including request traces, slow queries, error rates, and correlated logs, without a per-host commercial agent, and you want instrumentation that is not tied to one vendor. SigNoz is an open-source observability platform built on OpenTelemetry and ClickHouse. Django sends data with standard OpenTelemetry libraries over OTLP, so the same instrumentation could later point somewhere else.

1. pip install opentelemetry-distro opentelemetry-exporter-otlp and run opentelemetry-bootstrap -a install to add instrumentations.
2. Start Gunicorn with opentelemetry-instrument, setting OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_ENDPOINT.
3. With Gunicorn, initialize OpenTelemetry in the post_fork hook so each worker has its own exporter.
4. Self-host SigNoz with its Docker or Helm setup, or use SigNoz Cloud with an ingestion key header.
5. Add trace IDs to Django logs and ship logs through the OpenTelemetry Collector.

Step-by-step solution

1. Install OpenTelemetry

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-bootstrap detects installed libraries (Django, psycopg, redis, requests, Celery) and installs matching instrumentation packages.

2. Configure the exporter

OTEL_SERVICE_NAME=shop-web
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=3f2a1c9
OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-otel-collector:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.2
DJANGO_SETTINGS_MODULE=config.settings.production

For SigNoz Cloud, use the regional ingest endpoint and add OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<key>. Sampling 20 percent of traces keeps storage manageable.

3. Handle Gunicorn's forking

Auto-instrumentation started in the Gunicorn master does not survive forking cleanly for the batch span processor. Initialize in each worker instead:

# gunicorn.conf.py
def post_fork(server, worker):
    from opentelemetry import trace
    from opentelemetry.sdk.trace import TracerProvider
    from opentelemetry.sdk.trace.export import BatchSpanProcessor
    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk.resources import Resource
    from opentelemetry.instrumentation.django import DjangoInstrumentor
    from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

    provider = TracerProvider(resource=Resource.create())
    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(provider)
    DjangoInstrumentor().instrument()
    PsycopgInstrumentor().instrument()

Run Gunicorn normally (without opentelemetry-instrument) when using this hook. Celery workers have a similar pattern with the worker_process_init signal.

4. Run SigNoz

Self-hosting uses the project's Docker Compose or Helm chart, which deploys the collector, ClickHouse, the query service, and the UI. ClickHouse needs memory and fast disks; plan for several gigabytes of RAM even for small installs. SigNoz Cloud removes that operational work.

5. Correlate logs

Add trace and span IDs to log records so you can jump from a trace to its logs:

from opentelemetry.instrumentation.logging import LoggingInstrumentor
LoggingInstrumentor().instrument(set_logging_format=True)

Ship logs to the SigNoz collector with the OpenTelemetry Collector's filelog receiver, or send them over OTLP from Python's logging handler.

Explanation

OpenTelemetry defines APIs and SDKs for traces, metrics, and logs, plus the OTLP wire protocol. Instrumentation libraries hook into Django's request handling, database drivers, and HTTP clients to produce spans. SigNoz receives OTLP data through its collector and stores it in ClickHouse, a columnar database suited to high-volume telemetry. Because the app only knows about OpenTelemetry, the backend is replaceable.

Edge cases / notes

• Sampling. Use parent-based sampling so a trace is either fully kept or fully dropped across services.
• Sensitive data. Instrumentations can record SQL statements and URLs; scrub parameters or disable statement capture if they may contain personal data.
• Metrics. Django and Gunicorn metrics through OTel are still maturing; Prometheus exporters remain a common complement.

Next steps

• Learn the instrumentation details in Django OpenTelemetry Tracing.
• Compare with Monitor Django With Prometheus and Grafana.
• Correlate requests and logs with Django Request ID Log Correlation.

FAQ

Does SigNoz need a special Django agent?

No. It uses standard OpenTelemetry instrumentation and the OTLP exporter.

Why do traces disappear with Gunicorn workers?

Exporters started in the master do not work after fork. Initialize OpenTelemetry in the post_fork hook.

Is SigNoz free?

The self-hosted edition is open source. SigNoz Cloud is a paid managed service.

Can I switch from SigNoz to another backend later?

Yes. Point the OTLP exporter at a different endpoint; the Django instrumentation stays.