Python - ClickHouse Documentation

ClickStack utilise le standard OpenTelemetry pour collecter les données de télémétrie (logs et traces). Les traces sont générées automatiquement grâce à l’instrumentation automatique, l’instrumentation manuelle n’est donc pas nécessaire pour bénéficier du tracing. Ce guide couvre :

Logs
Metrics
Traces

Prise en main

Installez le paquet d’instrumentation OpenTelemetry de ClickStack

Utilisez la commande suivante pour installer le paquet OpenTelemetry de ClickStack.

pip install hyperdx-opentelemetry

Installez les bibliothèques d’instrumentation automatique OpenTelemetry pour les paquets utilisés par votre application Python. Nous vous recommandons d’utiliser l’outil opentelemetry-bootstrap, fourni avec le SDK OpenTelemetry pour Python, pour analyser les paquets de votre application et générer la liste des bibliothèques disponibles.

opentelemetry-bootstrap -a install

Configurer les variables d’environnement

Ensuite, vous devrez configurer les variables d’environnement suivantes dans votre shell afin d’acheminer la télémétrie vers ClickStack via le collector OpenTelemetry :

Managed ClickStack
ClickStack Open Source

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

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 d’environnement OTEL_SERVICE_NAME sert à identifier votre service dans l’application HyperDX ; vous pouvez lui donner le nom de votre choix.

Lancer l’application avec l’agent Python OpenTelemetry

Vous pouvez maintenant lancer l’application avec l’agent Python OpenTelemetry (opentelemetry-instrument).

opentelemetry-instrument python app.py

Si vous utilisez `Gunicorn`, `uWSGI` ou `uvicorn`

Dans ce cas, l’agent OpenTelemetry Python nécessite quelques modifications supplémentaires pour fonctionner. Pour configurer OpenTelemetry pour des serveurs d’applications utilisant le mode de serveur web pre-fork, veillez à appeler la méthode configure_opentelemetry dans le hook post-fork.

Gunicorn
uWSGI
uvicorn

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

from hyperdx.opentelemetry import configure_opentelemetry
from uwsgidecorators import postfork

@postfork
def init_tracing():
    configure_opentelemetry()

OpenTelemetry ne fonctionne actuellement pas avec uvicorn lorsqu’il est exécuté avec le flag --reload ou avec plusieurs workers (--workers). Nous recommandons de désactiver ces flags pendant les tests ou d’utiliser Gunicorn.

Configuration avancée

Capture réseau

En activant les fonctionnalités de capture réseau, les développeurs peuvent déboguer efficacement les en-têtes des requêtes HTTP et le contenu du corps. Pour cela, il suffit de définir le flag HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE sur 1.

export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1

Dépannage

Les logs n’apparaissent pas à cause du niveau de log

Par défaut, le handler de logging OpenTelemetry utilise le niveau logging.NOTSET, qui correspond au niveau WARNING. Vous pouvez spécifier le niveau de logging lors de la création d’un logger :

import logging

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

Exportation vers la console

Le SDK Python OpenTelemetry affiche généralement les erreurs dans la console lorsqu’elles se produisent. Cependant, si vous ne rencontrez aucune erreur mais constatez que vos données n’apparaissent pas dans HyperDX comme prévu, vous pouvez activer le mode de débogage. Lorsque le mode de débogage est activé, toutes les données de télémétrie sont affichées dans la console, ce qui vous permet de vérifier si votre application est correctement instrumentée avec les données attendues.

export DEBUG=true

Pour en savoir plus sur l’instrumentation Python d’OpenTelemetry, consultez : https://opentelemetry.io/docs/instrumentation/python/manual/

​Prise en main

​Installez le paquet d’instrumentation OpenTelemetry de ClickStack

​Configurer les variables d’environnement

​Lancer l’application avec l’agent Python OpenTelemetry

​Si vous utilisez Gunicorn, uWSGI ou uvicorn

​Configuration avancée

​Capture réseau

​Dépannage

​Les logs n’apparaissent pas à cause du niveau de log

​Exportation vers la console