Aperçu

Orchestrion ajoute automatiquement l’instrumentation aux applications Go lors de la compilation, éliminant ainsi le besoin de modifications de code. Il fournit une couverture de traçage complète et permet des fonctionnalités de sécurité exclusives :

• Couverture de traçage complète :
  • Instrumente votre code et toutes les dépendances, y compris la bibliothèque standard Go
  • Instrumente votre code lors de la compilation, empêchant les lacunes dans la couverture de traçage dues à une instrumentation manuelle négligée
• Fonctionnalité exclusive de Protection des applications et API Prévention des exploits. Prévention des exploits est une mise en œuvre de la protection des applications en cours d’exécution (RASP) et inclut des méthodes RASP telles que l’inclusion de fichiers locaux (LFI).

Exigences

• Prend en charge les deux dernières versions du Go runtime (correspondant à la politique de publication officielle de Go).
• Les applications doivent être gérées à l’aide de modules Go. Le vendoring de modules est pris en charge.

Installer Orchestrion

Pour installer et configurer Orchestrion :

1. Installer Orchestrion :

   go install github.com/DataDog/orchestrion@latest
   

   Assurez-vous que $(go env GOBIN) ou $(go env GOPATH)/bin est dans votre $PATH.

2. Enregistrez Orchestrion dans le go.mod de votre projet :

   orchestrion pin
   

   Référez-vous à la sortie de orchestrion pin -help pour plus d’informations sur les options de personnalisation disponibles.

3. Engagez les modifications dans votre système de contrôle de version (sauf si vous intégrez orchestrion directement dans votre pipeline CI/CD) :

   git add go.mod go.sum orchestrion.tool.go
   git commit -m "chore: enable orchestrion"
   

   Vous pouvez maintenant gérer votre dépendance à orchestrion comme toute autre dépendance en utilisant le fichier go.mod.

Utilisation

Utilisez l’une de ces méthodes pour activer Orchestrion dans votre processus de construction :

Placez orchestrion avant vos commandes go habituelles :

orchestrion go build .
orchestrion go run .
orchestrion go test ./...

Ajoutez l’argument -toolexec="orchestrion toolexec" à vos commandes go :

go build -toolexec="orchestrion toolexec" .
go run -toolexec="orchestrion toolexec" .
go test -toolexec="orchestrion toolexec" ./...

Modifiez la variable d’environnement $GOFLAGS pour injecter Orchestrion, et utilisez les commandes go normalement :

# Make sure to include the quotes as shown below, as these are required for
# the Go toolchain to parse GOFLAGS properly!
export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"
go build .
go run .
go test ./...

Personnalisation de la trace

Configuration du tagging de service unifié

Les applications instrumentées par orchestrion prennent en charge le tagging de service unifié (UST). Vous pouvez définir des tags UST pour vos traces en définissant la variable d’environnement correspondante dans l’environnement runtime de votre application :

Pour plus d’informations, référez-vous à la documentation sur le tagging de service unifié.

Configuration du Traceur

Référez-vous à Configuration de la Bibliothèque pour les instructions de configuration.

Créez des spans de trace personnalisés

Des spans de trace personnalisés peuvent être créés automatiquement pour toute fonction annotée avec le commentaire de directive //dd:span :

//dd:span custom_tag:tag_value
func CriticalPathFunction() {
  // ... implementation details ...
}

Cela fonctionne également avec des expressions littérales de fonction :

//dd:span custom_tag:tag_value
handler := func(w http.ResponseWriter, r *http.Request) {
  // ... implementation details ...
}

Nom de l’Opération

Le nom de l’opération (span.name) est déterminé automatiquement en utilisant la priorité suivante :

1. Une balise explicite span.name:customOperationName spécifiée comme argument de directive
2. Le nom déclaré de la fonction (cela ne s’applique pas aux expressions littérales de fonction, qui sont anonymes)
3. La valeur de la toute première balise fournie à la liste des arguments de directive

//dd:span tag-name:spanName other-tag:bar span.name:operationName
func tracedFunction() {
  // This function will be represented as a span named "operationName"
}

//dd:span tag-name:spanName other-tag:bar
func otherTracedFunction() {
  // This function will be represented as a span named "otherTracedFunction"
}

//dd:span tag-name:spanName other-tag:bar
tracedFunction := func() {
  // This function will be represented as a span named "spanName"
}

Résultats d’erreur

Si la fonction annotée renvoie un error résultat, toute erreur renvoyée par la fonction sera automatiquement attachée au span de trace correspondant :

//dd:span
func failableFunction() (any, error) {
  // This span will have error information attached automatically.
  return nil, errors.ErrUnsupported
}

Empêchez l’instrumentation de certaines parties du code

Vous pouvez utiliser la directive //orchestrion:ignore pour empêcher orchestrion d’effectuer toute modification sur le code annoté.

Cela peut être utilisé pour empêcher l’instrumentation côté appelant d’être appliquée à des emplacements spécifiques :

import "database/sql"

// Caller-side instrumentation normally happens within this function...
func normal() {
  // The following assignment will NOT be modified to add any caller-side
  // instrumentation as it is opted out by the orchestrion:ignore directive:
  //orchestrion:ignore
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

// Caller-side instrumentation will NOT happen in the following function
// as it is annotated with orchestrion:ignore.
//orchestrion:ignore
func excluded() {
  // The following assignment will NOT be modified to add any caller-side
  // instrumentation as the surrounding context is excluded by an
  // orchestrion:ignore directive:
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

Une partie de l’instrumentation effectuée par orchestrion est réalisée côté appelé (ou côté bibliothèque), ce qui signifie que l’intégration est ajoutée directement au sein de la dépendance elle-même. Dans de tels cas, il n’est pas possible de se désinscrire localement de telles intégrations.

Utilisez le SDK

Vous pouvez utiliser le SDK dans votre application construite avec Orchestrion. Ceci est utile pour instrumenter des frameworks qui ne sont pas encore pris en charge par Orchestrion. Cependant, soyez conscient que cela peut entraîner des intervalles de trace dupliqués à l’avenir à mesure que le support d’Orchestrion s’élargit. Consultez les notes de version lors de la mise à jour de votre dépendance orchestrion pour rester informé des nouvelles fonctionnalités et ajuster votre instrumentation manuelle si nécessaire.

Utilisez le profileur continu

Votre application construite avec Orchestrion inclut l’instrumentation du profileur continu. Pour activer le profileur, définissez la variable d’environnement DD_PROFILING_ENABLED=true à l’exécution.

Supprimer les intégrations

Vous pouvez supprimer les intégrations en modifiant les imports dans le fichier orchestrion.tool.go. Vous pouvez également créer votre propre fichier orchestrion.tool.go avant d’exécuter orchestrion. Vous pourriez faire cela si vous ne souhaitez pas une intégration, ou si vous souhaitez réduire le nombre de dépendances transitives pour les intégrations que votre programme n’utilise pas. Par défaut, Orchestrion importe github.com/DataDog/dd-trace-go/orchestrion/all/v2, ce qui importe chaque bibliothèque pour laquelle il existe une intégration Orchestrion. Vous pouvez remplacer cet import par des imports uniquement des intégrations que vous souhaitez utiliser. Voir le code source du SDK pour la liste des intégrations prises en charge.

Remarque: Si vous choisissez d’importer des intégrations spécifiques, vous devez mettre à jour manuellement orchestrion.tool.go chaque fois que vous souhaitez ajouter une nouvelle intégration.

Construction avec Docker

Pour plus d’informations sur la façon de créer une image Docker adaptée, voir Créer un Dockerfile pour APM pour Go.

Dépannage

Pour dépanner les builds que orchestrion gère, consultez Dépannage de l’instrumentation de compilation Go.

Ajoutez le SDK à votre application

Tout d’abord, importez et démarrez le SDK dans votre code en suivant la documentation Configuration de la bibliothèque. Référez-vous à la documentation de l’API (ou à la documentation de l’API v1) pour les instructions de configuration et les détails sur l’utilisation de l’API.

Activez les intégrations Go pour créer des spans

Activez les intégrations Go pour générer des spans. Datadog dispose d’une série de packages modulables qui offrent un support prêt à l’emploi pour instrumenter une série de bibliothèques et de frameworks. Une liste de ces packages peut être trouvée sur la page Exigences de compatibilité. Importez ces packages dans votre application et suivez les instructions de configuration énumérées à côté de chaque intégration.