銀の光と碧い空

クラウドなインフラとC#なアプリ開発の狭間にいるエンジニアの日々

公開スライドをSlideshareからドクセルに移しています

今まで登壇資料などはSlideShareに公開していたのですが、徐々にドクセルに移しています。

www.docswell.com

一時期、docs.com を利用したこともあったのですが、サービス終了したこともありSlideShareを使い続けていました。が、買収により所有企業がころころ変わり、最近では一部の機能が有償化しているようです。一番懸念しているのが、どの機能が有償なのか、資料を公開する側が払うのか、資料を閲覧する側が払うのか明確でないということです。 基本的にはSlideShareで使っていた機能が使えることが条件だったのですが、例えばこんな機能です。

  • はてなブログなどへの埋め込みができる。できるだけ手順が簡単なのが望ましい。 => はてなブログではURLをコピぺしてページ埋め込みモードで下のように埋め込めます。
  • PPTXもしくはPDFがアップロード可能
  • スライド内のハイパーリンクが動くこと
  • 資料のページでTwitterへのシェアが可能なこと

www.docswell.com

加えて、ドクセルでは同じリンクのまま資料を更新することが可能です*1。また、ページを指定したURLハッシュに対応しているので、指定したページに直接飛ばすこともできます。

https://www.docswell.com/s/tanaka_733/KE17N5-202202-open-telemetry-net-handson#p3

実際に移行するときに気になるのがSlideShareに公開済みの既存の資料の移行ですが、ドクセルでは手順が公開されています。

www.docswell.com

SlideShareのExport機能を使うわけですが、SlideShareでのダウンロードはExport機能で出力されたURLをクリックするとWebページ内で(クライアントブラウザ内で)リダイレクトされたうえで、ファイル保存ダイアログが開く仕様になっています。つまり、プログラミングでの自動化がやりづらくなっています。なおかつ、このときのデフォルトファイル名がタイトルなどとは関連しないわかりづらいものになることがあり、ファイル数が多いとこの後の作業が非常にわかりづらい状況でした。

ドクセルではこのページに書いている通り、登録の代行もしていただけるとのことで、私も(声をかけていただいたこともあり)お願いしました。無事にすべて登録できており、まずは非公開ですべて保存されています。今後、確認しながら新しいものから順次公開しています。昨年公開した資料はすでにドクセルで公開済みにしました。

SlideShareに公開した資料は、今後デフォルトで課金されるなどなければそのままにするつもりですが、今後公開する資料はドクセルで公開する予定です。

*1:読み手が混乱するほど異なる資料をアップロードした場合は非公開になることもあると記載されています。妥当な対応だと思います。

OpenTelemetry .NETを理解する (5) HttpClientによる外部通信処理を計測する

前回はスパンに情報を追加しました。

tech.tanaka733.net

次にトレースをさらにスパンで区切ってどの処理に時間がかかっているか計測することにします。スパンは作業の単位で区切ります。原理的には1メソッド1スパンで記録することもできますが、計測のオーバーヘッドや分析のノイズになることから、意味のある作業の単位でスパンを作成するのがおすすめです。そして、トレースで注目したいボトルネックになりうる作業の単位としては、HTTPでの外部呼び出しやデータベースへの呼び出しが典型的です。そのため、OpenTelemetry .NETでもそれらのライブラリに対して自動計装する機能が用意されています。今回は、HttpClientによる外部呼び出しを自動計装する機能を紹介します。

最初のコードはこのような状態です。

app.MapGet("/external", async () =>
{
    var client = new HttpClient();
    var req = await client.GetAsync("http://httpbin.org/get");
    var res = await req.Content.ReadAsStringAsync();
    Console.WriteLine(res);
    return res;
});

app.MapGet("/external/error", async () =>
{
    var client = new HttpClient();
    var req = await client.GetAsync("http://httpbin.org/status/502");
    try
    {
        var res = await req.EnsureSuccessStatusCode().Content.ReadAsStringAsync();
        Console.WriteLine(res);
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }
});

HttpClientの自動計装については、次のようにASP.NET Coreの最初の設定時にAddHttpClientInstrumentationメソッドを呼び出すことで行います。そのため、個別のHttpClientの呼び出し部分に処理を追加する必要はありません。

builder.Services.AddOpenTelemetryTracing((builder) => builder
        .AddAspNetCoreInstrumentation()
        .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("Hello-Otel").AddAttributes(tags))
        //以下1行を追加する
        .AddHttpClientInstrumentation()
        .AddOtlpExporter(options => 
        {
            options.Endpoint = new Uri("https://otlp.nr-data.net:4317/");
            options.Headers = $"api-key={Environment.GetEnvironmentVariable("OTEL_API_KEY")}";
        })
    );

すると、/externalのエンドポイントは次のようにトレースが記録されます。HttpClientによる通信処理が1つの子スパンとして記録されています。これにより、全体の処理(親スパン)のうち、外部通信でどれだけかかっているかがわかります。また、レスポンスのステータスコードなどの情報がhttp.ではじまる属性として記録されています。

一方、external/error のエンドポイントは次のようにトレースが記録されます。通信処理が子スパンとして記録された上で、スパンの状態をエラーとして記録しているため赤く表示されています。

さて、子スパンはエラーとして記録されていますが、親スパンの側はエラーとしては記録されていません。これは外部通信処理がエラーであっても、必ずしも親スパンの状態がエラーになるべきではないからです。通信処理でエラーが発生した場合に親スパンもエラーとして記録したい場合、前回の記事で紹介した方法で記録することになります。

app.MapGet("/external/error", async () =>
{
    var client = new HttpClient();
    var req = await client.GetAsync("http://httpbin.org/status/502");
    try
    {
        var res = await req.EnsureSuccessStatusCode().Content.ReadAsStringAsync();
        Console.WriteLine(res);
    }
    catch (Exception e)
    {
        var activity = Activity.Current;
        activity?.SetTag("otel.status_code", "ERROR");
        activity?.SetTag("otel.status_description", "required service is down.");
        activity?.RecordException(e);
    }
});

これで親スパンもエラーとして記録されるようになります。

OpenTelemetry .NETを理解する (4) Spanに情報を追加する

今回は、第2回目で計装したコードを基に、計測したSpanに情報を追加してみます。

tech.tanaka733.net

以下のコードを出発点にします。

app.MapGet("/weatherforecast", (ILogger<Program> logger, HttpContext context) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
       new WeatherForecast
       (
           DateTime.Now.AddDays(index),
           Random.Shared.Next(-20, 55),
           summaries[Random.Shared.Next(summaries.Length)]
       ))
        .ToArray();
    try
    {
        throw new Exception("error!!!!");
    }
    catch (Exception e)
    {
        logger.LogError(e, "error happened");
    }
    logger.LogInformation("Response1 length: {Length}", forecast.Length);
    return forecast;
})
.WithName("GetWeatherForecast");

今回の操作はOpenTelemetry .NETのドキュメントではここに記述されています。

opentelemetry.io

SpanとActivity

.NET には従来 System.Diagnostics.Activityという診断のために利用できるクラスがあります。

docs.microsoft.com

OpenTelemetry .NETでは(他の言語のOpenTelemetry実装と異なり)この言語備え付けの Activityを内部で利用しており、Activityを操作することでOpenTelemetryの計測も操作できるようになっています。この記事ではActivityクラスを使って操作する方法を紹介します。OpenTelemetryの仕様にもとづいたAPIで操作する方法もあり、そちらはOpenTelemetry Tracing Shimとして紹介されています。

Manual Instrumentation | OpenTelemetry

かんたんにいうと、ActivityとSpanは「計測するために区切られたある作業の単位」という同じ概念を表しています。

現在のSpanを取得する

第2回で紹介したASP.NET Coreで自動計装を適用している場合、Spanに情報を追加するためにはまず現在記録しているSpanを取得する必要があります。これはActivity.Currentプロパティで取得することが可能です。なお、計測していない場合などにnullが返る可能性があります。

app.MapGet("/weatherforecast", (ILogger<Program> logger, HttpContext context) =>
{
    var activity = Activity.Current;
    //以下略
}

タグを追加する

OpenTelemetryのSpanにはタグとよばれるキー・値のペアを追加することができます。タグの重要性については先日のObservability Conferenceの資料にも書いています。

tech.tanaka733.net

タグはActivity.SetTagメソッドで追加できます。

app.MapGet("/weatherforecast", (ILogger<Program> logger, HttpContext context) =>
{
    var activity = Activity.Current;
    activity?.SetTag("operation.value", 1);
    activity?.SetTag("operation.name", "Saying hello!");
    //以下略
}

イベントを追加する

Spanにイベントを追加することができます。イベントはTimestampと文字列情報およびキー値のペアを持つことができます。これはActivity.AddEventにActivityEventオブジェクトを渡して追加できます。ActivityEventのコンストラクタでこれらの情報を指定しますが、Timestampはデフォルトで現在時刻になるので、通常は指定しないことになります。

app.MapGet("/weatherforecast", (ILogger<Program> logger, HttpContext context) =>
{
    var activity = Activity.Current;
    activity?.SetTag("operation.value", 1);
    activity?.SetTag("operation.name", "Saying hello!");

    var spanTags = new ActivityTagsCollection(new KeyValuePair<string, object?>[]
        {
            new ("mode", "normal"),
            new ("speed", 10),
        });
    activity?.AddEvent(new ActivityEvent("Start", tags: spanTags));

    var forecast = Enumerable.Range(1, 5).Select(index =>
       new WeatherForecast
       (
           DateTime.Now.AddDays(index),
           Random.Shared.Next(-20, 55),
           summaries[Random.Shared.Next(summaries.Length)]
       ))
        .ToArray();
    
    activity?.AddEvent(new ActivityEvent("End"));
    logger.LogInformation("Response1 length: {Length}", forecast.Length);
    return forecast;
})
.WithName("GetWeatherForecast");

Spanの状態を設定する

これもObservability Conferenceにて発表したことにつながりますが、処理の中で異常な状態になった(通常例外が発生した)のであれば、Spanの状態もエラーとマークすべきです。これにより分析が可能になります。Activity.SetStatusというメソッドがあるのでこれで設定できるはずなのですが、現時点ではまだこのAPIを呼び出してもOpenTelemetry側のSpanの状態がマークされません。

try
    {
        throw new Exception("error!!!!");
    }
    catch (Exception e)
    {
        //これは現時点ではOpenTelemetry側に作用しない
        activity?.SetStatus(ActivityStatusCode.Error, "error happened.");
        
        logger.LogError(e, "error happened");
    }

この問題は以下のIssueで議論されています。

github.com

現時点ではotel.status_codeotel.status_descriptionを使って手動でタグとして設定します。また、例外オブジェクトを記録したい場合、Activity.RecordExceptionを使うと例外オブジェクトを格納したイベントを追加してくれます。したがってcatch節に書くであろうコードはこうなります。

    try
    {
        throw new Exception("error!!!!");
    }
    catch (Exception e)
    {
        activity?.SetTag("otel.status_code", "ERROR");
        activity?.SetTag("otel.status_description", "error happened.");
        activity.RecordException(e);
        logger.LogError(e, "error happened");
    }

まとめ

以上でコードはこのようになります。

app.MapGet("/weatherforecast", (ILogger<Program> logger, HttpContext context) =>
{
    var activity = Activity.Current;
    activity?.SetTag("operation.value", 1);
    activity?.SetTag("operation.name", "Saying hello!");

    var spanTags = new ActivityTagsCollection(new []
        {
            new KeyValuePair<string, object?>("mode", "normal"),
            new KeyValuePair<string, object?>("speed", 10),
        });
    activity?.AddEvent(new ActivityEvent("Start", tags: spanTags));
    var forecast = Enumerable.Range(1, 5).Select(index =>
       new WeatherForecast
       (
           DateTime.Now.AddDays(index),
           Random.Shared.Next(-20, 55),
           summaries[Random.Shared.Next(summaries.Length)]
       ))
        .ToArray();
    try
    {
        throw new Exception("error!!!!");
    }
    catch (Exception e)
    {
        // このコードは https://github.com/open-telemetry/opentelemetry-dotnet/issues/2569 によりOpenTelemetry側に作用しない
        //activity?.SetStatus(ActivityStatusCode.Error, "error happened.");
        activity?.SetTag("otel.status_code", "ERROR");
        activity?.SetTag("otel.status_description", "error happened.");
        activity.RecordException(e);
        logger.LogError(e, "error happened");
    }
    activity?.AddEvent(new ActivityEvent("End"));
    logger.LogInformation("Response1 length: {Length}", forecast.Length);
    return forecast;
})
.WithName("GetWeatherForecast");

これを実行するとバックエンドで追加した情報が見えるようになります。New RelicであればSpanの状態をエラーにすると下のように赤色になります。

f:id:tanaka733:20220319233423p:plain

また属性が追加されていることもわかります。

f:id:tanaka733:20220319233300p:plain

View Span eventsというリンクをクリックするとSpanに追加したイベントの一覧が確認できます。Spanイベントに追加したタグや例外オブジェクトも確認できます。

f:id:tanaka733:20220319233529p:plain

f:id:tanaka733:20220319233552p:plain

さて、OpenTelemetry .NETのドキュメントには子スパンの作成とSpanのLinkの機能も紹介されていますが、これは改めて紹介したいと思います。