概要

Orchestrion は、コンパイル中に Go アプリケーションへ自動的にインスツルメンテーションを追加し、コードの変更を不要にします。包括的なトレースカバレッジを提供し、独自のセキュリティ機能を有効にします。

• 包括的なトレースカバレッジ:
  • あなたのコードおよびすべての依存関係 (Go 標準ライブラリを含む) にインスツルメンテーションを行います。
  • コンパイル中にコードへインスツルメンテーションを追加し、手動インスツルメンテーションの見落としによるトレースカバレッジのギャップを防ぎます。
• 独自の App and API Protection の Exploit Prevention 機能。Exploit Prevention は、Runtime Application Self-Protection (RASP) の実装であり、Local File Inclusion (LFI) などの RASP メソッドを含みます。

要件

• 最新の 2 つの Go ランタイムリリースをサポートしています (Go の公式リリースポリシーに準拠)。
• アプリケーションは go modules を使用して管理する必要があります。モジュールのベンダリングがサポートされています。

Orchestrion をインストールする

Orchestrion をインストールして設定するには:

1. Orchestrion をインストールします

   go install github.com/DataDog/orchestrion@latest
   

   $(go env GOBIN) または $(go env GOPATH)/bin が $PATHに含まれていることを確認してください。

2. プロジェクトの go.mod に Orchestrion を登録してください。

   orchestrion pin
   

   利用可能なカスタマイズオプションに関する詳細情報は orchestrion pin -help の出力を参照してください。

3. 変更をバージョン管理システムにコミットしてください (orchestrion を CI/CD パイプラインに直接統合している場合を除く)

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

   これで、go.mod ファイルを使用して orchestrion への依存関係を他の依存関係と同様に管理できます。

使用方法

ビルドプロセスで Orchestrion を有効にするには、次のいずれかの方法を使用してください。

通常の go コマンドの前に orchestrion を追加します。

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

go コマンドに -toolexec="orchestrion toolexec" 引数を追加します。

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

Orchestrion を注入するために $GOFLAGS 環境変数を変更し、通常通り go コマンドを使用します。

# 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 ./...

トレースのカスタマイズ

unified service tagging の設定

orchestrion によってインスツルメンテーションされたアプリケーションは、Unified Service Tagging (UST) をサポートしています。アプリケーションの runtime 環境で対応する環境変数を設定することで、トレースに UST タグを設定できます。

詳細については、統合サービスタグ付けドキュメントを参照してください。

トレーサーの構成

構成手順については、ライブラリ構成を参照してください。

カスタムトレーススパンの作成

カスタムトレーススパンは、//dd:span ディレクティブコメントで注釈された任意の関数に対して自動的に作成されます。

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

これは関数リテラル式でも機能します。

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

オペレーション名

オペレーションの名前 (span.name) は、次の優先順位に従って自動的に決定されます。

1. ディレクティブ引数として指定された明示的な span.name:customOperationName タグ
2. 関数の宣言された名前 (これは匿名の関数リテラル式には適用されません)
3. ディレクティブ引数リストに指定された最初のタグの値

//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"
}

エラー結果

注釈付き関数が error 結果を返す場合、関数によって返されたエラーは対応するトレーススパンに自動的に添付されます。

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

一部のコードのインスツルメンテーションを防ぐ

//orchestrion:ignore ディレクティブを使用して、orchestrion が注釈付きコードに対して_いかなる_修正も行わないようにすることができます。

これは、特定の場所に対して呼び出し側のインスツルメンテーションが適用されるのを防ぐために使用できます。

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")
  // ...
}

orchestrion によって行われるインスツルメンテーションの一部は、呼び出される側 (またはライブラリ側) で行われ、依存関係自体に直接統合が追加されることを意味します。そのような場合、これらの統合をローカルでオプトアウトすることはできません。

SDK を使用する

Orchestrion で構築されたアプリケーションで SDK を使用できます。これは、Orchestrion でまだサポートされていないフレームワークのインスツルメンテーションに役立ちます。ただし、Orchestrion のサポート範囲の拡大に伴い、将来的に重複したトレーススパンが発生する可能性があることに注意してください。orchestrion 依存関係を更新する際は、リリースノートを確認して新機能に関する情報を把握し、必要に応じて手動インスツルメンテーションを調整してください。

継続的プロファイラを使用する

Orchestrion で構築されたアプリケーションには、continuous profiler のインスツルメンテーションが含まれています。 プロファイラを有効にするには、実行時に環境変数 DD_PROFILING_ENABLED=true を設定してください。

インテグレーションを削除する

orchestrion.tool.go ファイルのインポートを変更することで、インテグレーションを削除できます。 orchestrion.tool.go ファイルを作成してから orchestrion を実行することもできます。 インテグレーションを使用したくない場合や、 プログラムが使用しないインテグレーションに関するトランジティブ依存関係の数を削減したい場合に、これを行うことがあります。 デフォルトでは、Orchestrion は github.com/DataDog/dd-trace-go/orchestrion/all/v2 をインポートします。 これは、Orchestrion インテグレーションがあるすべてのライブラリをインポートします。 このインポートは、使用したいインテグレーションのみに置き換えることができます。 サポートされているインテグレーションのリストについては、SDK ソースコードを参照してください。

注: 特定のインテグレーションをインポートすることを選択した場合、新しいインテグレーションを追加するたびに orchestrion.tool.go を手動で更新する必要があります。

Docker でのビルド

適切な Docker イメージを作成する方法の詳細については、Go 向け APM の Dockerfile の作成を参照してください。

トラブルシューティング

orchestrion が管理するビルドのトラブルシューティングについては、Go コンパイル時インスツルメンテーションのトラブルシューティングを参照してください。

アプリケーションに SDK を追加する

まず、ライブラリ構成ドキュメントに従って、コード内で SDK をインポートして開始します。構成手順や API の使用に関する詳細については、API ドキュメント (または API ドキュメント v1) を参照してください。

Go インテグレーションを有効化してスパンを作成する

Go インテグレーションを有効化してスパンを生成します。Datadog には、一連のライブラリやフレームワークのインスツルメンテーション向けにすぐに使えるサポートを提供するプラグイン可能な一連のパッケージがあります。これらのパッケージの一覧は、互換性要件ページにあります。これらのパッケージをアプリケーションにインポートし、各インテグレーションに記載されている構成手順に従ってください。