> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Global VM Lock

export const VersionRequirements = ({versions = []}) => {
  if (!Array.isArray(versions) || versions.length === 0) {
    return null;
  }
  const boundaries = {
    upper: " or lower",
    exact: "",
    lower: " or higher"
  };
  const containerStyle = {
    marginTop: "0.5rem",
    marginBottom: "1.5rem"
  };
  const lineStyle = {
    display: "block",
    margin: "0 0 0.35rem 0",
    fontSize: "0.875rem",
    lineHeight: "1.4"
  };
  const pillBaseStyle = {
    display: "inline-block",
    padding: "0.1em 0.4em",
    borderRadius: "0.25rem",
    border: "1px solid",
    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
    fontSize: "0.85em",
    fontWeight: 500
  };
  const pillColors = {
    "AppSignal for Elixir": {
      background: "#f3e8ff",
      borderColor: "#e9d5ff",
      color: "#9333ea"
    },
    "AppSignal for Front-end": {
      background: "#fef9c3",
      borderColor: "#fde68a",
      color: "#ca8a04"
    },
    "AppSignal for Go": {
      background: "#ccfbf1",
      borderColor: "#99f6e4",
      color: "#0d9488"
    },
    "AppSignal for JavaScript": {
      background: "#fef9c3",
      borderColor: "#fde68a",
      color: "#ca8a04"
    },
    "AppSignal for Node.js": {
      background: "#dcfce7",
      borderColor: "#bbf7d0",
      color: "#16a34a"
    },
    "AppSignal for Python": {
      background: "#dbeafe",
      borderColor: "#bfdbfe",
      color: "#2563eb"
    },
    "AppSignal for Ruby": {
      background: "#fee2e2",
      borderColor: "#fecaca",
      color: "#dc2626"
    },
    "AppSignal for Rust": {
      background: "#ffedd5",
      borderColor: "#fed7aa",
      color: "#ea580c"
    }
  };
  const defaultPillColor = {
    background: "#f4f4f5",
    borderColor: "#e4e4e7",
    color: "#52525b"
  };
  const getPillStyle = name => ({
    ...pillBaseStyle,
    ...pillColors[name] || defaultPillColor
  });
  const getBoundText = bound => {
    return boundaries[bound] || boundaries.lower;
  };
  return <div style={containerStyle}>
      {versions.map((v, i) => <p key={`${v.name}-${v.version}-${v.bound || "lower"}-${i}`} style={lineStyle}>
          This feature requires{" "}
          <code style={getPillStyle(v.name)}>{v.name}</code> version {v.version}
          {getBoundText(v.bound)}.
        </p>)}
    </div>;
};

<VersionRequirements
  versions={[
{ name: "AppSignal for Ruby", version: "3.3.9" },
{ name: "Ruby", version: "3.2" },
{ name: "gvltools", version: "0.2" }
]}
/>

La VM (machine virtuelle) Ruby planifie l'exécution des threads Ruby. À tout moment, un seul thread peut être actif et interagir avec l'état de la VM Ruby.

Le mécanisme par lequel l'interpréteur Ruby garantit cela est le Global VM Lock (GVL).

Le changement de thread a sa propre surcharge. Les métriques relatives au Global VM Lock vous permettent de voir le temps qu'un thread passe à attendre son tour pour s'exécuter, ainsi que le nombre de threads en attente d'exécution à un moment donné. Ces métriques peuvent fournir des informations utiles pour comprendre les problèmes de performances de votre application.

Lorsqu'AppSignal détecte les métriques du Global VM Lock, il créera un [Magic Dashboard](#magic-dashboard) vous permettant de surveiller visuellement les métriques principales.

## Installation

<Warning>
  La bibliothèque `gvltools` n'est compatible qu'avec l'interpréteur Ruby officiel.
  JRuby n'est pas pris en charge.
</Warning>

Pour qu'AppSignal puisse obtenir les métriques du Global VM Lock, vous devez ajouter la bibliothèque `gvltools` à votre projet :

<CodeGroup>
  ```shell Shell theme={null}
  bundle add gvltools
  ```
</CodeGroup>

Une fois installée, l'intégration AppSignal collectera automatiquement les métriques du Global VM Lock chaque minute.

## Magic dashboards

Les magic dashboards apparaîtront dans la section [Dashboard](https://appsignal.com/redirect-to/app?to=dashboard) d'AppSignal.

<img src="https://mintcdn.com/appsignal-715f5a51/4TRZP0Sq9Zq7PAPW/assets/images/screenshots/ruby/integrations/global-vm-lock/magic-dashboard.png?fit=max&auto=format&n=4TRZP0Sq9Zq7PAPW&q=85&s=005c856a34ea7513ae781ce685cb6c45" alt="Création du magic dashboard Ruby GVL" width="2548" height="1430" data-path="assets/images/screenshots/ruby/integrations/global-vm-lock/magic-dashboard.png" />

Le magic dashboard Global VM Lock contient les graphiques suivants :

| Graphique                                 | Métrique              |
| ----------------------------------------- | --------------------- |
| [Global timer](#global-timer-graph)       | `gvl_global_timer`    |
| [Waiting threads](#waiting-threads-graph) | `gvl_waiting_threads` |

AppSignal signale les tags suivants pour les métriques du Global VM Lock :

| Nom            | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `hostname`     | Le nom de l'hôte depuis lequel la métrique a été signalée    |
| `process_id`   | L'ID du processus depuis lequel la métrique a été signalée   |
| `process_name` | Le nom du processus depuis lequel la métrique a été signalée |

<Tip>
  Les tags `process_id` et `process_name` ne sont signalés qu'en utilisant
  AppSignal for Ruby version 3.9.3 ou ultérieure.
</Tip>

<img src="https://mintcdn.com/appsignal-715f5a51/4TRZP0Sq9Zq7PAPW/assets/images/screenshots/ruby/integrations/global-vm-lock/dashboard-graphs.png?fit=max&auto=format&n=4TRZP0Sq9Zq7PAPW&q=85&s=7adb9334fbf51a1ab2d6e28aad0c5d3f" alt="Magic dashboard Ruby GVL" width="2200" height="872" data-path="assets/images/screenshots/ruby/integrations/global-vm-lock/dashboard-graphs.png" />

### Graphique Global timer

Le graphique Global timer montre le temps passé par les threads à attendre leur reprise au cours de la dernière minute, c'est-à-dire à attendre que leur code soit à nouveau exécuté.

#### Configuration de la mesure du global timer

La mesure du global timer a une surcharge de performance estimée à 5 %.

Pour éviter d'avoir un impact négatif sur les performances de votre application, vous pouvez désactiver `gvl_global_timer` par défaut et l'activer au besoin pour des requêtes spécifiques ou des jobs intensifs en threads.

Pour désactiver cette métrique au démarrage, définissez [l'option de configuration `enable_gvl_global_timer`](/ruby/configuration/options#option-enable_gvl_global_timer) sur `false`.

Vous pouvez ensuite utiliser la bibliothèque `gvltools` pour activer et désactiver la mesure du global timer sans avoir à redémarrer votre application :

<CodeGroup>
  ```ruby Ruby theme={null}
  require "gvltools"

  GVLTools::GlobalTimer.enable

  # some code that uses threads ...

  GVLTools::GlobalTimer.disable
  ```
</CodeGroup>

### Graphique Waiting threads

Le graphique Waiting threads montre le nombre de threads en attente de reprise à un moment donné. Le graphique n'inclut pas les threads qui ne sont pas prêts à être repris, comme les threads qui dorment ou attendent un événement d'E/S.

Pour désactiver cette métrique, vous pouvez définir [l'option de configuration `enable_gvl_waiting_threads`](/ruby/configuration/options#option-enable_gvl_waiting_threads) sur `false`.