注意

SignalFx Instrumentation for .NETは、2024年2月21日をもって非推奨となり、2025年2月21日にサポート終了となります。それまでは、重要なセキュリティ修正とバグ修正のみが提供されます。それ以降は、ライブラリはアーカイブされ、保守されなくなります。

新規に .NET エコシステムをインストルメンテーションするお客様は、Splunk Distribution of OpenTelemetry .NET をご利用ください。既存のお客様は、同様の機能を提供する Splunk Distribution of OpenTelemetry .NET への移行をご検討ください。移行方法については、SignalFx .NET Instrumentationからの移行を参照してください。

Splunk Observability Cloud で .NET トレースデータとログを接続する 🔗

SignalFx Instrumentation for .NET が自動的に提供するトレース属性を含めるように、ロギングライブラリを設定できます。メタデータを使用して、トレースとログイベントを関連付け、Splunk でログを探索します。

互換性と必要条件をチェック 🔗

SignalFx Instrumentation は、以下のロギング・ライブラリをサポートしています：

ライブラリ	バージョン	レイアウト
ILogger	2.5.0 ～ 6.x.x	JSONフォーマット： `NetEscapades.Extensions.Logging` パッケージの `json`
Log4Net	1.0.0 ～2.x.x	JSONフォーマット： `log4net.Ext.Json` パッケージの `SerializedLayout` 生のフォーマット： `PatternLayout`
NLog	1.0.0.505～ 4.x.x	JSONフォーマット： `JsonLayout` 生のフォーマット：カスタムレイアウト
Serilog	1.4.0 ～ 2.x.x	JSONフォーマット： `Serilog.Formatting.Compact` パッケージの `JsonFormatter` または `CompactJsonFormatter` 生のフォーマット：出力テンプレート

ログ相関を有効にする 🔗

ログの相関を有効にするには、インストルメンテーションされたアプリケーションを実行する前に、SIGNALFX_LOGS_INJECTION 環境変数を true に設定します。

ログ文にトレースメタデータを含める 🔗

SignalFx Instrumentation for .NET は、ロギング・ライブラリに以下の属性を提供します：

trace_id
span_id
service.name 環境変数 SIGNALFX_SERVICE_NAME で定義されています。
service.version 環境変数 SIGNALFX_VERSION で定義されています。
deployment.environment 環境変数 SIGNALFX_ENV で定義されています。

ロギングライブラリがJSONを使用する場合、トレース・ライブラリは自動的にデータ注入を処理します。

ロガーが未加工形式を使用する場合、トレースメタデータを含めるようにロガーを設定する必要があります。以下のセクションは、サポートされているロガーにトレースメタデータを含めるように設定する方法を示しています。

Log4Net 🔗

SerializedLayout レイアウトを使用する場合、properties メンバを追加することで、すべてのコンテキスト・プロパティを追加できます。例：

<layout type='log4net.Layout.SerializedLayout, log4net.Ext.Json'>
   <!-- existing configuration -->
   <member value='properties'/> <!-- addition -->
</layout>

明示的にコンテキスト・フィールドを追加することもできます。例：

<layout type='log4net.Layout.SerializedLayout, log4net.Ext.Json'>
   <!-- existing configuration -->
   <member value='trace_id' />
   <member value='span_id' />
   <member value='service.name' />
   <member value='service.version' />
   <member value='deployment.environment' />
</layout>

PatternLayout レイアウトを使用する場合は、コンテキスト・フィールドを手動で追加してください。値は引用符で囲む必要があります。例：

<layout type="log4net.Layout.PatternLayout">
   <conversionPattern value="%date [%thread] %level %logger {trace_id=&quot;%property{trace_id}&quot;, span_id=&quot;%property{span_id}&quot;, service.name=&quot;%property{service.name}&quot;, service.version=&quot;%property{service.version}&quot;, deployment.environment=&quot;%property{deployment.environment}&quot;} - %message%newline" />
</layout>

NLog 🔗

JsonLayout レイアウトとNLogバージョン4.4.10以降を使用する場合、includeMdlc 属性を true に設定することで、すべてのコンテキスト・プロパティを追加することができます。例：

<layout xsi:type="JsonLayout" includeMdlc="true"> <!-- includeMdlc property available in NLog 4.4.10+ -->
   <!-- existing configuration -->
</layout>

明示的にコンテキスト・フィールドを追加することもできます。例：

<layout xsi:type="JsonLayout">
   <!-- existing configuration -->
   <attribute name="trace_id" layout="${mdc:item=trace_id}"/>
   <attribute name="span_id" layout="${mdc:item=span_id}"/>
   <attribute name="service.name" layout="${mdc:item=service.name}"/>
   <attribute name="service.version" layout="${mdc:item=service.version}"/>
   <attribute name="deployment.environment" layout="${mdc:item=deployment.environment}"/>
</layout>

カスタムレイアウトを使用する場合は、コンテキストフィールドを手動で追加してください。値は引用符で囲む必要があります。例：

<target
// existing configuration
layout="${longdate}|${uppercase:${level}}|${logger}|{trace_id=&quot;${mdc:item=trace_id}&quot;,span_id=&quot;${mdc:item=span_id}&quot;,service.name=&quot;${mdc:item=service.name}&quot;,service.version=&quot;${mdc:item=service.version}&quot;,deployment.environment=&quot;${mdc:item=deployment.environment}&quot;}|${message}"
/>

Serilog 🔗

注入したいトレースコンテキストを抽出するには、ログコンテキストを使用して LoggerConfiguration インスタンスをエンリッチします：

var loggerConfiguration = new LoggerConfiguration()
   .Enrich.FromLogContext() // addition

出力テンプレートを利用する際には、{Properties} プレースホルダを用いてすべてのコンテキストプロパティを印字するか、またはコンテキストフィールドを手動で追加することができます。

コンテキスト・フィールドを手動で追加する場合は、値を引用符で囲んでください。例：

"{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] trace_id=\"{trace_id}\" span_id=\"{span_id}\" service.name=\"{service_name}\" service.version=\"{service_version}\" deployment.environment=\"{deployment_environment}\"{NewLine}{Message:lj}{NewLine}{Exception}"

Serilogはドットセパレータ（ . ）を使用するプロパティ名をサポートしていないため、インストルメンテーションはフィールド名のセパレータとしてアンダースコア文字を使用します（ _ ）。ログデータを取り込むには、以下の変換ルールを定義します：

service_name から service.name
service_version から service.version
deployment_environment から deployment.environment

ILogger 🔗

NetEscapades.Extensions.Logging.RollingFile パッケージを使用する場合は、IncludeScopes オプションを有効にし、json フォーマッターを使用します。例：

Host.ConfigureLogging(builder =>
   builder.AddFile(opts =>
   {
      opts.FileName = "logs";
      opts.Extension = "json";
      opts.FormatterName = "json"; // supported formatter
      opts.IncludeScopes = true; // addition
   })
);

注釈

SignalFx Instrumentation for .NETはILogger 2.5.0以降のみをサポートしています。

ログ相関は、ILogger が他のサポートされているロガーをラップしている場合にも機能します。

サンプルアプリケーション 🔗

ログ相関の設定方法を示すいくつかのサンプルアプリケーションをダウンロードするには、GitHubの https://github.com/signalfx/signalfx-dotnet-tracing/tree/main/tracer/samples/AutomaticTraceIdInjection を参照してください。

このページは 2024年10月01日に最終更新されました。

Related Topics