README.md

Opentelemetry auto instrumentation for django-stomp

This library will help you to use opentelemetry traces and metrics on Django STOMP usage library.

Installation

pip install opentelemetry-instrumentation-django-stomp

How to use ?

You can use the DjangoStompInstrumentor().instrument() for example in manage.py file.

#!/usr/bin/env python
"""Django's command-line utility for administrative tasks."""
import os
import sys
import typing

from opentelemetry_instrumentation_django_stomp import DjangoStompInstrumentor

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
from opentelemetry.trace.span import Span


def publisher_hook(span: Span, body: typing.Dict, headers: typing.Dict):
    # Custom code in your project here we can see span attributes and make custom logic with then.
    pass


def consumer_hook(span: Span, body: typing.Dict, headers: typing.Dict):
    # Custom code in your project here we can see span attributes and make custom logic with then.
    pass


provider = TracerProvider()
trace.set_tracer_provider(provider)
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

def main():
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "application.settings")
    DjangoStompInstrumentor().instrument(
        trace_provider=trace,
        publisher_hook=publisher_hook,
        consumer_hook=consumer_hook,
    )
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


if __name__ == "__main__":
    main()

The code above will create telemetry wrappers inside django-stomp code and creates automatic spans with broker data.

The DjangoStompInstrumentor can receive three optional parameters:

• trace_provider: The tracer provider to use in open-telemetry spans.
• publisher_hook: The callable function on publisher action to call before the original function call, use this to override, enrich the span or get span information in the main project.
• consumer_hook: The callable function on consumer action to call before the original function call, use this to override, enrich the span or get span information in the main project.

⚠️ The hook function will not raise an exception when an error occurs inside hook function, only a warning log is generated

PUBLISHER example

With the django-stomp, we can publish a message to a broker using publisher.send and the instrumentator can include a span with telemetry data in this function utilization.

    from uuid import uuid4
    from django_stomp.builder import build_publisher
    publisher = build_publisher(f"publisher-unique-name-{uuid4()}")
    publisher.send(
        queue='/queue/a-destination',
        body={"a": "random","body": "message"},
    )

The publisher span had "PUBLISHER" name.

CONSUMER example

With the django-stomp, we create a simple consumer using pubsub command and the instrumentator can include a span with telemetry data in this function utilization.

   python manage.py pubsub QUEUE_NAME callback_function_to_consume_message

Consumer spans can generate up to three types:

• CONSUMER
• ACK
• NACK

Supress django-stomp traces and metrics

When the flag OTEL_PYTHON_DJANGO_STOMP_INSTRUMENT has False value traces and metrics will not be generated. Use this to supress the django-stomp instrumentation.

HOW TO CONTRIBUTE ?

Look the contributing specs