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

ステップ 1：エージェントのダウンロードとビルド

skywalking-go エージェントをダウンロードし、次のコマンドを実行してビルドします。

cd skywalking-go && make build

実行可能ファイルが skywalking-go/bin ディレクトリに生成されます。実行可能ファイルはオペレーティングシステムによって異なります。

• macOS：skywalking-go-agent--darwin-amd64

• Linux: skywalking-go-agent--linux-amd64

• Windows： skywalking-go-agent--windows-amd64

ステップ 2：Go プロジェクトでのインストルメンテーションの有効化

Go プロジェクトを開き、次のいずれかの方法でインストルメンテーションを有効にします。inject コマンドがエラーを返す場合は、代わりに main パッケージに skywalking モジュールをインポートしてください。

package main
import (
    _ "github.com/apache/skywalking-go"
)

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

ステップ 3：接続パラメータの設定

ステップ 1 でダウンロードした skywalking-go リポジトリから skywalking-go/tools/go-agent/config/config.default.yaml をコピーして、独自の config.yaml ファイルとして保存し、エージェントを Managed Service for OpenTelemetry に接続するために次のパラメーターを設定します。

agent:
  service_name: ${SW_AGENT_NAME:<your-service-name>}
reporter:
  grpc:
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:<your-endpoint>}
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:<your-auth-token>}

• service_name: サービス名です。<your-service-name>を、お使いのアプリケーション名に置き換えます。

• backend_service: エンドポイントです。<your-endpoint> を エンドポイントの取得でコピーしたエンドポイントに置き換えます。

• authentication: エンドポイントの認証トークン。<your-auth-token> をご自身のトークンに置き換えてください。

残りのエージェントパラメータ、設定方法、およびデフォルトの設定ファイルについては、「skywalking-go エージェントの詳細設定」をご参照ください。

ステップ 4：プロジェクトの再ビルドと起動

プロジェクトを再ビルドし、-toolexec フラグを使用して Go コンパイラにエージェントを渡します：

# -toolexec を使用する必要があります
sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

• path/to/skywalking-go-agent: ステップ 1 でビルドした実行可能ファイルの絶対パスです。

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

プロジェクトを起動します。その後、SkyWalking データが Managed Service for OpenTelemetry コンソールにレポートされます。

ステップ 1：接続パラメータの設定

Go2Sky は 2 つの設定方法をサポートしています。プロジェクトにパラメータをハードコードするか、環境変数を使用して自動的に設定することが可能です。

// reporter.WithAuthentication() を使用して認証トークンを設定
report, err := reporter.NewGRPCReporter(
    <your-backend-server-address>,
    reporter.WithAuthentication(<your-auth-token>))

# 方法 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 リポジトリをご参照ください。各プラグインフォルダの README.md ファイルには、基本的な使用例が記載されています。

gin フレームワークのフックを追加するには、次の操作を実行します。

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

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

次の例は、フックのマウント方法を示しています。Managed Service for OpenTelemetry にデータをレポートする前に、ログレポーターを gRPC レポーターとステップ 1 およびステップ 2 で設定したサービス名に置き換えてください。

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("new reporter error %v \n", err)
    }
    defer re.Close()
    tracer, err := go2sky.NewTracer("gin-server", go2sky.WithReporter(re))
    if err != nil {
        log.Fatalf("create tracer error %v \n", err)
    }
    gin.SetMode(gin.ReleaseMode)
    r := gin.New()
    // トレーシングで go2sky ミドルウェアを使用
    r.Use(v3.Middleware(r, tracer))
    // 何かを実行
}

ステップ 4：アプリケーションの再起動

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

パラメータの設定方法

skywalking-go エージェントパラメーターを設定するには 2 つの方法があります。 次の例では、service_name を設定します。

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

export SW_AGENT_NAME=<your_service_name>

プラグインの除外

デフォルトでは、skywalking-go エージェントはすべてのプラグインを自動的に計測します。特定のプラグインを除外するには、excluded パラメーターを設定します。

# sql プラグインを除外する場合
plugin:
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
# 複数のプラグインを同時に除外する場合は、カンマで区切ります
plugin:
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

デフォルト設定ファイル

以下に、skywalking-go エージェントの完全な 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:
  # type は、システムが現在使用しているロギングタイプを決定します。
  # Go エージェントは、このログタイプを使用してカスタムログを生成します。サポートされるタイプ：「auto」、「logrus」、または「zap」。
  # auto：ログのソースを自動的に識別します。
  #       プロジェクトに logrus が存在する場合、自動的に logrus を使用します。
  #       プロジェクトで zap が初期化されている場合、zap フレームワークを使用します。
  #       デフォルトでは、std エラーを使用してログコンテンツを出力します。
  # 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}

skywalking-go の環境変数

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

Go2Sky の環境変数

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

skywalking-go の inject コマンドがバージョンエラーを返す

skywalking-go を使用すると、次のエラーが発生します。

U-VF4VY9W5-1944:skywalking-go-test whlongxi$ skywalking-go/bin/skywalking-go-agent-darwin-amd64 -inject ../skywalking-go-test -all
2023/08/09 16:55:59 version is empty, please use the release version of skywalking-go

inject メソッドを使用してエラーが発生した場合は、main パッケージに skywalking モジュールをインポートしてください。

Go2Sky 経由でデータをレポートする際にクロスプロセス トレースが正しく表示されない

エンドツーエンドのトレーシングは、HTTP リクエストで伝達されるトレース ID を使用してトレースを接続します。トレースが正しくない場合、トレース ID が正しく伝播されていないことを意味します。そのため、スパンを適切に設定する必要があります。次の 2 つのインターフェイスを使用して、クロスプロセス呼び出しを単一のトレースに接続します。

• CreateEntrySpan：エントリスパン。このインターフェイスを使用して、HTTP リクエストからトレース ID を含むトレースコンテキストを抽出します。

• CreateExitSpan: Exit スパン。このインターフェイスを使用して、トレース ID を含むトレースコンテキストを HTTP リクエストに挿入します。

// プロセス内では、CreateLocalSpan を使用してスパンを作成します。
span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
// プロセス間では、エントリスパン CreateEntrySpan を使用して HTTP リクエストからコンテキストを抽出し、終了スpan 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 リクエストにインジェクトし、リクエストとともにプロセス間で渡す必要があります。