Instana ベースイメージを使用した Docker での.NET トレースの設定

オンラインで編集する

Instana .NET のベースイメージ（トレースエージェントが組み込まれているもの）を使用することで、コンテナ化された.NET アプリケーションにおけるトレース設定を簡素化できます。

Instana .NET ベースイメージは、Microsoftの公式.NET ランタイムイメージをベースにした、あらかじめ設定済みの Docker イメージです。 これらには Instana トレースエージェントが含まれており、計測ツールはあらかじめインストールおよび設定済みの状態で提供されます。

重要：Instana .NET のベースイメージは、.NET Core Tracer 1.319.7 以降から入手可能です。

手動での設定については、 Docker の「.NET のトレースを手動で設定する 」をご覧ください。

主な機能

オンラインで編集する

Instana .NET のベースイメージには、以下のものが含まれます：

  • プリインストール済み Instana .NET Core Tracer
  • あらかじめ設定済みのプロファイラ環境変数
  • マルチアーキテクチャ対応（ amd64 および arm64 ）
  • 複数のOSバリエーション（ Alpine、 Ubuntu Noble、および Ubuntu Resolute）
  • .NET 10.0 実行時サポート
  • ゼロコードでの計測対応済み

前提条件

オンラインで編集する

Instana .NET のベースイメージを使用する前に、以下の前提条件が満たされていることを確認してください

  • Docker お使いのシステムにインストールされ、実行されています。
  • Instana のエージェントキーとエンドポイント URL をご用意ください。

.NET のトレースにベース画像を使用する

オンラインで編集する

コンテナ化されたアプリケーションで Instana .NET のベースイメージを使用するには、以下の手順を実行してください

  1. 用途に応じて、適切なベースイメージのバリエーションを選択してください。 オプションについては、「利用可能な画像バリエーション」 をご覧ください。
  2. Instana ベースイメージを使用するように Dockerfile を更新してください：
    FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-{variant}-{architecture}:{version}

    {variant} および {architecture} を、お使いの環境に適した値に置き換えてください。 {version} タグを使用する場合は、 を使用して latest 最新の画像バージョンを取得するか、特定のバージョン（例： 1.319.7）を指定して特定のリリースに固定してください。 詳細については、 「アーキテクチャのサポート 」および「 イメージの命名規則 」の各セクションを参照してください。

アプリケーションは、 Instana のトレース機能が有効な状態で実行され、トレースデータが自動的に Instana に送信されます。

例 1: シンプルな ASP.NET Core アプリケーション

オンラインで編集する

次の例は、 Instana ベースイメージを使用した、 ASP.NET Core の簡単なアプリケーションを示しています

Dockerfile:

# Use Instana base image with specific version
FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-alpine-amd64:1.319.7

# Copy published application
COPY ./publish /app

# Set entrypoint
ENTRYPOINT ["dotnet", "MyApp.dll"]

ビルドして実行：

# Build your application
dotnet publish -c Release -o ./publish

# Build Docker image
docker build -t myapp:latest .

# Run with Instana configuration
docker run -d \
  -e INSTANA_AGENT_KEY="your-instana-agent-key" \
  -e INSTANA_ENDPOINT_URL="serverless-end-point-url" \
  -e INSTANA_SERVICE_NAME=my-service \
  -p 8080:8080 \
  myapp:latest

例 2：SDK を使用した多段階ビルド

オンラインで編集する

以下の例は、多段階の Dockerfile を示しています：

Dockerfile:

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MyApp.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish

# Runtime stage with Instana (using specific version)
FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:1.319.7

# Or use latest tag to get the most recent version
# FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:latest

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

ビルドして実行：

# Build Docker image (this also builds your application)
docker build -t myapp:latest .

# Run with Instana configuration
docker run -d \
  -e INSTANA_AGENT_KEY="your-instana-agent-key" \
  -e INSTANA_ENDPOINT_URL="serverless-end-point-url" \
  -e INSTANA_SERVICE_NAME=my-service \
  -p 8080:8080 \
  myapp:latest

例 3：複数のサービスを含む ` Docker Compose `

オンラインで編集する

次の例は、 Docker Compose を使用して、 Instana のトレース機能を備えた複数のサービスを実行する方法を示しています

docker-compose.yml:

version: '3.8'

services:
  api-service:
    build:
      context: ./api
      dockerfile: Dockerfile
    image: myapp-api:latest
    environment:
      - INSTANA_ENDPOINT_URL=serverless-end-point-url
      - INSTANA_AGENT_KEY=your-instana-agent-key
      - INSTANA_SERVICE_NAME=api-service
    ports:
      - "8080:8080"

  worker-service:
    build:
      context: ./worker
      dockerfile: Dockerfile
    image: myapp-worker:latest
    environment:
      - INSTANA_ENDPOINT_URL=serverless-end-point-url
      - INSTANA_AGENT_KEY=your-instana-agent-key
      - INSTANA_SERVICE_NAME=worker-service

サービスの開始：

docker-compose up -d

設定値：

設定ファイル内の以下の値を置き換えてください：

  • your-instana-agent-key: Instana のエージェントキー
  • serverless-end-point-url: Instana のエンドポイント URL
  • my-service またはサービス名：あなたのサービス名

Instana や.NET のベースイメージを使う理由

オンラインで編集する

ベースイメージがない場合は、次の操作を行う必要があります：

  1. Dockerfile内で Instana や NuGet のパッケージを手動でダウンロードする
  2. CLR プロファイラ用の複雑な環境変数を設定する
  3. アーキテクチャ固有のプロファイラバイナリの取り扱い（ amd64 対 arm64 ）
  4. Alpine （musl-libc）と Ubuntu （glibc）の異なるプロファイラビルドを管理する
  5. この設定を複数のマイクロサービスに適用する

Instana .NET のベースイメージを使用すれば、設定済みのイメージをそのまま利用できます。

ベース画像の詳細

オンラインで編集する

ニーズに応じて、3種類のベース画像から選択できます。

利用可能な画像バリエーション

オンラインで編集する

以下の表は、利用可能な Instana .NET のベースイメージをまとめたものです：

表 1. Instana .NET ベース画像のバリエーション
異形体 基本イメージ C ライブラリー ユース・ケース サイズ
Alpine mcr.microsoft.com/dotnet/aspnet:10.0-alpine3.23 musl-libc 最小限のコンテナ、サイズが最適化されている 110 MB
Noble mcr.microsoft.com/dotnet/aspnet:10.0-noble glibc Ubuntu 24.04 LTS（ノーブル・ナンバット） 220 MB
断固たる mcr.microsoft.com/dotnet/aspnet:10.0-resolute glibc Ubuntu 25.04 (断固たるリングテイル) 220 MB

アーキテクチャのサポート

オンラインで編集する

各バリアントは以下をサポートしています：

  • amd64 ( x86_64 ): 標準的なIntelまたはAMDプロセッサ
  • arm64 ( aarch64 ): ARMプロセッサ（Apple Silicon、 AWS Graviton、およびその他のプロセッサ）

画像の命名規則

オンラインで編集する

画像名は次の形式に従います：

{registry}/dotnet-runtime-10.0-{variant}-{architecture}:{version}

バージョンタグのオプション：

  • を使用して latest 、最新の画像バージョンを自動的に取得します
  • 1.319.7特定のリリースに固定するには、特定のバージョン番号（例：）を使用してください

特定のバージョンを用いた例：

  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-alpine-amd64:1.319.7
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:1.319.7
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-resolute-amd64:1.319.7

「latest」タグが付いた例：

  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-alpine-amd64:latest
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:latest
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-resolute-amd64:latest

ディレクトリー構造

オンラインで編集する

ベースイメージには、以下のディレクトリ構造が含まれています：

/opt/instana/
├── lib/
│   └── Instana.Tracing.Core.dll          # Managed tracer library
└── profiler/
    ├── CoreProfiler.so                    # Native profiler (architecture-specific)
    └── instrumentation.json               # Instrumentation configuration

あらかじめ設定済みの環境変数

オンラインで編集する

すべてのベースイメージには、以下の事前設定済みの環境変数が含まれています：

表 2. あらかじめ設定済みの環境変数
変数 値 目的
CORECLR_ENABLE_PROFILING 1 CLRのプロファイリングを有効にします
CORECLR_PROFILER {CF0D821E-299B-5307-A3D8-B283C03916DD} Instana プロファイラー GUID
CORECLR_PROFILER_PATH /opt/instana/profiler/CoreProfiler.so ネイティブプロファイラのパス
DOTNET_STARTUP_HOOKS /opt/instana/lib/Instana.Tracing.Core.dll 管理対象トレーサーの起動フック

メリット

オンラインで編集する

ベースイメージを使用すると、手動でのセットアップに比べて大きな利点があります：

  • 手動設定は一切不要： NuGet パッケージのインストールや環境変数の設定は不要です
  • 一貫性のあるセットアップ：すべての環境で同一の設定
  • エラーの削減：よくある設定ミスを解消します
  • 導入の迅速化：事前設定済みのイメージにより、コンテナの起動が高速化されます
  • マルチアーキテクチャ対応：1つのDockerfileで異なるCPUアーキテクチャに対応
  • メンテナンスの簡素化： Instana による一元的なアップデート管理