Suivi des erreurs PostHog pour Ruby on Rails

Cette skill vous aide à ajouter le suivi des erreurs PostHog à vos applications Ruby on Rails.

Fichiers de référence

• references/ruby-on-rails.md - Installation du suivi des erreurs Ruby on rails - docs
• references/fingerprints.md - Fingerprints - docs
• references/alerts.md - Envoyer des alertes de suivi des erreurs - docs
• references/monitoring.md - Surveiller et rechercher des issues - docs
• references/assigning-issues.md - Assigner des issues aux coéquipiers - docs
• references/upload-source-maps.md - Télécharger les source maps - docs

Consultez la documentation pour les détails de l'API et les patterns spécifiques au framework.

Principes clés

• Variables d'environnement : Toujours utiliser les variables d'environnement pour les clés PostHog et les URL d'hôte. Ne jamais les coder en dur.
• Changements minimaux : Ajouter le suivi des erreurs en parallèle de la gestion des erreurs existante. Ne pas remplacer ou restructurer le code de gestion des erreurs existant.
• Autocapture d'abord : Activer la capture automatique des exceptions dans l'initialisation du SDK avant d'ajouter des captures manuelles.
• Source maps : Télécharger les source maps pour que les stack traces se résolvent en code source original, pas en bundles minifiés.
• Capture manuelle pour les limites : Utiliser captureException() aux limites d'erreurs et dans les blocs catch pour les erreurs qui ne se propagent pas au gestionnaire global.

Directives du framework

• Utiliser la gem posthog-rails en parallèle de posthog-ruby pour la capture automatique des exceptions et l'instrumentation ActiveJob
• Exécuter rails generate posthog:install pour créer l'initializer, ou créer manuellement config/initializers/posthog.rb
• Configurer auto_capture_exceptions: true pour tracker automatiquement les exceptions non gérées dans les contrôleurs
• Configurer report_rescued_exceptions: true pour aussi capturer les exceptions que Rails gère (par ex. avec rescue_from)
• Configurer auto_instrument_active_job: true pour tracker les défaillances des jobs de fond avec la classe de job, la queue et les arguments
• Utiliser les méthodes au niveau classe PostHog.capture() et PostHog.identify() (PAS les méthodes d'instance) — la gem posthog-rails gère le cycle de vie du client via PostHog.init
• NE PAS créer manuellement les instances PostHog::Client dans Rails — utiliser PostHog.init dans l'initializer et PostHog.capture/identify partout ailleurs
• capture_exception prend des args POSITIONNELS : PostHog.capture_exception(exception, distinct_id, additional_properties) — NE PAS utiliser les keyword args
• Définir posthog_distinct_id sur le modèle User pour l'association automatique de l'utilisateur dans les rapports d'erreur — posthog-rails détecte automatiquement en essayant : posthog_distinct_id, distinct_id, id, pk, uuid (dans l'ordre)
• Pour l'association utilisateur dans ActiveJob, utiliser le DSL au niveau classe posthog_distinct_id ->(user) { user.email } ou passer user_id: dans un argument hash
• Stocker la clé API dans les credentials Rails ou les variables d'environnement, jamais coder en dur
• Pour le tracking frontend en parallèle de posthog-rails, ajouter le snippet posthog-js au template layout — posthog-js gère les pageviews, la session replay et les erreurs côté client tandis que posthog-ruby gère les événements backend, les erreurs serveur, les feature flags et les jobs de fond
• posthog-ruby est le nom de la gem SDK Ruby (ajouter gem 'posthog-ruby' au Gemfile) mais l'importer avec require 'posthog' (PAS require 'posthog-ruby')
• Utiliser PostHog::Client.new(api_key: key, host: host) pour l'initialisation basée sur instance dans les scripts et CLIs
• Dans les CLIs et scripts : DOIT appeler client.shutdown avant exit sinon tous les événements sont perdus
• capture et identify prennent un seul argument hash : client.capture(distinct_id: 'user_123', event: 'my_event', properties: { key: 'value' })
• capture_exception prend des args POSITIONNELS (pas keyword) : client.capture_exception(exception, distinct_id, additional_properties) — NE PAS utiliser la syntaxe keyword distinct_id: