Uptrace for Python¶
Installation¶
pip install uptrace
Introduction¶
uptrace-python is the official Uptrace client for Python that sends your traces/spans to Uptrace.
To learn about tracing, please see Introduction to distributed tracing.
Configuring Uptrace client¶
You configure Uptrace client using a DSN (Data Source Name, e.g. https://<token>@api.uptrace.dev/<project_id>
) from the project settings page. Add following code to the app main file (manage.py for Django):
import uptrace
# Set dsn or UPTRACE_DSN env var.
upclient = uptrace.Client(dsn="")
tracer = upclient.get_tracer(__name__)
The following example shows how to create a tracer, start spans and add events:
import uptrace
# Set dsn or UPTRACE_DSN env var.
upclient = uptrace.Client(dsn="")
upclient.report_exception(ValueError("Hello from uptrace-python"))
tracer = upclient.get_tracer(__name__)
with tracer.start_as_current_span("main span"):
with tracer.start_as_current_span("child1") as span:
span.set_attribute("key1", "value1")
span.add_event("event-name", {"foo": "bar"})
with tracer.start_as_current_span("child2") as span:
span.set_attribute("key2", "value2")
span.add_event("event-name", {"foo": "baz"})
# Flush and close the client.
upclient.close()
Instrumenting your code¶
To create a tracer:
# Create a named tracer using module name as an identifier.
tracer = upclient.get_tracer(__name__, __version__)
To create a span and activate it in the current context:
with tracer.start_as_current_span("operation-name") as span:
do_some_work()
Or you can use start_span
:
# Create a span.
span = tracer.start_span(name)
# Activate the span in the current context.
with tracer.use_span(span, end_on_exit=True):
do_some_work()
To get the active span from the tracer context:
span = upclient.get_current_span()
Or using OpenTelemetry API:
from opentelemetry import trace
span = trace.get_current_span()
Once you have a span you can start adding attributes:
span.set_attribute("enduser.id", "123")
span.set_attribute("enduser.role", "admin")
And more complex events:
span.add_event("log", {
"log.severity": "error",
"log.message": "User not found",
"enduser.id": "123",
})
Instrumenting Django¶
Install Django instrumentation extension:
pip install opentelemetry-instrumentation-django
Edit manage.py
:
from opentelemetry.instrumentation.django import DjangoInstrumentor
if __name__ == "__main__":
# Make sure sure that settings module is defined. It is used by DjangoInstrumentor.
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "app_name.settings")
# Instrument Django by adding middleware etc.
DjangoInstrumentor().instrument()
...
Run the server:
# Enable instrumentation.
export OTEL_DJANGO_INSTRUMENT=True
./manage.py runserver
You can also check already instrumented django-realworld-example-app.
Instrumenting PostgreSQL psycopg2¶
Install psycopg instrumentation extension:
pip install opentelemetry-instrumentation-psycopg2
Update your main file (manage.py for Django):
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
if __name__ == "__main__":
Psycopg2Instrumentor().instrument()
...
Instrumenting MySQL¶
Using pymysql¶
pymysql
is a Python3 compatible replacement for mysql-python
.
pip install PyMySQL
To use it with libraries that expect mysql-python
, add the following to your main file (manage.py for Django):
import pymysql
pymysql.install_as_MySQLdb()
Install opentelemetry-instrumentation-pymysql
that instruments mysql-connector-python
:
pip install opentelemetry-instrumentation-pymysql
Update your main file (manage.py for Django):
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
if __name__ == "__main__":
PyMySQLInstrumentor().instrument()
...
Using mysql-connector-python¶
Install opentelemetry-instrumentation-mysql
that instruments mysql-connector-python
:
pip install mysql-connector-python
pip install opentelemetry-instrumentation-mysql
Update your main file (manage.py for Django):
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
if __name__ == "__main__":
MySQLInstrumentor().instrument()
...