Ruby Configuration : Configuration du gem

Activer ou désactiver globalement

Le gem complet peut être désactivé lors de l'exécution en définissant une variable d'environnement pour votre application :

export INSTANA_DISABLE=true

Les autres options d'activation ou de désactivation globales sont les suivantes :

Instana.config[:tracing][:enabled] # default true

Si vous souhaitez désactiver l'instrumentation intégrée tout en autorisant l'instrumentation personnalisée, définissez la variable d'environnement suivante pour votre application :

export INSTANA_DISABLE_AUTO_INSTR=true

AutoProfile™

Modifier en ligne

AutoProfile génère et signale les profils de processus à Instana automatiquement et en continu. Pour en savoir plus sur les profils, consultez la section « Profils d'analyse ».

Pour plus d'informations sur son activation, consultez la section « Configuration du profilage ».

Communication avec l'agent hôte

Modifier en ligne

Le capteur tente de communiquer avec l'agent Instana via l' 127.0.0.1 IP et, à défaut, via la passerelle par défaut de l'hôte dans les environnements conteneurisés. Si l'agent n'est disponible à aucun de ces emplacements, vous pouvez utiliser des variables d'environnement pour configurer l'emplacement où rechercher l'agent hôte d' Instana.

Les variables d'environnement doivent être définies dans l'environnement du processus en cours d'exécution.

export INSTANA_AGENT_HOST = '127.0.0.1'
export INSTANA_AGENT_PORT = '42699'

Voir également la section « Référence générale : Variables d'environnement pour les capteurs de langue »

Kubernetes et Red Hat OpenShift

Modifier en ligne

Assurez-vous que vos applications instrumentées communiquent avec l'agent hôte d' Instana. Pour plus d'informations, consultez la section « Configurer l'accès réseau pour les applications surveillées ».

Activer ou désactiver des composants individuels

Modifier en ligne

Les différents composants peuvent être activés ou désactivés via une configuration locale.

Pour désactiver un composant unique dans le gem, vous pouvez le faire avec le code suivant dans un initialiseur de votre application :

::Instana.config[:metrics][:gc][:enabled] = false

Les composantes métriques actuelles sont :gc, :memory, et :thread.

L'instrumentation peut être désactivée comme suit :

::Instana.config[:excon][:enabled] = false
::Instana.config[:rack][:enabled] = false

Pour obtenir la liste complète des instruments, consultez config.rb

Activer ou désactiver la collecte des traces de pile

Modifier en ligne

Étant donné que les traces d'appel sont coûteuses en termes de ressources dans l' Ruby, la collecte des traces d'appel est désactivée par défaut, mais peut être activée à l'aide du code suivant dans un initialiseur de votre application :

::Instana.config[:collect_backtraces] = true

Cette configuration permet ensuite à l' CodeView, depuis votre tableau de bord, d'obtenir des informations détaillées au niveau du code.

Configuration des traces de pile

Modifier en ligne

Par défaut, l'outil de traçage Instana Ruby enregistre les 30 dernières trames de trace de pile pour chaque intervalle EXIT présentant une erreur. Vous pouvez modifier cette valeur selon vos besoins.

Remarque : les traces de pile ne sont pas collectées pour ENTRY les intervalles, car elles ne contiennent généralement aucune information utile au niveau de l'application.

Vous pouvez configurer les aspects suivants de la capture de la trace de pile :

Attribut de trace de pile	Description	Valeur prise en charge	Valeur par défaut
Longueur de la trace de pile	Nombre de trames de trace de pile à capturer	1 à 40	30
Niveau de trace de pile	Comment les traces de pile sont-elles enregistrées?	- `all`: Récupère la trace de pile pour tous les segments de sortie - `error`: Récupère la trace de pile uniquement pour les segments présentant une erreur - `none`: Ne récupère pas la trace de pile	`error`

Remarque : en cas d'erreurs, la trace complète de la pile est enregistrée, quelle que soit sa longueur, afin de garantir que la cause première soit entièrement identifiée.

Vous pouvez configurer la capture de la trace de pile en utilisant l'une des options suivantes :

Pour configurer la capture de traces de pile spécifiques à une technologie via l'agent et les méthodes de configuration d' YAML, consultez la section « Configuration spécifique à une technologie ».

Utilisation des variables d'environnement

Vous pouvez utiliser les variables d'environnement INSTANA_STACK_TRACEINSTANA_STACK_TRACE_LENGTH et pour filtrer les traces de pile, comme le montre l'exemple suivant :

Enregistrer les traces de pile uniquement pour les segments présentant des erreurs : utilisez ce paramètre pour enregistrer les traces de pile uniquement lorsqu'une erreur se produit.
```
# Captures stack trace only for erroneous spans.
INSTANA_STACK_TRACE=error
```
Désactiver la collecte des traces de pile : utilisez ce paramètre pour désactiver complètement la collecte des traces de pile.
```
# Disable collection of stack trace.
INSTANA_STACK_TRACE=none
```
Enregistrer les traces de pile pour tous les segments : utilisez ce paramètre pour collecter les traces de pile de tous les segments.
```
# Captures stack trace for all spans.
INSTANA_STACK_TRACE=all
```
Limiter le nombre d'étapes de la trace de pile : utilisez ce paramètre pour limiter le nombre d'étapes de la trace de pile capturées.
```
# Limits capture of stack trace frames to 25.
INSTANA_STACK_TRACE_LENGTH=25
 
```

Utilisation de la configuration d' YAML

Définissez la variable INSTANA_CONFIG_PATH d'environnement sur un fichier de configuration local d' YAML, en utilisant la spécification suivante. Vous pouvez créer un nouveau fichier de configuration local YAML ou en utiliser un existant.

tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>

Utilisation de la configuration de l'agent

Pour configurer la capture de la trace de pile à l'aide de la méthode de configuration de l'agent, définissez les paramètres dans la com.instana.tracing.global section de votre fichier de configuration d'agent (*instanaAgentDir*/etc/instana/configuration.yaml), comme le montre l'exemple suivant :

com.instana.tracing:
  global:
    stack-trace-length: 15
    stack-trace: 'error'

Configuration spécifique à la technologie

Le Tracer de l' Instana Ruby propose une configuration spécifique à la technologie qui prévaut sur les configurations globales. Vous pouvez affiner la configuration et contrôler la capture de la trace de pile à l'aide des paramètres suivants :

com.instana.tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>
  <technology>:
    stack-trace: <string>
    stack-trace-length: <int>

Dans cette configuration, les valeurs suivantes sont prises en charge pour la <technology> clé :

action_controller
action_view
active_record
bunny
dalli
excon
grpc
graphql
nethttp
redis
resque-client
resque-worker
rest-client
sequel
sidekiq-client
sidekiq-worker

L'exemple suivant capture les traces de pile pour tous les segments et limite le nombre de trames à 25 dans le cadre d'une configuration globale; cependant, pour l'option « Redis », il ne capture la trace de pile complète que pour les segments présentant une erreur :

com.instana.tracing:
  global:
    stack-trace: all
    stack-trace-length: 25
  redis:
    stack-trace: error

Définition d'un nom de service personnalisé

Modifier en ligne

Vous pouvez définir un nom de service personnalisé pour votre application en définissant la variable d'environnement INSTANA_SERVICE_NAME :

export INSTANA_SERVICE_NAME=my-custom-service-name

Pour plus d'informations sur la configuration d'un service personnalisé, consultez la section « Définition du nom du service au niveau global ».

Définition du nom de processus

Modifier en ligne

Utilisez la variable d'environnement INSTANA_PROCESS_NAME pour définir un libellé personnalisé pour l'entité d'infrastructure qui représente le processus Ruby.

Bifurcation de serveurs Web et de systèmes de traitement des travaux

Modifier en ligne

Pour les bibliothèques logicielles telles que Puma, Resque ou d'autres qui créent des processus fils pour effectuer des tâches, vous devez ajouter une configuration afin d'indiquer à l'agent d' Instana ation qu'un processus fils a été créé.

Puma

Modifier en ligne

Pour le serveur Web Puma, ajoutez le contenu suivant à votre configuration puma.rb :

on_worker_boot do
  ::Instana.agent.after_fork if defined?(::Instana)
end

Unicorn

Modifier en ligne

Pour Unicorn en mode bifurcation (fork), ajoutez le bloc suivant à votre fichier unicorn.rb :

after_fork do |server, worker|
  ::Instana.agent.after_fork if defined?(::Instana)
end

Middleware Rack

Modifier en ligne

Ce module détecte et intègre automatiquement le middleware Rack « Instana » dans la pile de middleware lorsqu'un framework pris en charge est présent. Nous sommes en train d'ajouter la prise en charge d'autres infrastructures. Si vous utilisez un framework qui n'est pas encore instrumenté, vous pouvez intégrer le middleware Rack d' Instana s à l'aide de la configuration suivante :

require "instana/rack"
config.middleware.use ::Instana::Rack

... ou un appel de middleware spécifique adapté à votre infrastructure.

Gestion de l'unité d'exécution d'arrière-plan de l'agent

Modifier en ligne

Cet agent crée un thread d'arrière-plan léger chargé de collecter et de transmettre périodiquement des métriques et des traces. Par défaut, cela utilise un thread standard de type « Ruby ». Si vous souhaitez bénéficier d'un meilleur contrôle et éventuellement lancer l'agent chargé de la transmission des données manuellement dans un autre système de threads (tel que les threads basés sur des acteurs), vous pouvez le faire en utilisant la configuration suivante :

gem "instana", :require => "instana/setup"

Ensuite, dans le thread d'arrière-plan de votre choix, appelez :

::Instana.agent.start

Cet appel est en attente. Il lance une boucle de temporisateurs qui collecte et fait état des métriques et des données de trace à intervalles réguliers. Cet appel ne doit être effectué qu'à partir d'un thread d'arrière-plan déjà initialisé :

Thread.new do
  ::Instana.agent.start
end

Journalisation

Modifier en ligne

L'enregistreur « Instana » est un enregistreur standard de type « Ruby » qui consigne les messages de débogage, d'avertissement ou d'information et peut être configuré comme suit :

require "logger"
::Instana.logger.level = ::Logger::WARN

Le gem peut être configuré pour utiliser le consignateur de votre application à la place :

::Instana.logger = ::My.logger

Par défaut, le gem « Instana » hérite et utilise le logger « Ruby » de Rails lorsque Rails est utilisé.

Débogage et niveau de détail accru

Modifier en ligne

Vous pouvez définir la configuration de débogage du gem Instana Ruby.

Variable d"environnement

Modifier en ligne

En définissant cette option INSTANA_DEBUG sur une valeur différente de nil, vous activez des messages de journalisation supplémentaires, généralement utiles pour le développement et le dépannage.

Voir également la section « Référence générale : Variables d'environnement pour les capteurs de langue »

AWS Fargate

Modifier en ligne

Lorsqu'elle s'exécute au sein d'une fonction ` AWS Lambda `, la bibliothèque ` Ruby ` utilise les options de configuration standard.

AWS Lambda

Modifier en ligne

Lorsqu'elle s'exécute au sein d'une fonction ` AWS Lambda `, la bibliothèque ` Ruby ` utilise les options de configuration standard.

Filtrage par intervalle

Modifier en ligne

Vous pouvez utiliser cette fonctionnalité pour filtrer les traces ou les appels superflus afin de réduire le volume global de données ingérées. Par exemple, vous pouvez filtrer le traçage de méthodes spécifiques d' Redis, telles que redis.get.

Cette fonctionnalité est disponible uniquement pour Redis avec la gemme Instana Ruby version 2.1.0 ou supérieure. À l'heure actuelle, le gem « Ruby » ne prend en charge le filtrage que pour les opérations de type « Redis ».

Règles de filtrage

Modifier en ligne

Appliquez les règles suivantes pour filtrer les segments :

Lorsqu'un segment est filtré, tous les segments suivants en aval sont également filtrés (suppression).
Utilisez le caractère générique * pour filtrer toutes les méthodes de l' Redis.
Les noms des méthodes peuvent varier en fonction du langage de programmation et de la technologie utilisés. Consultez l'interface utilisateur d' Instana pour déterminer la méthode appropriée pour vos opérations d' Redis.

Remarque : la fonctionnalité de filtrage par intervalle ne fonctionne qu'avec les noms exacts des méthodes. Assurez-vous d'utiliser le nom de méthode correct à filtrer.

Configuration du filtrage par intervalle

Modifier en ligne

Vous pouvez configurer le filtrage des intervalles pour Redis en utilisant l'une des options suivantes :

Variables d'environnement
Fichier de configuration
Configuration de l'agent

Remarque : si plusieurs approches sont utilisées simultanément, le gem « Ruby » établit un ordre de priorité comme suit : variables d'environnement, fichier de configuration et configuration de l'agent.

Variables d'environnement pour le filtrage des balises `span`

Modifier en ligne

Vous pouvez configurer le filtrage des spans à l'aide des variables d'environnement suivantes :

INSTANA_CONFIG_PATH : Indiquez le chemin d'accès à un fichier de configuration d' YAML
INSTANA_TRACING_FILTER_<policy>_<name>_ATTRIBUTES=<rule> : Définir directement les règles de filtrage

Utilisation `INSTANA_CONFIG_PATH`

Modifier en ligne

Grâce à cette variable d'environnement, vous pouvez configurer le filtrage via un fichier d' YAML s externe :

INSTANA_CONFIG_PATH=/path/to/config.yaml

YAML configuration du filtrage par intervalle

Modifier en ligne

Le fichier de configuration d' YAML prend en charge deux formats :

Format 1 : Filtrage simple par « Redis »

tracing:
  filter:
      exclude:
        - name: "Redis Operations"
          attributes:
            - key: "type"
              values: ["redis"]

Cette configuration filtre toutes les balises Redis.

Format 2 : Filtrage avancé basé sur les attributs

tracing:
  filter:
    deactivate: false  # Optional, defaults to false
    exclude:
      - name: "Redis Operations"
        suppression: true  # Optional, defaults to true
        attributes:
          - key: "category"
            values: ["databases"]
          - key: "type"
            values: ["redis"]
            match_type: "strict"  # Optional, defaults to "strict"

Cette configuration filtre toutes les sections de l' Redis.

Pour le filtrage d' Redis s, key l'attribut peut prendre les valeurs suivantes :

category: Catégorie Technologie (bases de données)
type: Bibliothèque ( redis )
Redis - attributs spécifiques ( redis.command )

Cela match_type peut être :

strict: Correspondance exacte (par défaut)
startswith: La chaîne commence par la valeur
endswith: La chaîne se termine par la valeur
contains: La chaîne contient la valeur

Utilisation des variables d'environnement pour la configuration directe

Modifier en ligne

Vous pouvez définir des règles de filtrage directement à l'aide de variables d'environnement :

# Filter all Redis operations
INSTANA_TRACING_FILTER_EXCLUDE_REDIS_ATTRIBUTES="type;redis;strict"

# Filter specific Redis commands
INSTANA_TRACING_FILTER_EXCLUDE_REDIS_ATTRIBUTES="redis.command;get,set;strict"

Le format des règles est le suivant : key;values;match_type où :

key: L'attribut à vérifier
values: Liste de valeurs séparées par des virgules à faire correspondre
match_type: Stratégie de correspondance facultative (valeur par défaut : strict)

Plusieurs règles peuvent être combinées à l'aide du caractère « | » :

INSTANA_TRACING_FILTER_EXCLUDE_REDIS_ATTRIBUTES="type;redis;strict|redis.command;get,set;strict"

Configuration de l'agent pour le filtrage des segments

Modifier en ligne

Pour configurer le filtrage des segments à l'aide de la méthode de configuration de l'agent, ajoutez la filter configuration au fichier configuration.yaml de l'agent. Pour plus d'informations, consultez la section « Filtrage des intervalles ».

Exemples

Modifier en ligne

Exemple 1 : Filtrer toutes les opérations « Redis »

tracing:
  filter:
    exclude:
      - name: "Redis Operations"
        attributes:
          - key: "type"
            values: ["redis"]

Exemple 2 : Filtrer certaines commandes d' Redis

tracing:
  filter:
    exclude:
      - name: "Redis GET and SET"
        attributes:
          - key: "type"
            values: ["redis"]
          - key: "redis.command"
            values: ["get", "set"]

Exemple 3 : Filtrer les opérations d' Redis s à l'aide de la correspondance de motifs

tracing:
  filter:
    exclude:
      - name: "Redis GET operations"
        attributes:
          - key: "redis.command"
            values: ["get"]
            match_type: "startswith"

Cela filtrera les commandes d' Redis s qui commencent par get (par exemple, get, et set).

Configuration de la désactivation des segments

Modifier en ligne

Vous pouvez désactiver les segments en utilisant la fonctionnalité de filtrage des segments de l'outil Tracer de l' Instana Ruby.

Grâce à la fonctionnalité de désactivation des balises span, vous pouvez désactiver complètement la génération de balises span dans votre application. Cette fonctionnalité peut s'avérer utile dans les cas suivants :

Vous souhaitez réduire le nombre de segments générés par votre application.
Certaines de vos opérations ne sont pas concernées par la surveillance.
Vous souhaitez vous concentrer sur d'autres aspects des performances de votre application.

Catégories prises en charge

Modifier en ligne

Il existe plusieurs catégories d'opérations pouvant être filtrées.

Les catégories sont des ensembles de bibliothèques regroupées selon un type commun de technologie ou de protocole. Vous pouvez désactiver les intervalles pour les catégories suivantes :

logging
databases

Options de configuration

Modifier en ligne

Vous pouvez désactiver les balises `span` en utilisant l'une des options suivantes :

Option 1 : Utilisation de la configuration d' YAML

Modifier en ligne

Créez un fichier de configuration YAML et définissez la variable INSTANA_CONFIG_PATH d'environnement de manière à ce qu'elle pointe vers un paquet, comme indiqué dans l'exemple suivant :

tracing:
  disable:
    - redis: true

La disable clé peut contenir une liste de catégories ou de type noms. Un type nom désigne toute référence à un framework, une bibliothèque ou un outil d'instrumentation pris en charge par l'outil de traçage Instana Ruby.

Les configurations type individuelles prévalent sur les paramètres de category leur niveau supérieur, quel que soit l'ordre dans lequel elles sont définies. Cette approche permet un contrôle précis, grâce auquel certaines instrumentations spécifiques peuvent rester activées même lorsque leur catégorie générale est désactivée.

L'exemple de configuration suivant désactive toutes les étendues de base de données, à l'exception de celles destinées à Redis :

tracing:
  disable:
    - databases: true
    - redis: false

Option 2 : Utilisation des variables d'environnement

Modifier en ligne

Vous pouvez utiliser la variable INSTANA_TRACING_DISABLE d'environnement :

# Disable only Redis spans
INSTANA_TRACING_DISABLE=redis

# Disable all database spans (including Redis)
INSTANA_TRACING_DISABLE=databases

# Disable multiple technologies
INSTANA_TRACING_DISABLE=redis,databases

Option 3 : Par programmation

Modifier en ligne

Vous pouvez également désactiver les éléments « span » de type « Redis » par programmation :

# Disable Redis spans
Instana.config[:redis][:enabled] = false

# Disable logging category
Instana.config[:logging][:enabled] = false

Option 4 : Configuration de l'agent

Modifier en ligne

Pour désactiver les segments « Redis » via la configuration de l'agent, ajoutez la disable configuration suivante au fichier configuration.yaml de l'agent :

tracing:
  disable:
    - databases: true

Pour désactiver les databases intervalles de catégories à l'aide de la configuration de l'agent, utilisez la configuration de catégories suivante dans le fichier de configuration.yaml l'agent :

Pour plus d'informations, consultez la section « Configuration de l'agent ».

Sujets connexes

Modifier en ligne

Ruby Configuration : Configuration du gem « Instana »

Activer ou désactiver globalement

AutoProfile™

Communication avec l'agent hôte

Kubernetes et Red Hat OpenShift

Activer ou désactiver des composants individuels

Activer ou désactiver la collecte des traces de pile

Configuration des traces de pile

Utilisation des variables d'environnement

Utilisation de la configuration d' YAML

Utilisation de la configuration de l'agent

Configuration spécifique à la technologie

Définition d'un nom de service personnalisé

Définition du nom de processus

Bifurcation de serveurs Web et de systèmes de traitement des travaux

Puma

Unicorn

Middleware Rack

Gestion de l'unité d'exécution d'arrière-plan de l'agent

Journalisation

Débogage et niveau de détail accru

Variable d"environnement

AWS Fargate

AWS Lambda

Filtrage par intervalle

Règles de filtrage

Configuration du filtrage par intervalle

Variables d'environnement pour le filtrage des balises `span`

Utilisation INSTANA_CONFIG_PATH

YAML configuration du filtrage par intervalle

Utilisation des variables d'environnement pour la configuration directe

Configuration de l'agent pour le filtrage des segments

Exemples

Configuration de la désactivation des segments

Catégories prises en charge

Options de configuration

Option 1 : Utilisation de la configuration d' YAML

Option 2 : Utilisation des variables d'environnement

Option 3 : Par programmation

Option 4 : Configuration de l'agent

Sujets connexes

Utilisation `INSTANA_CONFIG_PATH`