> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Python pour ClickStack - La stack d’observabilité ClickHouse

# Python

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>Ce guide intègre :</span>
      {supported.includes("logs") && <span style={pillStyle}>Logs</span>}
      {supported.includes("metrics") && <span style={pillStyle}>Métriques</span>}
      {supported.includes("traces") && <span style={pillStyle}>Traces</span>}
    </div>;
};

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.

<ClickStackIntegrates signals={['logs', 'metrics', 'traces']} />

<h2 id="getting-started">
  Prise en main
</h2>

<h3 id="install-clickstack-otel-instrumentation-package">
  Installez le paquet d’instrumentation OpenTelemetry de ClickStack
</h3>

Utilisez la commande suivante pour installer le [paquet OpenTelemetry de ClickStack](https://pypi.org/project/hyperdx-opentelemetry/).

```shell theme={null}
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.

```shell theme={null}
opentelemetry-bootstrap -a install
```

<h3 id="configure-environment-variables">
  Configurer les variables d'environnement
</h3>

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 :

<Tabs>
  <Tab title="Managed ClickStack">
    ```shell theme={null}
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> 
    ```
  </Tab>

  <Tab title="ClickStack Open Source">
    ```shell theme={null}
    export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> 
    ```
  </Tab>
</Tabs>

*La variable d'environnement `OTEL_SERVICE_NAME` sert à identifier votre service dans l'application HyperDX ; vous pouvez lui donner le nom de votre choix.*

<h3 id="run-the-application-with-otel-python-agent">
  Lancer l'application avec l'agent Python OpenTelemetry
</h3>

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

```shell theme={null}
opentelemetry-instrument python app.py
```

<h4 id="using-uvicorn-gunicorn-uwsgi">
  Si vous utilisez `Gunicorn`, `uWSGI` ou `uvicorn`
</h4>

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.

<Tabs>
  <Tab title="Gunicorn">
    ```python theme={null}
    from hyperdx.opentelemetry import configure_opentelemetry

    def post_fork(server, worker):
        configure_opentelemetry()
    ```
  </Tab>

  <Tab title="uWSGI">
    ```python theme={null}
    from hyperdx.opentelemetry import configure_opentelemetry
    from uwsgidecorators import postfork

    @postfork
    def init_tracing():
        configure_opentelemetry()
    ```
  </Tab>

  <Tab title="uvicorn">
    OpenTelemetry [ne fonctionne actuellement pas](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/385) 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.
  </Tab>
</Tabs>

<h2 id="advanced-configuration">
  Configuration avancée
</h2>

<h4 id="network-capture">
  Capture réseau
</h4>

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.

```shell theme={null}
export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1
```

<h2 id="troubleshooting">
  Dépannage
</h2>

<h3 id="logs-not-appearing-due-to-log-level">
  Les logs n’apparaissent pas à cause du niveau de log
</h3>

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 :

```python theme={null}
import logging

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

<h3 id="exporting-to-the-console">
  Exportation vers la console
</h3>

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.

```shell theme={null}
export DEBUG=true
```

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