Si no has leído las instrucciones de configuración de la instrumentación automática, empieza por las Instrucciones de configuración de Python.

Si no utilizas la instrumentación de biblioteca compatible (consulta Compatibilidad de bibliotecas), puede que desees instrumentar manualmente tu código.

También es posible que desees ampliar la funcionalidad de la biblioteca ddtrace u obtener un control más preciso sobre la instrumentación de tu aplicación. La biblioteca proporciona varias técnicas para conseguirlo.

Creación de tramos

La biblioteca ddtrace crea tramos automáticamente con ddtrace-run para muchas bibliotecas y marcos. Sin embargo, es posible que desees obtener visibilidad de tu propio código y esto se logra utilizando tramos.

Dentro de tu solicitud web (por ejemplo, make_sandwich_request), puedes realizar varias operaciones, como get_ingredients() y assemble_sandwich(), que son útiles para hacer mediciones.

def make_sandwich_request(request):
    ingredients = get_ingredients()
    sandwich = assemble_sandwich(ingredients)

  from ddtrace import tracer

  @tracer.wrap(service="my-sandwich-making-svc", resource="resource_name")
  def get_ingredients():
      # go to the pantry
      # go to the fridge
      # maybe go to the store
      return

  # You can provide more information to customize the span
  @tracer.wrap("assemble_sandwich", service="my-sandwich-making-svc", resource="resource_name")
  def assemble_sandwich(ingredients):
      return

from ddtrace import tracer

def make_sandwich_request(request):
    # Capture both operations in a span
    with tracer.trace("sandwich.make"):
        ingredients = get_ingredients()
        sandwich = assemble_sandwich(ingredients)

def make_sandwich_request(request):
    # Capture both operations in a span
    with tracer.trace("sandwich.create", resource="resource_name") as outer_span:

        with tracer.trace("get_ingredients", resource="resource_name") as span:
            ingredients = get_ingredients()

        with tracer.trace("assemble_sandwich", resource="resource_name") as span:
            sandwich = assemble_sandwich(ingredients)

def make_sandwich_request(request):
    span = tracer.trace("sandwich.create", resource="resource_name")
    ingredients = get_ingredients()
    sandwich = assemble_sandwich(ingredients)
    span.finish()  # remember to finish the span

Acceso a tramos activos

La instrumentación incorporada y tu propia instrumentación personalizada crean tramos alrededor de operaciones significativas. Puedes acceder al tramo activo para incluir datos significativos.

from ddtrace import tracer

def make_sandwich_request(request):
    # Capture both operations in a span
    with tracer.trace("sandwich.make") as my_span:
        ingredients = get_ingredients()
        sandwich = assemble_sandwich(ingredients)

def get_ingredients():
    # Get the active span
    span = tracer.current_span()
    # this span is my_span from make_sandwich_request above

def assemble_sandwich(ingredients):
    with tracer.trace("another.operation") as another_span:
        # Get the active root span
        span = tracer.current_root_span()
        # this span is my_span from make_sandwich_request above

Añadir etiquetas

from ddtrace import tracer

def make_sandwich_request(request):
    with tracer.trace("sandwich.make") as span:
        ingredients = get_ingredients()
        span.set_tag("num_ingredients", len(ingredients))

from ddtrace import tracer
from myapp import __version__

# This will be applied to every span
tracer.set_tags({"version": __version__, "<TAG_KEY_2>": "<TAG_VALUE_2>"})

from ddtrace import tracer

with tracer.trace("throws.an.error") as span:
    raise Exception("Oops!")

# `span` will be flagged as erroneous and have
# the stack trace and exception message attached as tags

from ddtrace import tracer

span = tracer.trace("operation")
span.error = 1
span.finish()

import os
from ddtrace import tracer

try:
    raise TypeError
except TypeError as e:
    root_span = tracer.current_root_span()
    (exc_type, exc_val, exc_tb) = sys.exc_info()
    # this sets the error type, marks the span as an error, and adds the traceback
    root_span.set_exc_info(exc_type, exc_val, exc_tb)

Propagación de contexto con extracción e inyección de encabezados

Puedes configurar la propagación de contexto para trazas distribuidas al inyectar y extraer encabezados. Consulta Propagación de contexto de traza para obtener información.

Baggage

Manipulación de Baggage en un span (tramo):

from ddtrace import tracer

# Start a new span and set baggage
with tracer.trace("example") as span:
    # set_baggage_item
    span.context.set_baggage_item("key1", "value1")
    span.context.set_baggage_item("key2", "value2")

    # get_all_baggage_items
    all_baggage = span.context.get_all_baggage_items()
    print(all_baggage) # {'key1': 'value1', 'key2': 'value2'}

    # remove_baggage_item
    span.context.remove_baggage_item("key1")
    print(span.context.get_all_baggage_items()) # {'key2': 'value2'}

    # get_baggage_item
    print(span.context.get_baggage_item("key1")) # None
    print(span.context.get_baggage_item("key2")) # value2

    # remove_all_baggage_items
    span.context.remove_all_baggage_items()
    print(span.context.get_all_baggage_items()) # {}

Para ver un ejemplo en acción, consulta flask-baggage en trace-examples.

ddtrace-api

El paquete ddtrace-api proporciona una API pública estable para la instrumentación personalizada de Python de Datadog APM. Este paquete implementa sólo la interfaz de la API, no la funcionalidad subyacente que crea y envía tramos a Datadog.

Esta separación entre interfaz (ddtrace-api) e implementación (ddtrace) ofrece varias ventajas:

• Puedes confiar en una API que cambia con menos frecuencia y de forma más predecible para tu instrumentación personalizada
• Si sólo utilizas la instrumentación automática, puedes ignorar por completo los cambios de la API
• Si implementas tanto el paso único como la instrumentación personalizada, evitarás depender de múltiples copias del paquete ddtrace

Para utilizar ddtrace-api:

1. Instala las bibliotecas ddtrace y ddtrace-api:

   pip install 'ddtrace>=3.1' ddtrace-api
   

2. Instrumenta tu aplicación de Python mediante el uso de ddtrace-run anteponiendo tu comando de punto de entrada de Python:

   ddtrace-run python app.py
   

3. Una vez configurado esto, puedes escribir instrumentación personalizada exactamente igual que en los ejemplos de las secciones anteriores, pero importando desde ddtrace_api en lugar de ddtrace.

   Por ejemplo:

   from ddtrace_api import tracer
   
   @tracer.wrap(service="my-sandwich-making-svc", resource="resource_name")
   def get_ingredients():
       # go to the pantry
       # go to the fridge
       # maybe go to the store
       return
   

Consulte la definición de la API del paquete para conocer la lista completa de las llamadas a la API compatibles.

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Conectar tus logs y trazasDOCUMENTACIÓN Explora tus servicios, recursos y trazasDOCUMENTACIÓN