トラブルシューティング

アプリケーションへの Go コレクターの統合が正しく行われているかを確認するには、以下の手順に従ってください：

1. Go コレクターを初期化する

   アプリケーションの開始時に、 InstanaInitCollector パッケージの関数を使用して、 Go コレクタを初期化する必要があります：

   import (
       instana "github.com/instana/go-sensor"
   )
   
   func main() {
       // Initialize the collector with service name and other options
       collector := instana.InitCollector(&instana.Options{
           Service:           "your-service-name",
           EnableAutoProfile: true,
           Tracer:            instana.DefaultTracerOptions(),
       })
   
       // Your application code here
   }

   主な設定オプション：

   • Service (必須)： Instana に表示されるサービスの名前。
   • EnableAutoProfile （オプション）：自動プロファイリング機能を有効にします。
   • Tracer (オプション)：トレースオプションを設定します。
2. コレクターの接続を確認してください

   初期化が完了したら、アプリケーションのログを確認し、接続に関する問題がないか確認してください。 コレクターが Instana エージェントに正しく接続されていれば、エラーメッセージは表示されません。

3. 計測ライブラリを使用する

   包括的な監視を行うには、 Instana の計測ライブラリを使用して、アプリケーションの特定のコンポーネントを計測してください。 これらのライブラリは、スパンを作成し、さまざまな操作に関するメトリクスを収集します。

   Instana Go の人気パッケージ向けに、いくつかの計測ライブラリを提供しています。

   詳細については、以下の利用可能な計測ライブラリを参照してください：

   • HTTP サーバーの監視
   • SQLベースのデータベース監視
   • GraphQL 計装
   • Redis 計装
   • MongoDB 計装
   • Kafka 計装
   • その他の計測パッケージ
4. 適切な環境変数を設定する

   デプロイメントのシナリオに合わせて、必要な環境変数がすべて正しく設定されていることを確認してください。 環境変数が欠落していたり、誤って設定されていたりすると、 Instana Go のトレーサーの動作に影響を与え、監視が不完全になったり、設定上の問題が発生したりする可能性があります。

   必要な環境変数とその設定に関する詳細については、 「 Go コレクターの設定」 のセクションを参照してください。

ネットワークの問題を解決するには、以下の手順でトラブルシューティングを行ってください

• Go プロセスが、同じホスト上のホストエージェントにポート42699経由で接続できることを確認してください。 必要なネットワーク可視性に関する詳細については、「 Instana ホストエージェントのネットワーク要件 」を参照してください。

• コンテナ化されたプラットフォームでは、トレース対象のアプリケーションが実行されているコンテナと、 Instana ホストエージェントが実行されているコンテナ間のネットワーク接続を確認してください。 トレース対象のアプリケーションコンテナが、同じホスト上の Instana エージェントコンテナに接続しようとする際、オーバーレイネットワークの設定に問題がないことを確認してください。

• Go コレクターが、 Instana エージェントと通信するために正しいIPアドレスまたは DNS 名を使用していることを確認してください。 ネットワークアドレスを変更する必要がある場合は、 GoINSTANA_AGENT_HOST コレクターに環境変数を使用するよう指示できます。

• ホストエージェントがポート 42699 でリスニングしていることを確認してください。 ホストエージェントがポート 42699 ではなく別のポートでリスニングしているためにポートの再マッピングが必要な場合は、環境 INSTANA_AGENT_PORT 変数を使用して、コレクターが別のポートを使用するように設定できます。

上記の解決策のいずれも問題が解決しない場合は、 サポートチケットをご提出ください。

コンテキスト伝播とは、アプリケーションの異なるコンポーネント間でトレース情報を渡す仕組みのことです。 Go センサーでは、この伝播は主に Go のcontextパッケージを通じて、 instana.SpanFromContext() および instana.ContextWithSpan() を使用することで実現されています。

次の例は、 HTTP エンドポイントからSQLデータベース操作へコンテキストを正しく伝播させる方法を示しています：

import (
    "fmt"
    "io"
    "net/http"

    _ "github.com/go-sql-driver/mysql"
    instana "github.com/instana/go-sensor"
)

func main() {
    // Initialize the Instana collector
    col := instana.InitCollector(&instana.Options{
        Service: "your-service-name",
        Tracer:  instana.DefaultTracerOptions(),
    })

    // HTTP handler with SQL database operation
    http.HandleFunc("/api/users", instana.TracingHandlerFunc(col, "/api/users", func(w http.ResponseWriter, req *http.Request) {
        // Open an instrumented database connection
        db, err := instana.SQLInstrumentAndOpen(col, "mysql", "user:password@tcp(localhost:3306)/mydb")
        if err != nil {
            http.Error(w, "Database connection failed", http.StatusInternalServerError)
            return
        }
        defer db.Close()

        // The request context already contains the span from the HTTP handler
        ctx := req.Context()

        // Use the same context for the database query to maintain the trace
        rows, err := db.QueryContext(ctx, "SELECT id, name FROM users LIMIT 10")
        if err != nil {
            http.Error(w, "Query failed", http.StatusInternalServerError)
            return
        }
        defer rows.Close()

        // Process the query results
        var result string
        for rows.Next() {
            var id int
            var name string
            if err := rows.Scan(&id, &name); err != nil {
                continue
            }
            result += fmt.Sprintf("User: %d - %s\n", id, name)
        }

        io.WriteString(w, result)
    }))

    http.ListenAndServe(":8080", nil)
}

以下のベストプラクティスを遵守する必要があります：

• 常にコンテキストを渡す ：spanを含むコンテキストを、コンテキストをサポートするすべての操作に渡してください。

• コンテキスト認識型メソッドを使用する ：データベースや計測対象の QueryContext クライアントメソッドなど、コンテキストパラメータを受け取るメソッドを使用します。

• スパンを適切に抽出および挿入する ：手動による計測を行う際は、スパンを抽出するには を、挿入 ContextWithSpan() するには SpanFromContext() を使用してください。

• ゴルーチン間でコンテキストを維持する ：ゴルーチンを作成する際は、トレースの連続性を確保するためにコンテキストを渡してください。

• 計測ライブラリの確認 ： Redis、 MongoDB,、SQLデータベースなどの一般的なパッケージについては、 Instana の計測ライブラリを使用してください。これらはコンテキストの伝播を自動的に処理します。

以下の間違いは避ける必要があります：

• リクエストから取得したコンテキストを使用する代わりに、新しいコンテキストを作成する。
• コンテキストをサポートしている操作に対して、そのコンテキストを渡さない。
• コンテキスト対応の代替手段があるにもかかわらず、コンテキスト非対応の手法を使用すること。
• サービス境界を越える際にコンテキストが失われる。

これらのガイドラインに従うことで、分散トレースが適切に連携され、アプリケーションのパフォーマンスを完全に可視化できるようになります。

最適なパフォーマンスと最新機能を利用できるようにするため、 Instana Go Tracer SDK の最新バージョンを使用していることを確認してください：

1. 現在のバージョンを確認するには、ファイル go.mod を確認してください：

   require (
       github.com/instana/go-sensor v1.x.y
   )

   GitHub または「 サポートされているランタイム 」セクションで入手可能な最新バージョンと比較してください。

2. 必要に応じて最新バージョンに更新してください：

   go get -u github.com/instana/go-sensor

Instana Go Tracer SDKは、特定のバージョンの Go と連携するように設計されています。 互換性を次のように確認してください：

1. お使いの Go のバージョンを確認してください：

   go version

2. お使いの Go のバージョンが、 Instana Go Tracer SDKのバージョンと互換性があることを確認してください。

互換性のある最新バージョンを使用することで、 Instana Go Tracer SDK における多くの一般的な問題を回避し、最新の機能や改善点を活用することができます。

デバッグログを収集するには、以下の手順を実行してください：

1. 以下の環境変数を設定して、デバッグログを有効にしてください：

   export INSTANA_DEBUG=true
   export INSTANA_LOG_LEVEL=debug
    

2. アプリケーションを再起動し、問題を再現してください。

3. デバッグ情報を含むアプリケーションログを収集してください。

さまざまなホスト環境からエージェントのログを収集するには、以下のセクションを参照してください：

ご利用の環境について、以下の情報を収集してください：

• アプリケーションのデプロイメントタイプ：

  • Kubernetes （バージョンおよび配布形態を含む）
  • Docker （バージョンを含める）
  • 仮想マシン
  • ベア・メタル
  • サーバーレス（ AWS Lambda、 Google、 Cloud Functions、およびその他のクラウドサービス）

• OSの詳細：

  • Linux
  • macOS
  • Windows
  • その他のOS
• Go 実行時のバージョン：バージョンを確認するには、次のコマンドを実行してください：

  go version
   

• Instana Go 使用中のTracer SDKのバージョン：バージョンを確認するには、次のコマンドを実行してください：

  # Extract Instana Go Tracer SDK version
  grep "github.com/instana/go-sensor" go.mod > go-sensor-version.txt

• 使用している Go のTracer計測ライブラリの名称とバージョン：

  github.com/instana/go-sensor/instrumentation/instasql v1.x.y
  github.com/instana/go-sensor/instrumentation/instaredis v1.x.y
  # etc.

  ライブラリを抽出するには、次のコマンドを実行してください：

  # Extract instrumentation libraries
  grep -r "github.com/instana/go-sensor/instrumentation" go.mod >> instrumentation-library-versions.txt