• Stars
    star
    105
  • Rank 328,196 (Top 7 %)
  • Language
    Python
  • License
    BSD 3-Clause "New...
  • Created over 8 years ago
  • Updated about 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

OpenTracing instrumentation for the Django framework

Django Opentracing

https://travis-ci.org/opentracing-contrib/python-django.svg?branch=master

This package enables distributed tracing in Django projects via The OpenTracing Project. Once a production system contends with real concurrency or splits into many services, crucial (and formerly easy) tasks become difficult: user-facing latency optimization, root-cause analysis of backend errors, communication about distinct pieces of a now-distributed system, etc. Distributed tracing follows a request on its journey from inception to completion from mobile/browser all the way to the microservices.

As core services and libraries adopt OpenTracing, the application builder is no longer burdened with the task of adding basic tracing instrumentation to their own code. In this way, developers can build their applications with the tools they prefer and benefit from built-in tracing instrumentation. OpenTracing implementations exist for major distributed tracing systems and can be bound or swapped with a one-line configuration change.

If you want to learn more about the underlying python API, visit the python source code.

If you are migrating from the 0.x series, you may want to read the list of breaking changes.

Installation

Run the following command:

$ pip install django_opentracing

Setting up Tracing

In order to implement tracing in your system, add the following lines of code to your site's settings.py file:

import django_opentracing

# OpenTracing settings

# if not included, defaults to True.
# has to come before OPENTRACING_TRACING setting because python...
OPENTRACING_TRACE_ALL = True

# defaults to []
# only valid if OPENTRACING_TRACE_ALL == True
OPENTRACING_TRACED_ATTRIBUTES = ['arg1', 'arg2']

# Callable that returns an `opentracing.Tracer` implementation.
OPENTRACING_TRACER_CALLABLE = 'opentracing.Tracer'

# Parameters for the callable (Depending on the tracer implementation chosen)
OPENTRACING_TRACER_PARAMETERS = {
    'example-parameter-host': 'collector',
}

If you want to directly override the DjangoTracing used, you can use the following. This may cause import loops (See #10)

# some_opentracing_tracer can be any valid OpenTracing tracer implementation
OPENTRACING_TRACING = django_opentracing.DjangoTracing(some_opentracing_tracer)

Note: Valid request attributes to trace are listed here. When you trace an attribute, this means that created spans will have tags with the attribute name and the request's value.

Tracing All Requests

In order to trace all requests, OPENTRACING_TRACE_ALL needs to be set to True (the default). If you want to trace any attributes for all requests, then add them to OPENTRACING_TRACED_ATTRIBUTES. For example, if you wanted to trace the path and method, then set OPENTRACING_TRACED_ATTRIBUTES = ['path', 'method'].

Tracing all requests uses the middleware django_opentracing.OpenTracingMiddleware, so add this to your settings.py file's MIDDLEWARE_CLASSES at the top of the stack.

MIDDLEWARE_CLASSES = [
    'django_opentracing.OpenTracingMiddleware',
    ... # other middleware classes
]

Tracing Individual Requests

If you don't want to trace all requests to your site, set OPENTRACING_TRACE_ALL to False. Then you can use function decorators to trace individual view functions. This can be done by adding the following lines of code to views.py (or any other file that has url handler functions):

from django.conf import settings

tracing = settings.OPENTRACING_TRACING

@tracing.trace(optional_args)
def some_view_func(request):
    ... # do some stuff

This tracing method doesn't use middleware, so there's no need to add it to your settings.py file.

The optional arguments allow for tracing of request attributes. For example, if you want to trace metadata, you could pass in @tracing.trace('META') and request.META would be set as a tag on all spans for this view function.

Note: If OPENTRACING_TRACE_ALL is set to True, this decorator will be ignored, including any traced request attributes.

Accessing Spans Manually

In order to access the span for a request, we've provided an method DjangoTracing.get_span(request) that returns the span for the request, if it is exists and is not finished. This can be used to log important events to the span, set tags, or create child spans to trace non-RPC events.

Tracing an RPC

If you want to make an RPC and continue an existing trace, you can inject the current span into the RPC. For example, if making an http request, the following code will continue your trace across the wire:

@tracing.trace()
def some_view_func(request):
    new_request = some_http_request
    current_span = tracing.get_span(request)
    text_carrier = {}
    opentracing_tracer.inject(span, opentracing.Format.TEXT_MAP, text_carrier)
    for k, v in text_carrier.items():
        request.add_header(k,v)
    ... # make request

Example

Here is an example of a Django application that acts as both a client and server, with integrated OpenTracing tracers.

Breaking changes from 0.x

Starting with the 1.0 version, a few changes have taken place from previous versions:

  • DjangoTracer has been renamed to DjangoTracing, although DjangoTracer can be used still as a deprecated name. Likewise for OPENTRACING_TRACER being renamed to OPENTRACING_TRACING.
  • When using the middleware layer, OPENTRACING_TRACE_ALL defaults to True.
  • When no opentracing.Tracer is provided, DjangoTracing will rely on the global tracer.

Further Information

If you’re interested in learning more about the OpenTracing standard, please visit opentracing.io or join the mailing list. If you would like to implement OpenTracing in your project and need help, feel free to send us a note at [email protected].

More Repositories

1

opentracing-specification-zh

OpenTracing标准(中文版) `zh` (Chinese) translation of the opentracing/specification
929
star
2

nginx-opentracing

NGINX plugin for OpenTracing
C++
499
star
3

java-spring-cloud

Distributed tracing for Spring Boot, Cloud and other Spring projects
Java
386
star
4

csharp-netcore

OpenTracing instrumentation for .NET Core 3.1 & .NET 6+ apps
C#
261
star
5

java-spring-jaeger

Java
243
star
6

go-stdlib

OpenTracing instrumentation for packages in the Go stdlib
Go
217
star
7

java-specialagent

Automatic instrumentation for 3rd-party libraries in Java applications with OpenTracing.
Java
185
star
8

python-flask

OpenTracing instrumentation for the Flask microframework
Python
135
star
9

java-kafka-client

OpenTracing Instrumentation for Apache Kafka Client
Java
120
star
10

java-spring-web

OpenTracing Spring Web instrumentation
Java
106
star
11

java-opentracing-walkthrough

A self-guided OpenTracing walkthrough / demo project
JavaScript
106
star
12

java-jdbc

OpenTracing Instrumentation for JDBC
Java
81
star
13

java-jfr-tracer

This is a delegating tracer to be used with OpenTracing. It records span information into the JFR, allowing very deep tracing.
Java
77
star
14

go-grpc

Package otgrpc provides OpenTracing support for any gRPC client or server.
Go
71
star
15

go-gin

OpenTracing middleware for gin-gonic
Go
64
star
16

python-grpc

Python
53
star
17

java-grpc

OpenTracing Instrumentation for gRPC
Java
52
star
18

csharp-grpc

OpenTracing Instrumentation for gRPC
C#
43
star
19

java-agent

Agent-based OpenTracing instrumentation in Java
Java
40
star
20

javascript-express

OpenTracing middleware for express
JavaScript
39
star
21

java-jaxrs

OpenTracing Java JAX-RS instrumentation
Java
37
star
22

java-concurrent

OpenTracing-aware helpers related to java.util.concurrent
Java
36
star
23

meta

A meta-repository for OpenTracing contributions
34
star
24

java-redis-client

OpenTracing Instrumentation for Redis Client
Java
33
star
25

go-zap

Integration with go.uber.org/zap
Go
33
star
26

java-metrics

Java
31
star
27

go-amqp

AMQP instrumentation in Go
Go
29
star
28

scala-concurrent

OpenTracing instrumentation for scala.concurrent package
Scala
24
star
29

opentracing-erlang

Open Tracing Toolkit for ERlang
Erlang
24
star
30

java-web-servlet-filter

OpenTracing Java Web Servlet Filter Instrumentation
Java
23
star
31

java-xray-tracer

Java OpenTracing implementation backed by AWS X-Ray
Java
23
star
32

java-okhttp

OpenTracing Okhttp client instrumentation
Java
23
star
33

java-vertx-web

OpenTracing instrumentation for Vert.x web package
Java
21
star
34

python-redis

OpenTracing instrumentation for the Redis client.
Python
20
star
35

ruby-rack-tracer

Ruby
20
star
36

java-span-reporter

A Tracer implementation that writes all instrumented data to a conventional Logger
Java
20
star
37

goredis

a middleware for go-redis/redis to use opentracing
Go
18
star
38

java-spring-rabbitmq

OpenTracing RabbitMQ instrumentation
Java
18
star
39

java-spring-zipkin

Java
16
star
40

python-sqlalchemy

OpenTracing instrumentation for SQLAlchemy
Python
16
star
41

scala-akka

OpenTracing instrumentation for Scala Akka
Scala
16
star
42

java-dropwizard

(deprecated) OpenTracing instrumentation for the Dropwizard framework
Java
15
star
43

java-aws-sdk

OpenTracing instrumentation for AWS SDK
Java
15
star
44

java-specialagent-demo

A SpecialAgent Demo
Java
13
star
45

java-mongo-driver

OpenTracing Instrumentation for Mongo Driver
Java
12
star
46

java-reactor

OpenTracing instrumentation for Reactor
Java
12
star
47

javascript-tracedpromise

JavaScript
12
star
48

python-elasticsearch

OpenTracing instrumentation for the the Python's Elasticsearch clients
Python
11
star
49

java-apache-httpclient

OpenTracing Apache HttpClient instrumentation
Java
11
star
50

python-requests

OpenTracing instrumentation for Requests
Python
10
star
51

echo

a middleware for the echov4 web framework to use opentracing
Go
10
star
52

go-aws-sdk

OpenTracing support for AWS SDK in Go
Go
10
star
53

java-thrift

OpenTracing instrumentation for Apache Thrift
Java
10
star
54

java-rabbitmq-client

OpenTracing Instrumentation for RabbitMQ Client
Java
9
star
55

python-tornado

OpenTracing instrumentation for Tornado
Python
9
star
56

java-rxjava

OpenTracing Instrumentation for RxJava
Java
9
star
57

examples

Examples (some trivial) for opentracing.io
Go
9
star
58

java-elasticsearch-client

OpenTracing Instrumentation for Elasticsearch Client
Java
8
star
59

go-observer

an Observer API for OpenTracing-Go Tracers
Go
8
star
60

java-examples

tested examples of common instrumentation patterns
Java
7
star
61

ruby-faraday-tracer

Ruby
7
star
62

java-tracerresolver

Resolver API for OpenTracing Tracer implementations.
Java
6
star
63

java-akka

Java
6
star
64

go-gorilla

OpenTracing instrumentation for Gorilla framework (github.com/gorilla)
Go
6
star
65

java-spanmanager

Current span management for Java
Java
6
star
66

java-jms

OpenTracing Instrumentation for JMS API
Java
5
star
67

csharp-decorators

C#
5
star
68

perfevents

Perf metrics library for go and java applications
Go
5
star
69

beego

a middleware for the beego web framework to use opentracing
Go
5
star
70

java-hprose

OpenTracing instrumentation for the Hprose Remote Object Service Engine
Java
4
star
71

python-pyramid

OpenTracing instrumentation for the Pyramid framework
Python
4
star
72

java-cassandra-driver

OpenTracing instrumentation for Cassandra Driver
Java
4
star
73

java-globaltracer

(deprecated) Global OpenTracing Tracer resolution for Java
Java
4
star
74

java-asynchttpclient

OpenTracing Instrumentation for https://github.com/AsyncHttpClient/async-http-client
Java
4
star
75

cpp-grpc

OpenTracing Instrumentation for gRPC
4
star
76

python-cassandra

OpenTracing instrumentation for cassandra-driver
Python
3
star
77

java-p6spy

OpenTracing Instrumentation for P6Spy
Java
3
star
78

java-redisson

OpenTracing Instrumentation for Redisson
Java
3
star
79

java-spring-messaging

OpenTracing Spring Messaging instrumentation
Java
3
star
80

java-jdbi

OpenTracing instrumentation for the JDBI database framework
Java
3
star
81

java-benchmarks

Set of benchmarks to assess the performance of different OpenTracing components and/or libraries
Java
3
star
82

python-examples

tester examples of common instrumentation patterns
Python
3
star
83

java-spring-tracer-configuration

Java
2
star
84

python-pymongo

OpenTracing instrumentation for PyMongo
Python
2
star
85

java-cdi

Java
2
star
86

go-restful

OpenTracing instrumentation for the go-restful framework
Go
2
star
87

java-neo4j-driver

OpenTracing instrumentation for Neo4j Driver
Java
2
star
88

java-ejb

Java
2
star
89

java-solr-client

OpenTracing Instrumentation for Solr Client
Java
2
star
90

python-gevent

OpenTracing instrumentation for gevent
Python
2
star
91

java-grizzly-http-server

OpenTracing instrumentation for Grizzly HttpServer
Java
1
star
92

ruby-redis-instrumentation

Ruby
1
star
93

java-grizzly-ahc

OpenTracing instrumentation for Grizzly AsyncHttpClient
Java
1
star
94

java-memcached-client

OpenTracing Instrumentation for Memcached Client
Java
1
star
95

ruby-mongodb-instrumentation

Ruby
1
star
96

java-opentelemetry-bridge

OpenTracing-OpenTelemetry Tracer Bridge
Java
1
star
97

java-common

Common utilities for OpenTracing Instrumentation Plugins.
Java
1
star
98

java-hazelcast

OpenTracing Instrumentation for Hazelcast
Java
1
star
99

java-api-extensions

This repository contains API extensions for use with the core Tracer and Span APIs.
Java
1
star
100

java-opentracing-jaeger-bundle

Java
1
star