Mise en route

Architecture

Le schéma illustre la manière dont l' Instana e surveille les applications d'IA générative.

Instana prend en charge deux modes d'envoi des traces, des journaux et des métriques depuis vos applications d'IA.

Mode de l'agent

En mode agent, OpenLLMetry envoie d'abord les traces, les journaux et les métriques à l'agent Instana, qui les transmet ensuite au backend Instana via l'acceptateur d'agent. Ce mode est idéal lorsque vous avez déployé l'agent « Instana » et que vous souhaitez corréler les données de télémétrie de l'IA avec les métriques de l'infrastructure.

Mode sans agent

En mode sans agent, OpenLLMetry envoie les traces, les journaux et les métriques directement au backend Instana, sans passer par l'agent Instana. Les données de télémétrie sont importées via le module d'acceptation « OTLP » dans le backend « Instana ». Ce mode est idéal pour les déploiements natifs du cloud, les environnements sans serveur ou lorsque vous souhaitez une configuration plus simple sans avoir à déployer d'agents.

Prérequis

Avant de configurer vos applications d'IA pour la surveillance, assurez-vous que les conditions préalables suivantes sont remplies.

• Python 3.10 ou une version ultérieure
• Un compte Instana disposant des droits d'accès appropriés
• En mode agent, l'agent d' Instana est installé et en cours d'exécution
• Pour le mode sans agent, le backend Instana, le point de terminaison OTLP et la clé API
• API clé pour votre fournisseur de LLM ( OpenAI,, Anthropic, etc.)

Configuration d' Instana pour l'observabilité de l'IA

Pour configurer l'observabilité de l'IA dans l' Instana, procédez comme suit :

1. Configurez votre environnement Python.
   1. Vérifiez que la version Python 3.10 ou une version ultérieure est installée :

      python3 -V

   2. Facultatif : créez un environnement virtuel pour isoler vos dépendances.

      pip3 install virtualenv
      virtualenv genai-env
      source genai-env/bin/activate

2. Installez et configurez OpenLLMetry dans le code ou le service qui effectue des appels vers les modèles de langage grand format (LLM). Il peut s'agir de l'un des éléments suivants :

   • Le point d'entrée principal de votre application d'IA, par exemple, app.py,main.py.
   • Le serveur ou service backend d' API s qui traite les requêtes d'IA
   • Tout module d' Python s qui interagit directement avec des fournisseurs de modèles de langage de grande envergure (LLM) (tels que OpenAI,, Anthropic, watsonx, etc.
   Installez le SDK d' OpenLLMetry :

   pip3 install traceloop-sdk

   Remarque : ajoutez traceloop-sdk à votre requirements.txt fichier pour faciliter la gestion des dépendances dans votre projet.
3. Définissez les variables d'environnement suivantes, qui sont requises pour tous les modes de surveillance.

   OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai"
   TRACELOOP_LOGGING_ENABLED=true
   TRACELOOP_METRICS_ENABLED=true

   Configurez les variables spécifiques au mode en fonction de votre déploiement.

4. Effectuez l'une des étapes suivantes :
   • Mode agent : définissez ces variables d'environnement pour envoyer des données de télémétrie via l'agent Instana :

     TRACELOOP_BASE_URL=<instana-agent-host>:4317
     OTEL_EXPORTER_OTLP_INSECURE=true

     L'agent « Instana » enrichit automatiquement les données de télémétrie avec le contexte de l'infrastructure. Pour plus d'informations sur la configuration de l'agent « Instana », consultez la page Instana agent.

   • Mode sans agent : définissez ces variables d'environnement pour envoyer les données de télémétrie directement au backend Instana :

     TRACELOOP_BASE_URL=<instana-otlp-endpoint>:4317
     TRACELOOP_HEADERS="x-instana-key=<agent-key>,x-instana-host=<instana-host>"
     OTEL_EXPORTER_OTLP_INSECURE=false

     Recherchez les valeurs de configuration de votre fichier « Instana ». Pour déterminer les <instana-otlp-endpoint> valeurs de <agent-key> et.

     1. Connectez-vous à votre instance d' Instana.
     2. Dans le menu de navigation, cliquez sur « Agents et collecteurs ».
     3. Cliquez sur l'onglet « Collectors » de l' OpenTelemetry.
     4. Cliquez sur « Installer un collecteur ».
     5. Sélectionnez « Linux » - Installation automatique (commande en une ligne).
     6. À l'étape 2, vous verrez une commande similaire à celle de l'exemple suivant :

        curl -Lo setup.sh https://github.com/instana/instana-otel-collector/releases/latest/download/instana-collector-installer-latest.sh && chmod +x setup.sh && sudo ./setup.sh -a <agent-key> -e <instana-otlp-endpoint>:4317 -H <instana-otlp-endpoint>:4318
         

     7. <instana-otlp-endpoint> s'agit des points de terminaison indiqués précédemment :4317 (port gRPC ) et :4318 (port HTTP )
     8. <agent-key> est la clé qui apparaît après -a
     9. <instana-host> peut être n'importe quelle chaîne de caractères de votre choix

   Pour plus d'informations sur les points de terminaison du backend Instana OTLP pour différents environnements SaaS, consultez la page « Points de terminaison de l'acceptateur du backend Instana OTLP ».

5. Intégrez des outils à votre application. Ajoutez l'instrumentation d' OpenLLMetry s à votre application Python. Placez ce code au début du fichier principal de votre application (par exemple, app.py, main.py) ou dans le module qui initialise votre service d'IA :

   from traceloop.sdk import Traceloop
   
   # Initialize OpenLLMetry
   Traceloop.init(app_name="my_ai_app", disable_batch=True)
    

   Facultatif : pour les flux de travail complexes, vous pouvez les annoter afin d'en améliorer la visibilité :

   from traceloop.sdk.decorators import workflow
   
   @workflow(name="my_workflow")
   def my_ai_workflow():
       # Your AI logic here
       pass
    

   Remarque : si vous utilisez des frameworks tels que LangChain,, LangGraph, ou CrewAI,, aucune annotation supplémentaire n'est nécessaire. Pour plus d'informations sur les décorateurs, consultez la section « Annotations ».
6. Exécutez un exemple simple. L'exemple suivant utilise Claude d'Anthropic :

   1. Installez le SDK Anthropic :

      pip3 install anthropic
       

   2. Définissez votre clé « API » d'Anthropic en tant que variable d'environnement :

      ANTHROPIC_API_KEY=<your-anthropic-api-key>
       

      Pour créer une clé API, consultez la page Clés API Anthropic.

   3. Créez un fichier nommé hello_genai.py contenant le code suivant :

      import os
      import anthropic
      from traceloop.sdk import Traceloop
      from traceloop.sdk.decorators import workflow
      
      # Initialize OpenLLMetry
      Traceloop.init(app_name="hello_genai", disable_batch=True)
      
      # Create Anthropic client
      client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
      
      @workflow(name="simple_chat")
      def ask_question():
          message = client.messages.create(
              model="claude-3-sonnet-20240229",
              max_tokens=1024,
              messages=[
                  {"role": "user", "content": "What is observability?"}
              ]
          )
          print(message.content[0].text)
      
      # Run the workflow
      ask_question()
       

   4. Lancez l'application :

      python3 hello_genai.py
       

Vérifiez votre configuration

Une fois votre application lancée, vérifiez que les données sont bien transmises à Instana :

1. Dans l'interface utilisateur d' Instana, cliquez sur « Gen AI Observability ».
2. Les données de l'application s'affichent et comprennent les éléments suivants :
   • Appels et traces dans l' API LLM
   • Indicateurs d'utilisation des jetons
   • Temps d'attente des demandes
   • Coût
   • Taux d'erreur

Si vous rencontrez des difficultés lors de la configuration d' Instana pour l'observabilité de l'IA, consultez la section Dépannage pour résoudre des problèmes tels que les erreurs de connexion, les données manquantes et les problèmes de configuration.