nsTelemetry – README.md (2.2.0)

このページは、github.comに登録されているnsTelemetryのREADME.mdを日本語化したものです。英語版は、github.comを参照してください。

このページの内容は、nsTelemetry 2.2.0 相当の内容が翻訳されています。

nsTelemetryの日本語トップページへ戻る

NishySoftware.Telemetry.ApplicationInsights

Development status

Build Status (develop) Build Status (master)

Downloads NuGet NuGet (pre) Release License

Issues Issues Pull Requests Pull Requests

About

このライブラリーはPCアプリの使用状況や例外の発生状況を計測するためのテレメトリー情報を送信する機能をPCアプリに提供します。
このライブラリーのテレメトリー情報の送信先は、Azure Application Insightとなります。PCアプリから使いやすいようにApplicationInsightsのAPIをラップしたライブラリーとなります。PCアプリは、WindowsおよびLinuxを想定しています。

Azure Application Insightsでのアプリの使用状況タイムラインのグラフ例

インストール方法 (Installation)

NuGetパッケージをインストールします。 

PM> Install-Package NishySoftware.Telemetry.ApplicationInsights

使い方 (How to use)

nsTelemetry (NishySoftware.Telemetry.ApplicationInsights)

このライブラリーは、静的TelemetryクラスとITelemetryインターフェースを提供します。
Telemetryクラスのすべての公開メソッドは、静的メソッドとして公開されます。
Telemetryクラスは、全体的な設定とITelemetryインターフェースのインスタンスの作成ができます。
ITelemetryインターフェース は、テレメトリーデータの設定とテレメトリーの送信ができます。

準備 (Prepare)

  1. AzureポータルからInstrumentationKeyを取得します
    1. まだAzureアカウントを持っていない場合は、Azureポータルにアクセスして、アクティブなサブスクリプションを持つアカウントを作成してください。 無料でアカウントを作成
    2. Azure ポータルで Application Insight リソースを作成します。詳しくは、マイクロソフト社のサイトをご参照ください。
    3. 新しく作成したリソースページの「概要」ペインに表示されているInstrumentationKeyを取得します。
  2. このnugetライブラリ(NisySoftware.Telemetry.ApplicationInsights)を対象とするアプリのプロジェクトにインストールします。
  3. プロジェクトをビルドすると、ApplicationInsights.configファイルがプロジェクトに追加されます。
  4. ApplicationInsights.configファイルのInstrumentationKeyタグの内容に、Azureポータルで取得したInstrumentationKeyを設定します。
    ApplicationInsights.configファイルにInstrumentationKeyを設定したくない場合は、ソースコード内で指定することもできます。

実装 (Implementation)

  1. 必要に応じてグローバル 共通 テレメトリー データ (プロパティ/メトリック)を設定します。
  2. ApplicationInsights.configファイルにInstrumentationKeyを設定していない場合は、SetInstrumentationKey()を使用してInstrumentationKeyを設定します。
  3. ITelemetryのインスタンスを作成します。
  4. 必要に応じてグローバル カスタム テレメトリー データ（プロパテ）を設定します。
  5. 必要に応じてEnableDeveloperMode()でDeveloperModeを設定します。
  6. ITelemetryインターフェースのTrackEvent() / TrackPageView() / TrackException()メソッドを使用してテレメトリーを送信します。

Example

namespace nsTelemetryAI.Sample
{
    using NishySoftware.Telemetry;
    using System;
    using System.Threading;
    using System.Threading.Tasks;

    class Program
    {
        #region Fields
        DateTime _startupDateTime = DateTime.UtcNow;
        bool _sentEventExit = false;
        #endregion Fields

        #region Properties

        #region Telemetry
        static ITelemetry _telemetry;
        public static ITelemetry Telemetry
        {
            get
            {
                return LazyInitializer.EnsureInitialized<ITelemetry>(ref _telemetry, () =>
                {
                    // [ja] TelemetryDataFlags は、初回は時間がかかるので、非同期で設定する。
                    Task.Run(() =>
                    {
                        // [ja] 共通グローバルプロパティをセットアップする
                        NishySoftware.Telemetry.ApplicationInsights.Telemetry.CommonDataKinds = TelemetryDataKinds.All;
                    });

                    // [ja] ApplicationInsights.configファイルにInstrumentationKeyを配置していない場合は、SetInstrumentationKey()を使用してInstrumentationKeyを設定します。
                    // NishySoftware.Telemetry.ApplicationInsights.Telemetry.SetInstrumentationKey("your InstrumentationKey");

                    // [ja] テレメトリーインターフェースのインスタンスを作成する
                    var telemetry = NishySoftware.Telemetry.ApplicationInsights.Telemetry.CreateTelemetry();

                    // [ja] 必要ならカスタムグローバルプロパティを追加する
                    var userDomainName = Environment.UserDomainName;
                    lock (telemetry.GlobalSyncObject)
                    {
                        var prop = telemetry.GlobalProperties;
                        if (!prop.ContainsKey("UserDomainName"))
                        {
                            prop.Add("UserDomainName", userDomainName);
                        }
                    }
#if DEBUG
                    // [ja] 必要なら、デバッグ版のときに、非同期送信を利用する
                    NishySoftware.Telemetry.ApplicationInsights.Telemetry.EnableDeveloperMode(false);
#endif

                    return telemetry;
                });
            }
        }
        #endregion

        #endregion Properties

        #region Methods
        void TrackEventStartup(string[] startupArgs)
        {
            _startupDateTime = DateTime.UtcNow;
            Telemetry.TrackEvent("App_" + "General" + "Startup",
                "Command", startupArgs.Length > 0 ? startupArgs[0] : null);
        }

        void TrackEventExit(int exitCode)
        {
            if (!this._sentEventExit)
            {
                this._sentEventExit = true;
                var exitDateTime = DateTime.UtcNow;
                double duration = (exitDateTime - _startupDateTime).TotalSeconds;
                Telemetry.TrackEvent("App_" + "General" + "Exit",
                    "Duration", duration,
                    "ExitCode", exitCode.ToString());
                Telemetry.Flush();
                // [ja] Telemetry.Flush()を呼び出した後は少し待ちます。
                Thread.Sleep(1000);
            }
        }
        #endregion Methods

        static void Main(string[] args)
        {
            var program = new Program();

            program.TrackEventStartup(args);

            Console.WriteLine("Hello World!");

            program.TrackEventExit(Environment.ExitCode);
        }
    }
}

nsTelemetry API リファレンス

nsTelemetryAI のAPIリファレンスはnsTelemetry.md ファイルとnsTelemetryAI.md ファイルにあります。

このnsTelemetry.mdとnsTelemetryAI.mdは、英語と日本語が併記なため、github.comのファイルを参照してください。

名前空間 : NishySoftware.Telemetry

名前空間 : NishySoftware.Telemetry.ApplicationInsights

構成ファイル (ApplicationInsights.config)

nsTelemetryは構成ファイルとしてApplicationInsights.configファイルを使用します。
ApplicationInsights.config ファイルの仕様はオリジナルの仕様(英語) から少し拡張されています。

  • InstrumentationDevKey タグ
    このタグは、開発時に使用することを目的としています。このタグの値は、開発者モードまたはプロセスにデバッガがアタッチされているときに、InstrumentationKeyタグの値の代わりに使用されます。
  • Windows以外の環境でのServerTelemetryChannelのStorageFolderプロパティ
    ServerTelemetryChannelをWindows以外の環境で使用する場合、ApplicationInsights.configファイルにStorageFolderプロパティ(英語)を明示的に指定する必要があります。
    本ライブラリを使用する場合は、StorageFolderプロパティを明示的に指定する必要はありません。StorageFolderプロパティが指定されていない場合は、本ライブラリの適切な値が設定されます。

ライセンス (License)

このライブラリーは、Apache License Version 2.0 で提供されいます。

nsTelemetryの日本語トップページへ戻る