Python

Python para ClickStack - la pila de observabilidad de ClickHouse

ClickStack usa el estándar OpenTelemetry para recopilar datos de telemetría (logs y trazas). Las trazas se generan automáticamente con instrumentación automática, por lo que no se requiere instrumentación manual para empezar a aprovechar el tracing.

Esta guía integra:

• Logs
• Métricas
• Trazas

​

Primeros pasos

​

Instala el paquete de instrumentación de OpenTelemetry de ClickStack

Usa el siguiente comando para instalar el paquete de OpenTelemetry de ClickStack.

pip install hyperdx-opentelemetry

Instala las bibliotecas de instrumentación automática de OpenTelemetry para los paquetes que utiliza tu aplicación en Python. Recomendamos que uses la herramienta opentelemetry-bootstrap, incluida en el SDK de OpenTelemetry para Python, para analizar los paquetes de tu aplicación y generar la lista de bibliotecas disponibles.

opentelemetry-bootstrap -a install

​

Configura las variables de entorno

A continuación, tendrás que configurar las siguientes variables de entorno en tu shell para enviar telemetría a ClickStack a través del collector de OpenTelemetry:

Managed ClickStack

OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

ClickStack Open Source

export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

La variable de entorno OTEL_SERVICE_NAME se utiliza para identificar tu servicio en la aplicación HyperDX; puede ser cualquier nombre que quieras.

​

Ejecuta la aplicación con el agente de Python de OpenTelemetry

Ahora puedes ejecutar la aplicación con el agente de Python de OpenTelemetry (opentelemetry-instrument).

opentelemetry-instrument python app.py

​

Si usas Gunicorn, uWSGI o uvicorn

En este caso, el agente de Python de OpenTelemetry requerirá cambios adicionales para funcionar.

Para configurar OpenTelemetry en servidores de aplicaciones que usan el modo de servidor web pre-fork, asegúrate de llamar al método configure_opentelemetry dentro del hook posterior al fork.

Gunicorn

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

uWSGI

from hyperdx.opentelemetry import configure_opentelemetry
from uwsgidecorators import postfork

@postfork
def init_tracing():
    configure_opentelemetry()

uvicorn

Actualmente, OpenTelemetry no funciona con uvicorn cuando se ejecuta con la opción --reload o con varios workers (--workers). Recomendamos desactivar esas opciones durante las pruebas o usar Gunicorn.

​

Configuración avanzada

​

Captura de red

Al habilitar las funciones de captura de red, los desarrolladores pueden depurar eficazmente los encabezados de las solicitudes HTTP y las cargas útiles del cuerpo. Esto puede lograrse simplemente estableciendo la bandera HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE en 1.

export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1

​

Solución de problemas

​

Los logs no aparecen debido al nivel de logging

De forma predeterminada, el handler de logging de OpenTelemetry usa el nivel logging.NOTSET, que por defecto equivale al nivel WARNING. Puede especificar el nivel de logging al crear un logger:

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

​

Exportar a la consola

El SDK de Python de OpenTelemetry suele mostrar errores en la consola cuando se producen. Sin embargo, si no aparece ningún error, pero observas que tus datos no se muestran en HyperDX como deberían, puedes habilitar el modo de depuración. Cuando el modo de depuración está activado, todos los datos de telemetría se imprimirán en la consola, lo que te permitirá comprobar si tu aplicación está correctamente instrumentada con los datos esperados.

export DEBUG=true

Obtén más información sobre la instrumentación de OpenTelemetry para Python aquí: https://opentelemetry.io/docs/instrumentation/python/manual/