instrument-tracing

Par posthog · skills

Ajoutez le tracing distribué PostHog pour visualiser le flux des requêtes entre les services et identifier où le temps est consommé. À utiliser après l'implémentation de fonctionnalités ou lors de la revue de PRs pour vérifier que les points d'entrée des requêtes, les appels sortants et les jobs en arrière-plan produisent des spans, ou lorsqu'on vous demande d'ajouter du tracing ou des spans. Gère également la redirection d'un tracing OpenTelemetry existant vers PostHog et la configuration initiale de l'exporteur OTLP.

npx skills add https://github.com/posthog/skills --skill instrument-tracing

Ajouter du distributed tracing PostHog

Utilisez cette skill pour ajouter du distributed tracing PostHog pour du code nouveau ou modifié. Utilisez-la après l'implémentation de fonctionnalités ou la revue de PRs pour vous assurer que les points d'entrée des requêtes, les appels sortants et les jobs en arrière-plan produisent des spans, quand l'utilisateur demande d'ajouter du tracing ou des spans, ou pour pointer le tracing OpenTelemetry existant vers PostHog. Supporte n'importe quelle plateforme ou langage.

Plateformes supportées : Node.js, Next.js, Python (incluant Django, FastAPI et Flask), Go, Java, .NET, PHP, Ruby, et n'importe quel langage via OpenTelemetry (OTLP).

Le tracing PostHog utilise le SDK OpenTelemetry standard et un exportateur de traces OTLP HTTP. Il n'a pas besoin d'un SDK PostHog.

Instructions

Suivez ces étapes DANS L'ORDRE :

ÉTAPE 1 : Analysez la base de code et détectez la plateforme.

  • Détectez le langage, le framework et la configuration de tracing existante.
  • Cherchez les fichiers de dépendances et les fichiers de projet (package.json, requirements.txt, pyproject.toml, go.mod, pom.xml, build.gradle, *.csproj, Gemfile, composer.json, etc.).
  • Cherchez les fichiers de verrouillage (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, poetry.lock, uv.lock, go.sum, Gemfile.lock, composer.lock, etc.) pour déterminer le gestionnaire de paquets.
  • Cherchez le tracing existant : un fournisseur de traceur OpenTelemetry, un fichier instrumentation.ts, une commande de lancement opentelemetry-instrument, une config OpenTelemetry Collector, un flag d'agent Java, ou un agent de tracing d'un autre fournisseur.
  • Vérifiez si un SDK PostHog (posthog-js, posthog-node, posthog-python) est déjà installé. Vous en avez besoin uniquement pour l'ÉTAPE 6.

ÉTAPE 2 : Choisissez le chemin de capture.

  • Si la base de code exporte déjà des traces OpenTelemetry, pointez l'exportateur de traces OTLP existant (ou Collector) vers PostHog. Réutilisez le fournisseur de traceur existant. S'il exporte vers un autre backend de tracing, demandez à l'utilisateur avant d'ajouter PostHog comme deuxième destination.
  • Sinon, ajoutez le SDK OpenTelemetry avec un exportateur de traces OTLP HTTP et l'auto-instrumentation. L'auto-instrumentation crée des spans pour les serveurs HTTP, les frameworks et les drivers de base de données sans modifications de code.
  • Lisez la référence de plateforme qui correspond à la pile détectée maintenant. Utilisez sa section « With OpenTelemetry ». Si aucune référence ne correspond, utilisez la référence d'installation générale.

ÉTAPE 3 : Installez les dépendances. (Ignorez si la base de code exporte déjà des traces OpenTelemetry.)

  • Installez le SDK OpenTelemetry, l'exportateur de traces OTLP HTTP/protobuf, et l'auto-instrumentation pour la pile détectée :
    • Node.js et Next.js : les paquets de la référence de plateforme, plus @opentelemetry/auto-instrumentations-node.
    • Python : opentelemetry-distro et opentelemetry-exporter-otlp-proto-http, puis exécutez opentelemetry-bootstrap -a install. Cela installe les paquets d'instrumentation pour les bibliothèques que l'application utilise déjà. N'installez pas opentelemetry-instrumentation-all.
    • Go : les paquets de la référence de plateforme, plus l'instrumentation contrib pour chaque bibliothèque, comme go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp.
    • Java : l'agent sans-code opentelemetry-javaagent.jar. Il n'a besoin d'aucune modification de dépendance.
    • .NET : OpenTelemetry, OpenTelemetry.Exporter.OpenTelemetryProtocol, et OpenTelemetry.Extensions.Hosting, plus OpenTelemetry.Instrumentation.AspNetCore et OpenTelemetry.Instrumentation.Http.
    • PHP : les paquets de la référence de plateforme. Pour l'auto-instrumentation, l'extension PHP opentelemetry (de PECL) et le paquet open-telemetry/opentelemetry-auto-* pour le framework, comme open-telemetry/opentelemetry-auto-slim.
    • Ruby : opentelemetry-sdk, opentelemetry-exporter-otlp, et opentelemetry-instrumentation-all, activés avec c.use_all.
  • Ne modifiez pas manuellement les fichiers de dépendances — utilisez la commande d'installation du gestionnaire de paquets.

ÉTAPE 4 : Configurez l'exportateur de traces OTLP.

  • Envoyez les spans sur OTLP HTTP/protobuf vers /i/v1/traces sur l'hôte PostHog, avec le token du projet dans un header Authorization: Bearer. N'utilisez pas /i/v0/ai/otel. Cet endpoint accepte uniquement les spans LLM.
  • Avec les variables d'environnement, définissez le chemin complet dans OTEL_EXPORTER_OTLP_TRACES_ENDPOINT et le header dans OTEL_EXPORTER_OTLP_TRACES_HEADERS (Authorization=Bearer <token>). Ne définissez pas la base OTEL_EXPORTER_OTLP_ENDPOINT pour PostHog. Elle ajoute son propre chemin /v1/traces.
  • Définissez OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf où le SDK ou l'agent utilise gRPC par défaut. Cela s'applique à l'agent Java, .NET, et Python avec opentelemetry-distro.
  • Python avec opentelemetry-distro : démarrez l'application avec opentelemetry-instrument (par exemple, opentelemetry-instrument python app.py). Cela construit le fournisseur de traceur à partir des variables d'environnement, donc ne créez pas aussi de fournisseur dans le code. La distro active également l'export des métriques et logs OTLP. Définissez OTEL_METRICS_EXPORTER=none et OTEL_LOGS_EXPORTER=none sauf si l'application envoie déjà ces signaux ailleurs.
  • Définissez un nom de service (service.name, ou OTEL_SERVICE_NAME) pour que les spans soient faciles à trouver dans l'interface Tracing.
  • Démarrez le fournisseur avant que l'application charge ses frameworks, pour que l'auto-instrumentation puisse les patcher. Dans Next.js, enregistrez le fournisseur dans instrumentation.ts derrière la vérification NEXT_RUNTIME === 'nodejs'.
  • Suivez la référence spécifique à la plateforme pour la configuration exacte.
  • Vous devez lire un fichier immédiatement avant de tenter de l'écrire.

ÉTAPE 5 : Ajoutez des spans où ils doivent être.

  • L'auto-instrumentation couvre les points d'entrée des requêtes et la plupart des appels sortants. Ajoutez des spans manuels avec l'API du traceur OpenTelemetry uniquement où elle n'en a pas : les gestionnaires de jobs en arrière-plan, les consommateurs de queues, et les étapes internes lentes qui intéressent l'utilisateur.
  • Utilisez des noms de spans de faible cardinalité comme GET /users/:id, pas GET /users/123. Mettez les valeurs variables dans les attributs.
  • Passez le header W3C traceparent sur les appels entre services, pour que les spans de chaque service rejoignent une seule trace.
  • Ne modifiez pas l'architecture fondamentale des fichiers existants. Rendez les ajouts minimes et ciblés.

ÉTAPE 6 : Liez les spans aux personnes et sessions. (Optionnel.)

  • Un span rejoint une personne et un enregistrement Session Replay via les attributs de span posthogDistinctId et sessionId.
  • Si l'application utilise posthog-js, activez tracing_headers pour vos hôtes API. Le navigateur envoie alors les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID sur chaque requête.
  • Avec OpenTelemetry uniquement, copiez ces valeurs sur les spans vous-même. Dans le gestionnaire de requête ou un middleware, lisez les deux headers et définissez-les comme attributs posthogDistinctId et sessionId sur le span de requête actif. Ignorez un header qui manque ou est vide.
  • Si l'application utilise déjà le SDK PostHog, il peut ajouter ces attributs pour vous. N'installez pas le SDK PostHog uniquement pour cette étape.
    • Python : ajoutez PostHogContextSpanProcessor de posthog.integrations.otel au fournisseur de traceur. Cela copie l'ID distinct et l'ID de session du contexte PostHog actif sur chaque nouveau span. Le middleware de contextes de Django lit les headers et définit ce contexte.
    • Node.js et Python : les spans créés avec l'API de span du SDK PostHog (posthog.withSpan, posthog.start_span) dans un contexte de requête PostHog obtiennent ces attributs automatiquement. Cela nécessite posthog-node 5.52.0 ou plus tard, ou posthog 7.58.0 ou plus tard, avec l'option traces définie. Ces spans passent par le SDK PostHog, pas le fournisseur OpenTelemetry. Utilisez ceci uniquement pour les applications qui n'exécutent pas OpenTelemetry.

ÉTAPE 7 : Configurer les variables d'environnement.

  • Vérifiez si le projet a déjà des variables d'environnement PostHog configurées (par exemple dans .env, .env.local, ou les fichiers env spécifiques au framework). Si des valeurs valides existent déjà, ignorez cette étape.
  • Si le token du projet PostHog manque, utilisez l'outil projects-get du serveur MCP PostHog pour récupérer le api_token du projet. Si plusieurs projets sont retournés, demandez à l'utilisateur quel projet utiliser. Si le serveur MCP n'est pas connecté ou non authentifié, demandez à l'utilisateur son token du projet PostHog à la place.
  • Utilisez le token du projet (il commence par phc_). N'utilisez pas une clé API personnelle (elle commence par phx_).
  • Pour l'URL de l'hôte PostHog : vérifiez la réponse projects-get de MCP pour un champ region — US correspond à https://us.i.posthog.com, EU correspond à https://eu.i.posthog.com. Si la région n'est pas disponible dans la réponse MCP ou dans la configuration du projet existant, demandez à l'utilisateur : « Êtes-vous sur PostHog US Cloud ou EU Cloud ? » N'assumez pas US Cloud.
  • Pour l'endpoint de traces OTLP, utilisez https://us.i.posthog.com/i/v1/traces (US) ou https://eu.i.posthog.com/i/v1/traces (EU), en correspondance avec la région déterminée ci-dessus, avec le token du projet comme header Authorization: Bearer.
  • Écrivez ces valeurs dans le fichier env approprié en utilisant la convention de nommage du framework.
  • Référencez ces variables d'environnement dans le code au lieu de les hardcoder.

ÉTAPE 8 : Videz les spans dans les processus courte durée.

  • Le processeur batch exporte les spans à un intervalle. Un script, un job cron, ou une fonction serverless peut s'arrêter avant que le batch soit envoyé.
  • Sur Vercel et autres plateformes serverless, appelez forceFlush() du fournisseur avant le retour de la fonction. Dans Next.js 15.1 et plus tard, appelez-la dans after() de next/server.
  • Sur AWS Lambda, appelez forceFlush() à la fin de chaque invocation. N'appelez pas shutdown() là, car le runtime réutilise le conteneur. Appelez shutdown() uniquement quand le processus se termine.

ÉTAPE 9 : Vérifiez que les spans arrivent.

  • Exécutez l'application et déclenchez le code instrumenté.
  • Ouvrez Tracing dans la barre latérale PostHog et filtrez par le nom du service. Les spans doivent apparaître en moins d'une minute après l'envoi.
  • Si aucun span n'apparaît, vérifiez le chemin de l'endpoint, le token Bearer, le protocole de l'exportateur, et l'étape de vidage.

Fichiers de référence

  • references/nodejs.md - Installation du tracing Node.js
  • references/nextjs.md - Installation du tracing Next.js
  • references/python.md - Installation du tracing Python
  • references/go.md - Installation du tracing Go
  • references/java.md - Installation du tracing Java
  • references/dotnet.md - Installation du tracing .NET
  • references/php.md - Installation du tracing PHP
  • references/ruby.md - Installation du tracing Ruby
  • references/installation.md - Installer le tracing
  • references/start-here.md - Débuter avec le distributed tracing
  • references/basics.md - Pourquoi vous avez besoin du distributed tracing
  • references/COMMANDMENTS.md - Les règles spécifiques au framework que l'intégration doit suivre

Chaque référence de plateforme contient une configuration OpenTelemetry spécifique, une configuration OTLP, et des motifs d'intégration. Trouvez celle qui correspond à la pile de l'utilisateur.

Principes clés

  • OpenTelemetry d'abord : Les traces PostHog utilisent le protocole OpenTelemetry. Utilisez le SDK OpenTelemetry avec auto-instrumentation, et réutilisez un fournisseur de traceur existant quand il y en a un. Le SDK PostHog est optionnel.
  • Variables d'environnement : Utilisez toujours les variables d'environnement pour les clés PostHog et les endpoints OpenTelemetry. Ne les hardcodez jamais.
  • Changements minimes : Ajoutez l'export de traces PostHog aux côtés du code existant. Ne remplacez pas ou ne restructurez pas le tracing existant.
  • Frontières, pas chaque fonction : Quelques spans aux points d'entrée des requêtes, les appels sortants, et les jobs en arrière-plan valent mieux qu'un span autour de chaque fonction.
  • Pas de secrets dans les attributs : Ne mettez jamais de tokens, mots de passe, ou autres secrets dans les noms ou attributs des spans.

Skills similaires

clickstack-otel-collector
clickhouse / agent-skills

Configurer un collecteur OpenTelemetry pour ingérer des données dans ClickHouse Cloud.

561
agent-observability-auto-experiment
datadog-labs / agent-skills

Automatiser une boucle d'amélioration itérative locale de code via évaluations et commits git.

180
llm-obs-eval-bootstrap
datadog-labs / agent-skills

Générer une suite d'évaluateurs prêts à l'emploi à partir de traces LLM en production.

180
agent-observability-eval-bootstrap
datadog-labs / agent-skills

Analyser des traces LLM de production pour générer et publier une suite d'évaluateurs Datadog.

180
doca-telemetry-exporter
nvidia / skills

Configurer, émettre et déboguer la télémétrie structurée via DOCA Telemetry Exporter.

3 772