Managed Service for OpenTelemetry:SkyWalking を使用して Go アプリケーションのトレースデータをレポートする

サンプルコード

サンプルコードリポジトリの詳細については、GitHub の skywalking-demo を参照してください。

skywalking-go エージェントを使用してトレースデータをレポートする

1. skywalking-go エージェントをダウンロードします。

2. skywalking-go エージェントをビルドします。

   cd skywalking-go && make build

3. skywalking-go/bin ディレクトリに実行可能ファイルを生成します。

   実行可能ファイルは、オペレーティングシステムによって異なります。たとえば、macOS オペレーティングシステムの場合は skywalking-go-agent--darwin-amd64 を使用します。

   

4. Go プロジェクトを開き、SkyWalking モジュールをメインパッケージにインポートします。

   方法 1

   package main
   
   import (
   	_ "github.com/apache/skywalking-go"
   )
   // ...残りのコード
   

   方法 2

   skywalking-go/bin/skywalking-go-agent--darwin-amd64 -inject path/to/your-project

5. config.yaml ファイルを設定します。

   サンプルコードの skywalking-go/tools/go-agent/config/config.default.yaml ファイルを参照して、config.yaml ファイルを設定できます。

   展開して config.default.yaml ファイルのサンプルコンテンツを表示

   agent:
     # サービス名は UI に表示されます。
     service_name: ${SW_AGENT_NAME:Your_ApplicationName}
     # インスタンス名の環境変数キーを取得します。取得できない場合は、インスタンス名が自動的に生成されます。
     instance_env_name: SW_AGENT_INSTANCE_NAME
     # トレースデータのサンプリングレート。0 から 1 の間の浮動小数点数である必要があります。
     sampler: ${SW_AGENT_SAMPLE:1}
     meter:
       # メトリックを収集する間隔（秒単位）。
       collect_interval: ${SW_AGENT_METER_COLLECT_INTERVAL:20}
   
   reporter:
     grpc:
       # バックエンドサービスの gRPC サーバーアドレス。
       backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}
       # トレースデータのレポートに使用されるセグメントの最大数。
       max_send_queue: ${SW_AGENT_REPORTER_GRPC_MAX_SEND_QUEUE:5000}
       # サービスとバックエンドサービスをチェックする間隔（秒）。
       check_interval: ${SW_AGENT_REPORTER_GRPC_CHECK_INTERVAL:20}
       # バックエンドと通信するための認証文字列。
       authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}
       # バックエンドから動的設定を取得する間隔（秒）。
       cds_fetch_interval: ${SW_AGENT_REPORTER_GRPC_CDS_FETCH_INTERVAL:20}
       tls:
         # バックエンドで TLS を有効にするかどうか。
         enable: ${SW_AGENT_REPORTER_GRPC_TLS_ENABLE:false}
         # ca.crt のファイルパス。この設定は、TLS スイッチを開いた場合にのみ機能します。
         ca_path: ${SW_AGENT_REPORTER_GRPC_TLS_CA_PATH:}
         # client.pem のファイルパス。この設定は、mTLS の場合にのみ機能します。
         client_key_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_KEY_PATH:}
         # client.crt のファイルパス。この設定は、mTLS の場合にのみ機能します。
         client_cert_chain_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_CERT_CHAIN_PATH:}
         # クライアントがサーバーの証明書チェーンとホスト名を確認するかどうかを制御します。
         insecure_skip_verify: ${SW_AGENT_REPORTER_GRPC_TLS_INSECURE_SKIP_VERIFY:false}
   
   log:
     # タイプは、システムで現在使用されているログタイプを決定します。
     # Go エージェントは、このログタイプを使用してカスタムログを生成します。"auto"、"logrus"、または "zap" をサポートしています。
     # auto: ログのソースを自動的に識別します。
     #       プロジェクトに logrus が存在する場合、logrus を自動的に使用します。
     #       プロジェクトで zap が初期化されている場合、zap フレームワークを使用します。
     #       デフォルトでは、標準エラーを使用してログコンテンツを出力します。
     # logrus: エージェントが logrus フレームワークを使用するように指定します。
     # zap: エージェントが zap フレームワークを使用するように指定します。
     # システムは、"zap.New"、"zap.NewProduction" などのメソッドによって既に初期化されている必要があります。
     type: ${SW_AGENT_LOG_TYPE:auto}
     tracing:
       # トレース情報をログに自動的に統合するかどうか。
       enable: ${SW_AGENT_LOG_TRACING_ENABLE:true}
       # トレース情報が有効になっている場合、トレース情報は各ログの現在のキーに格納されます。
       key: ${SW_AGENT_LOG_TRACING_KEY:SW_CTX}
     reporter:
       # ログをバックエンドにアップロードするかどうか。
       enable: ${SW_AGENT_LOG_REPORTER_ENABLE:true}
       # ログのラベルに追加する必要があるフィールド名リスト（複数ある場合は "," で区切る）。
       label_keys: ${SW_AGENT_LOG_REPORTER_LABEL_KEYS:}
   
   plugin:
     # 除外するプラグインの名前をリストします。複数のプラグイン名は "," で区切る必要があります。
     # 注：このパラメータは、コンパイルフェーズでのみ有効です。
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:}
     config:
       http:
         # サーバー側で HTTP リクエストのパラメータを収集します。
         server_collect_parameters: ${SW_AGENT_PLUGIN_CONFIG_HTTP_SERVER_COLLECT_PARAMETERS:false}
       mongo:
         # MongoDB リクエストのステートメントを収集します。
         collect_statement: ${SW_AGENT_PLUGIN_CONFIG_MONGO_COLLECT_STATEMENT:false}
       sql:
         # SQL リクエストのパラメータを収集します。
         collect_parameter: ${SW_AGENT_PLUGIN_CONFIG_SQL_COLLECT_PARAMETER:false}
   

   パラメータを設定するには、2 つの方法があります。たとえば、service_name パラメータを設定するには、次のいずれかの方法を使用します。

   方法 1 (推奨): config.yaml ファイルに service_name パラメータを追加する

   agent:
     service_name: ${SW_AGENT_NAME:<your_service_name>}

   方法 2: システム環境変数を設定する

   export SW_AGENT_NAME=<your_service_name>

   skywalking-go エージェントを Managed Service for OpenTelemetry コンソールに接続するには、次のパラメータを設定する必要があります。

   • service_name: ${SW_AGENT_NAME:Your_ApplicationName}: Go アプリケーションの名前。

   • backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}: サーバーのエンドポイント。

   • authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}: サーバーにアクセスするための認証トークン。

   デフォルトでは、skywalking-go エージェントはすべてのプラグインを自動的にインストルメントします。特定のプラグインの自動インストルメンテーションを無効にするには、excluded パラメータを指定します。例:

   # SQL プラグインの自動インストルメンテーションを無効にします。
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
   
   # 複数のプラグインの自動インストルメンテーションを無効にします。プラグインはコンマ (,) で区切ります。
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

6. プロジェクトをリビルドします。

   # -toolexec パラメータを指定します。
   sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

   • path/to/skywalking-go-agent: 「skywalking-go エージェントを使用してトレースデータをレポートする」セクションの手順 3 で生成された実行可能ファイルへの絶対パス。

   • path/to/config.yaml: skywalking-go エージェントの config.yaml ファイルへの絶対パス。

7. プロジェクトを開始します。その後、SkyWalking はデータを Managed Service for OpenTelemetry コンソールにレポートします。

付録

次の表に、skywalking-go エージェントのいくつかの環境変数を示します。NULL の値は、デフォルト値が指定されていないことを示します。

Go2Sky エージェントを使用してトレースデータをレポートする

1. Go2Sky エージェントでは、パラメータをプロジェクトにハードコーディングするか、環境変数を使用してパラメータを設定できます。

   パラメータをプロジェクトにハードコーディングする

   ### reporter.WithParameter() メソッドを使用してパラメータをインポートします。
   report, err := reporter.NewGRPCReporter(
       <your-backend-server-address>,
       reporter.WithAuthentication(<your-auth-token>))

   環境変数を使用してパラメータを設定する

   ### Go2Sky エージェントは、環境変数から次のパラメータの値を取得できます。
   SW_AGENT_AUTHENTICATION
   SW_AGENT_LAYER
   SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD
   SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL
   SW_AGENT_COLLECTOR_BACKEND_SERVICES
   SW_AGENT_COLLECTOR_MAX_SEND_QUEUE_SIZE
   SW_AGENT_PROCESS_STATUS_HOOK_ENABLE
   SW_AGENT_PROCESS_LABELS
   
   ### 環境変数を設定します。この例では、macOS を使用しています。
   # 方法 1: 環境変数設定ファイルを記述します。この方法で設定された環境変数は永続的に有効です。
   vim ~/.bash_profile
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
   source ~/.bash_profile
   # 方法 2: ターミナルを開き、コマンドラインで環境変数を設定します。この方法で設定された環境変数は一時的に有効であり、別のターミナルを開くと無効になります。
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>

2. ServiceName パラメータを設定してアプリケーションを指定します。

   ServiceName := <your-service-name>
   tracer, err := go2sky.NewTracer(ServiceName, go2sky.WithReporter(report))

3. Go2Sky プラグインのフックを追加します。

   Go2Sky エージェントは、多くのライブラリ用のプラグインを提供しています。これらのプラグインのフックをプロジェクトのソースコードに追加する必要があります。フックを追加する方法の詳細については、GitHub の go2sky-plugins リポジトリを参照してください。各プラグインの plugin フォルダには、プラグインの使用方法を説明する README.md ファイルが用意されています。

   この例では、gin フレームワークを使用しています。

   1. /gin フォルダに移動し、/gin/v3/README.md ファイルを表示します。

   2. ミドルウェアのフック v3.Middleware(r, tracer) を追加します。

      package main
      
      import (
      	"log"
      
      	"github.com/SkyAPM/go2sky"
      	v3 "github.com/SkyAPM/go2sky-plugins/gin/v3"
      	"github.com/SkyAPM/go2sky/reporter"
      	"github.com/gin-gonic/gin"
      )
      
      func main() {
      	// 本番環境では gRPC レポーターを使用します。
      	re, err := reporter.NewLogReporter()
      	if err != nil {
      		log.Fatalf("新しいレポーターエラー %v \n", err)
      	}
      	defer re.Close()
      
      	tracer, err := go2sky.NewTracer("gin-server", go2sky.WithReporter(re))
      	if err != nil {
      		log.Fatalf("トレーサーの作成エラー %v \n", err)
      	}
      
      	gin.SetMode(gin.ReleaseMode)
      	r := gin.New()
      
      	// トレースを使用して go2sky ミドルウェアを使用します
      	r.Use(v3.Middleware(r, tracer))
      
      	// 何かを実行します
      }
      

4. アプリケーションを再起動します。

付録

次の表に、Go2Sky エージェントの環境変数を示します。NULL の値は、デフォルト値が指定されていないことを示します。

FAQ

• skywalking-go エージェントを使用しているときに、次の図に示すエラーメッセージが表示された場合はどうすればよいですか？

  

  inject メソッドが失敗した場合は、import メソッドを使用して SkyWalking モジュールをメインパッケージにインポートできます。

• Go2Sky エージェントを使用してトレースデータをレポートするときに、Managed Service for OpenTelemetry コンソールにクロスプロセスサービス呼び出しの正しいトレースデータが表示されないのはなぜですか？

  Managed Service for OpenTelemetry は、トレース ID に基づいてトレースを接続します。トレース ID は、HTTP リクエストによって伝送されます。無効なトレースデータが表示される場合は、トレース ID が正しく伝送されていません。この場合は、インストルメンテーションに適切なスパンを設定する必要があります。

  クロスプロセスサービス呼び出しのトレースを接続するには、次の 2 つの重要な操作を呼び出すことができます。

  • CreateEntrySpan: エントリスパンを作成します。この操作を呼び出して、トレース ID を含むトレース分析コンテキストを HTTP リクエストから抽出できます。

  • CreateExitSpan: 出力スパンを作成します。この操作を呼び出して、トレース ID を含むトレース分析コンテキストを HTTP リクエストに挿入できます。

  // CreateLocalSpan 操作を呼び出して、プロセス内にスパンを作成します。
  span, ctx, err := tracer.CreateLocalSpan(context.Background())
  subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
  
  // クロスプロセスサービス呼び出しの場合は、CreateEntrySpan 操作を呼び出して HTTP リクエストからトレース分析コンテキストを抽出し、CreateExitSpan 操作を呼び出してトレース分析コンテキストを HTTP リクエストに挿入します。
  span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
      return r.Header.Get(key), nil
  })
  span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
  		req.Header.Set(key, value)
  		return nil
  })
  

  クロスプロセスサービス呼び出しでは、トレースを接続するために、トレース ID をプロセス間で伝送する必要があります。したがって、前述の操作を呼び出して、プロセス間で伝送される HTTP リクエストにトレース分析コンテキストを挿入する必要があります。

参考資料

• Apache SkyWalking の公式ウェブサイト

• GitHub の skywalking-go リポジトリ

• skywalking-go の公式ドキュメント

• GitHub の Go2Sky リポジトリ

• GitHub の go2sky-plugins リポジトリ