Application Real-Time Monitoring Service:Go トレースデータの SkyWalking を介したレポート

ステップ 1: SkyWalking エンドポイントの取得

1. Managed Service for OpenTelemetry コンソールにログインします。

2. 左側のナビゲーションウィンドウで、[クラスタ設定] をクリックします。表示されるページで、[エンドポイント情報] タブをクリックします。

3. 上部ナビゲーションバーでリージョンを選択します。[クラスター情報] セクションで、[トークンを表示] をオンにします。

4. [クライアント] パラメーターを [SkyWalking] に設定します。

5. エンドポイントを、[関連情報] 列からコピーします。

ステップ 2: エージェントバイナリのビルド

skywalking-go エージェントをクローンしてビルドします。

git clone https://github.com/apache/skywalking-go.git
cd skywalking-go && make build

ビルドにより、skywalking-go/bin/ ディレクトリに実行可能ファイルが生成されます。ファイル名は OS によって異なります -- たとえば、macOS では skywalking-go-agent--darwin-amd64 です。

ステップ 3: プロジェクトへの SkyWalking モジュールの追加

次のいずれかの方法を選択してください。

package main

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

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

ステップ 4: エージェントの設定

少なくとも以下の3つのパラメーターを含むconfig.yaml ファイルを作成します。

agent:
  service_name: ${SW_AGENT_NAME:<your-service-name>}

reporter:
  grpc:
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:<your-skywalking-endpoint>}
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:<your-auth-token>}

プレースホルダーを実際の値に置き換えます。

これらの値を config.yaml に直接 (推奨)、または環境変数で設定します:

export SW_AGENT_NAME=my-go-service
export SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE=xxx.api.aliyuncs.com:11800
export SW_AGENT_REPORTER_GRPC_AUTHENTICATION=abcdef123456

plugin:
  # 単一のプラグインを無効にする
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}

  # 複数のプラグインを無効にする (カンマ区切り)
  # excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

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}

ステップ 5: プロジェクトの再ビルド

-toolexec フラグを使用して、エージェントのバイナリと設定ファイルを指定してコンパイルします：

sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

• path/to/skywalking-go-agent -- ステップ 2 でビルドされた実行可能ファイルへの絶対パス

• path/to/config.yaml -- ステップ 4 で作成された設定ファイルへの絶対パス

ステップ 6: アプリケーションの起動と検証

コンパイルされたバイナリを実行します。エージェントはサポートされているすべてのプラグインを自動的にイベントトラッキングし、gRPC 経由でトレースのレポートを開始します。

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

環境変数リファレンス

サポートされているプラグイン

skywalking-go エージェントは、コンパイル時に以下のライブラリを自動的にイベントトラッキングします。ライブラリごとのインストールは不要です。

ステップ 1: レポーターのセットアップ

パラメーターをハードコーディングするか、環境変数を設定して gRPC レポーターを設定します。

report, err := reporter.NewGRPCReporter(
    "<your-backend-server-address>",
    reporter.WithAuthentication("<your-auth-token>"))

# 永続的 -- シェルプロファイルに追加します
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
export SW_AGENT_AUTHENTICATION=<your-auth-token>

# その後、アプリケーションを起動します (エージェントはこれらの変数を自動的に読み取ります)

ステップ 2: トレーサーの作成

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

ステップ 3: プラグインフックの追加

Go2Sky は、イベントトラッキングされた各ライブラリにフックを必要とします。GitHub の go2sky-plugins リポジトリをご参照ください。各プラグインフォルダーには、統合手順が記載された README が含まれています。

例 -- gin フレームワーク:

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: アプリケーションの再起動

フックを追加した後、アプリケーションを再起動します。トレースが Managed Service for OpenTelemetry コンソールに流れ始めます。

サポートされているプラグインライブラリ

各プラグインには go get による個別のインストールが必要です：

環境変数リファレンス

skywalking-go のインジェクションコマンドが失敗した場合の対処法

-inject メソッドが失敗した場合は、代わりにメインパッケージに SkyWalking のインポートを直接追加します:

import _ "github.com/apache/skywalking-go"

次に、手順 5で説明されているように、-toolexec を使用して再構築します。

Go2Sky を使用したプロセス間呼び出しで、コンソールにトレースが切断されて表示されるのはなぜですか？

Managed Service for OpenTelemetry は、HTTP ヘッダーで伝達されるトレース ID によってスパンを関連付けます。サービス間でトレースが切断されて表示される場合、トレースコンテキストが正しく伝播されていません。

これを修正するには、HTTP 境界を越えてトレースコンテキストを伝播するエントリスパンとイグジットスパンを作成します。

// CreateEntrySpan -- 受信 HTTP リクエストからトレースコンテキストを抽出します
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
    return r.Header.Get(key), nil
})

// CreateExitSpan -- 送信 HTTP リクエストにトレースコンテキストを注入します
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
    req.Header.Set(key, value)
    return nil
})

インプロセススパン (ネットワーク境界がない場合) には、 CreateLocalSpan を使用します:

span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)

プロセス境界を越えるすべての HTTP 呼び出しは、トレースコンテキストを保持する必要があります。各境界で CreateEntrySpan および CreateExitSpan を使用しない場合、ダウンストリームサービスは新しい切断されたトレースを開始します。