C# ログ収集

Docs > Log Management > ログの収集とインテグレーション > C# ログ収集

C# のログを Datadog に送信するには、次のいずれかの方法を使用します。

ファイルにログを記録し、そのファイルを Datadog Agent でテールする。
エージェントレスロギングを有効にする
Serilog シンクを使用する。

Datadog Agent によるファイルテールロギング

C# ログ収集の推奨アプローチは、ログをファイルに出力し、そのファイルを Datadog Agent でテール監視することです。これにより、Datadog Agent が追加のメタデータでログを強化することができます。

Datadog は、カスタムパース規則の使用を避け、ログを JSON 形式で生成するようにロギングライブラリをセットアップすることを強くお勧めします。

ファイルテールロギングは、以下のフレームワークをサポートしています。

Serilog
NLog
log4net

ロガーの構成

他の多くの .NET のライブラリと同様に、Serilog は、ファイル、コンソールなどに診断ログを提供します。洗練された API を備えています。また、最近の .NET プラットフォーム間で移植可能です。

他のロギングライブラリと異なり、Serilog は、強力な構造化イベントデータを志向して構築されています。

Serilog を NuGet でインストールするには、パッケージマネージャーコンソールで、次のコマンドを実行してください。

PM> Install-Package Serilog.Sinks.File

次に、以下のコードを追加してアプリケーションでロガーを直接初期化します。

// Instantiate the logger
var log = new LoggerConfiguration()  // using Serilog;

    // using Serilog.Formatting.Json;
    .WriteTo.File(new JsonFormatter(renderMessage: true), "log.json")

    // using Serilog.Formatting.Compact;
    // .WriteTo.File(new RenderedCompactJsonFormatter(), "log.json")

    .CreateLogger();

// An example
var position = new { Latitude = 25, Longitude = 134 };
var elapsedMs = 34;

log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);

log.json ファイルで、ロガーが正常にインスタンス化されたことを確認します。

JsonFormatter(renderMessage: true) を使用している場合は、確認のために次のイベントを探してください。

{
  "MessageTemplate": "Processed {@Position} in {Elapsed:000} ms.",
  "Level": "Information",
  "Timestamp": "2016-09-02T15:02:29.648Z",
  "Renderings": {"Elapsed": [{"Format": "000", "Rendering": "034"}]},
  "RenderedMessage":"Processed { Latitude: 25, Longitude: 134 } in 034 ms.",
  "Properties": {"Position": {"Latitude": 25, "Longitude": 134}, "Elapsed": 34}
}

RenderedCompactJsonFormatter() を使用している場合は、確認のために次のイベントを探してください。

{
  "@t": "2020-05-20T04:15:28.6898801Z",
  "@m": "Processed { Latitude: 25, Longitude: 134 } in 034 ms.",
  "@i": "d1eb2146",
  "Position": {"Latitude": 25, "Longitude": 134 },
  "Elapsed": 34
}

NLog は、豊富なログルーティングおよび管理機能を備えた .NET 用のログプラットフォームです。アプリケーションのサイズや複雑さに関係なく、高品質なログの生成および管理に役立ちます。

NLog を NuGet を使ってインストールするには、パッケージマネージャーコンソールで、次のコマンドを実行してください。

PM> Install-Package NLog

ライブラリがクラスパスにある場合は、次のレイアウトを任意のターゲットに適用してください。プロジェクトのルートパスに NLog.config ファイルを編集または追加してください。次に、以下のコードをその中にコピー/ペーストします (ログは application-logs.json ファイルに書き込まれます)。

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <!--
  See https://github.com/nlog/nlog/wiki/Configuration-file
  for information on customizing logging rules and outputs.
   -->
  <targets async="true">
    <!-- Write logs as Json into a file -->
    <target name="json-file" xsi:type="File" fileName="application-logs.json">
      <layout xsi:type="JsonLayout">
        <attribute name="date" layout="${date:universalTime=true:format=o}" />
        <attribute name="level" layout="${level:upperCase=true}"/>
        <attribute name="message" layout="${message}" />
        <attribute name="exception" layout="${exception:format=ToString}" />
      </layout>
    </target>

  </targets>
  <rules>
    <!-- Log all events to the json-file target -->
    <logger name="*" writeTo="json-file" minlevel="Trace" />
  </rules>
</nlog>

最初のイベントを生成してログに記録するには、以下をコードに追加します。

using NLog;

namespace Datadog
{
    class Program
    {
        // Initialize a logger
        private static Logger logger = LogManager.GetCurrentClassLogger();

        static void Main(string[] args)
        {
            // Log a simple debug message
            logger.Debug("This is my first step");

            // your code continues here ...
        }
    }
}

Log4Net は、Log4j にインスパイアされた .NET 用のログプラットフォームで、豊富なログルーティングおよび管理機能を備えています。アプリケーションのサイズや複雑さに関係なく、高品質なログの生成および管理に役立ちます。

Log4Net をインストールするには、パッケージマネージャーコンソールで、次のコマンドを実行します。

PM> Install-Package log4net
PM> Install-Package log4net.Ext.Json

ライブラリをインストールしたら、任意のターゲットに次のレイアウトを適用します。プロジェクトの App.config を編集し、次のセクションを追加します。

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
  </configSections>

  <log4net>
    <root>
      <level value="DEBUG" />
      <appender-ref ref="JsonFileAppender" />
    </root>
    <appender name="JsonFileAppender" type="log4net.Appender.FileAppender">
      <threshold value="DEBUG"/>
      <file value="application-logs.json" />
      <encoding type="System.Text.UTF8Encoding" />
      <appendToFile value="true" />
      <layout type="log4net.Layout.SerializedLayout, log4net.Ext.Json">
        <decorator type="log4net.Layout.Decorators.StandardTypesDecorator, log4net.Ext.Json" />
        <default />
        <!--explicit default members-->
        <remove value="ndc" />
        <remove value="message" />
        <!--remove the default preformatted message member-->
        <member value="message:messageobject" />
        <!--add raw message-->
      </layout>
    </appender>
  </log4net>

  <!-- The rest of your configuration starts here ... -->

ロガーをインスタンス化し、イベントの生成を開始します。

using log4net;

namespace Datadog
{
    class Program
    {
        // Get the current class logger
        private static ILog logger = LogManager.GetLogger(typeof(Program));

        static void Main(string[] args)
        {

           // Load the configure fom App.config
           XmlConfigurator.Configure();

           // Log a simple debug message
           logger.Debug("This is my first debug message");

           // your code continues here ...
        }
    }
}

上の手順に従った場合は、ログファイル (例: C:\Projects\Datadog\Logs\log.json) に次のイベントがあることを確認できます。

{
  "level": "DEBUG",
  "message": "This is my debug message",
  "date": "2016-05-24 15:53:35.7175",
  "appname": "Datadog.vshost.exe",
  "logger": "Datadog.Program",
  "thread": "10"
}

JSON でログを記録する方がメリットが多いですが、未加工の文字列形式でログを記録したい場合は、次のように log4net conversion pattern を更新し、C# インテグレーションパイプラインを使用してログが自動的にパースされるようにします。

<param name="ConversionPattern" value="%date{yyyy-MM-dd HH:mm:ss.SSS} %level [%thread] %logger %method:%line - %message%n" />

Datadog Agent の構成

ログ収集が有効になったら、ログファイルを追跡して Datadog に送信するカスタムログ収集を設定します。

csharp.d/ フォルダーを conf.d/ Agent 構成ディレクトリに作成します。

csharp.d/ に以下の内容で conf.yaml ファイルを作成します。

init_config:

instances:

##Log section
logs:

  - type: file
    path: "<path_to_your_csharp_log>.log"
    service: <service_name>
    source: csharp
    sourcecategory: sourcecode
    # For multiline logs, if they start by the date with the format yyyy-mm-dd uncomment the following processing rule
    #log_processing_rules:
    #  - type: multi_line
    #    name: new_log_start_with_date
    #    pattern: \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])

Agent ユーザーにログファイルの読み取り権限があることを確認します。
Agent を再起動します。
Agent の status サブコマンドを実行し、Checks セクションで csharp を探し、ログが Datadog に正常に送信されることを確認します。

ログが JSON 形式の場合、Datadog は自動的にログメッセージをパースし、ログ属性を抽出します。ログエクスプローラーを使用して、ログを表示し、トラブルシューティングを行うことができます。

ログとトレース全体のサービスを接続

このアプリケーションで APM が有効になっている場合は、トレース ID とスパン ID を自動的に追加して、ログとトレースを接続します。 env、service、および version をログに追加して、APM .NET の指示に従ってログとトレースを接続してください。

注: Datadog SDK がログに service を挿入する場合、Agent 構成で設定されている値は上書きされます。

APM によるエージェントレスロギング

コードを変更することなく、.NET APM 自動インスツルメンテーションライブラリを使用して、アプリケーションから Datadog にログを直接ストリーミングできます。このアプローチではログを Datadog に直接送信するため、Datadog Agent が提供する機能 (機密データのスクラビングなど)の恩恵を受けることはありません。そのため、可能な限りファイルテールロギングを使用することを推奨しますが、Azure App Service を使用する場合など、ファイルテールロギングを使用できない環境では有用です。なお、Sensitive Data Scanner によるサーバー側のスクラビング機能は引き続き利用できる点は特筆すべきです。

エージェントレスロギング (「ダイレクトログ送信」とも呼ばれる) は、以下のフレームワークに対応しています。

Serilog (v1.0+)
NLog (v2.1+)
log4net (v1.0+)
Microsoft.Extensions.Logging (2.0+)

アプリケーションのコードを修正したり、アプリケーションに依存するものを追加でインストールする必要はありません。

注: log4net または NLog を使用する場合、エージェントレスロギングを有効にするには、アペンダー (log4net) またはロガー (NLog) を構成する必要があります。その場合、これらの追加依存関係を追加するか、Serilog シンクを使用したエージェントレスロギングを代わりに使用できます。

Datadog SDK を構成する

エージェントレスロギングは、APM で自動インスツルメンテーションを使用している場合にのみ利用可能です。始めるには、以下のドキュメントに記載されているようにアプリケーションをインスツルメントしてください。

インストール後、トレースが正しく受信されていることを確認します。

エージェントレスロギングを有効にする

エージェントレスロギングを有効にするには、以下の環境変数を設定します。

DD_API_KEY: Datadog にログを送信するための Datadog API キー。
DD_SITE: あなたの Datadog サイトの名前。次の例のいずれかを選択してください。
例: datadoghq.com (US1)、datadoghq.eu (EU)、us3.datadoghq.com (US3)、us5.datadoghq.com (US5)、ap1.datadoghq.com (AP1)、ap2.datadoghq.com (AP2)、ddog-gov.com (US1-FED)、us2.ddog-gov.com (US2-FED)
デフォルト: datadoghq.com (US1)
DD_LOGS_INJECTION: ログとトレースの接続を有効にします。
デフォルト: true
Tracer バージョン 3.24.0 以降、デフォルトで有効です。
DD_LOGS_DIRECT_SUBMISSION_INTEGRATIONS: エージェントレスロギングを有効にします。Serilog、NLog、Log4Net、またはILogger (Microsoft.Extensions.Logging 用) に設定することで、ログフレームワークで有効にします。複数のログフレームワークを使用している場合は、セミコロン区切りの変数リストを使用してください。
例: Serilog;Log4Net;NLog

注: Microsoft.Extensions.Loggingと併用してログフレームワークを使用している場合は、通常、そのフレームワーク名を使用する必要があります。例えば、Serilog.Extensions.Logging を使用している場合は、 DD_LOGS_DIRECT_SUBMISSION_INTEGRATIONS=Serilogを設定する必要があります。

これらの環境変数を設定した後、アプリケーションを再起動します。

追加の構成

以下の環境変数を使用して、エージェントレスログ収集のいくつかの側面をさらにカスタマイズすることができます。

DD_LOGS_DIRECT_SUBMISSION_MINIMUM_LEVEL: Datadogに送信される_前に_、レベルでログをフィルタリングできるようにします。次のいずれかの値に設定してください: Verbose、Debug、Information、Warning、Error、Critical。これらは、サポートされているログフレームワークにおける同等のレベルに対応します。
デフォルト: Information
DD_LOGS_DIRECT_SUBMISSION_HOST: ログに関連付けられたホストの名前を設定します。指定されない場合、ホスト名は自動的に検出されます。
デフォルト: 自動的に決定されます。
DD_LOGS_DIRECT_SUBMISSION_TAGS: 指定された場合、指定されたすべてのタグを生成されたすべてのスパンに追加します。指定されない場合は、代わりに DD_TAGS を使用します。
例: layer:api, team:intake 区切り文字はカンマと空白であることに注意してください: , 。

以下の構成値は、基本的に変更すべきではありませんが、必要であれば設定しても構いません。

DD_LOGS_DIRECT_SUBMISSION_URL: ログを送信する URL を設定します。デフォルトでは、DD_SITE で指定されたドメインを使用します。
デフォルト: :443 (based on DD_SITE)
DD_LOGS_DIRECT_SUBMISSION_SOURCE: 送信されたログのパースルールを設定します。カスタムパイプラインがない限り、常に csharp に設定する必要があります。
デフォルト: csharp
DD_LOGS_DIRECT_SUBMISSION_MAX_BATCH_SIZE: 一度に送信するログの最大数を設定します。API に設定されている制限を考慮します。
デフォルト: 1000
DD_LOGS_DIRECT_SUBMISSION_MAX_QUEUE_SIZE: ログメッセージを削除する前に、内部キューに一度に保持するログの最大数を設定します。
デフォルト: 100000
DD_LOGS_DIRECT_SUBMISSION_BATCH_PERIOD_SECONDS: 新しいログを送信する前にチェックするまでの待機時間 (秒) を設定します。
デフォルト: 1

Microsoft.Extensions.Logging インテグレーションを使用している場合は、ILogger に組み込まれている標準機能を使用して、Datadog に送信されるログをフィルタリングできます。キー "Datadog" を使用して直接送信プロバイダーを識別し、各ネームスペースの最小ログレベルを設定します。例えば、appSettings.json に以下を追加すると、Warning 未満のレベルのログが Datadog に送信されないようにできます。..NET SDK v2.20.0 で導入されました。

{
  "Logging": {
    "Datadog": {
      "LogLevel": {
        "Microsoft.AspNetCore": "Warning"
      },
    }
  }
}

Serilog シンクによるエージェントレスロギング

0.2.0以降では、 appsettings.json ファイルを使用してパッケージの Datadog シンクを構成できます。Serilog.Setting.Configuration パッケージ。詳細については、`Serilog.Sinks.Datadog.Logs` パッケージを参照してください。

もし、ファイルテールロギングや APM エージェントレスロギングを使用することができず、Serilog フレームワークを使用している場合は、Datadog Serilog シンクを使用して直接 Datadog にログを送信することが可能です。

Datadog Serilog シンクをアプリケーションにインストールすると、イベントとログが Datadog に送信されます。デフォルトでは、シンクは HTTPS (ポート 443) 経由でログを転送します。パッケージマネージャーコンソールで次のコマンドを実行します。

PM> Install-Package Serilog.Sinks.Datadog.Logs

次に、アプリケーションでロガーを直接初期化します。必ずご使用の <API_KEY> を追加してください。

using (var log = new LoggerConfiguration()
    .WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "" })
    .CreateLogger())
{
    // Some code
}