- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
C# のログを Datadog に送信するには、次のいずれかの方法を使用します。
このページでは、Serilog
、NLog
、log4net
、Microsoft.Extensions.Logging
ロギングライブラリのセットアップ例を、上記の各アプローチで詳しく説明します。
C# ログ収集の推奨アプローチは、ログをファイルに出力し、そのファイルを Datadog Agent でテールすることです。これにより、Datadog Agent が追加のメタデータでログをリッチ化することができます。
Datadog は、カスタムパース規則の使用を避け、ログを JSON 形式で生成するようにロギングライブラリをセットアップすることを強くお勧めします。
他の多くの .NET のライブラリと同様に、Serilog は、ファイル、コンソールなどに診断ログを提供します。洗練された API を備えています。また、最近の .NET プラットフォーム間で移植可能です。
他のロギングライブラリと異なり、Serilog は、強力な構造化イベント データを志向して構築されています。
Serilog を NuGet でインストールするには、パッケージマネージャーコンソールで、次のコマンドを実行してください。
PM> Install-Package Serilog.Sinks.File
次に、以下のコードを追加してアプリケーションでロガーを直接初期化します。
// ロガーをインスタンス化します
var log = new LoggerConfiguration() // using Serilog;
// Serilog.Formatting.Json; の使用
.WriteTo.File(new JsonFormatter(renderMessage: true), "log.json")
// Serilog.Formatting.Compact; の使用
// .WriteTo.File(new RenderedCompactJsonFormatter(), "log.json")
.CreateLogger();
// 例
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">
<!--
ログ規則と出力のカスタマイズについては、
https://github.com/nlog/nlog/wiki/Configuration-file を参照してください。
-->
<targets async="true">
<!-- ログを Json 形式でファイルに書き込みます -->
<target name="json-file" xsi:type="File" fileName="application-logs.json">
<layout xsi:type="JsonLayout">
<attribute name="date" layout="${date:format=yyyy-MM-ddTHH\:mm\:ss.fff}" />
<attribute name="level" layout="${level:upperCase=true}"/>
<attribute name="message" layout="${message}" />
<attribute name="exception" layout="${exception:format=ToString}" />
</layout>
</target>
</targets>
<rules>
<!-- すべてのイベントを json-file ターゲットに記録します -->
<logger name="*" writeTo="json-file" minlevel="Trace" />
</rules>
</nlog>
最初のイベントを生成してログに記録するには、以下をコードに追加します。
using NLog;
namespace Datadog
{
class Program
{
// ロガーを初期化します
private static Logger logger = LogManager.GetCurrentClassLogger();
static void Main(string[] args)
{
// 簡単なデバッグメッセージをログに記録します
logger.Debug("This is my first step");
// この後にコードを続けます...
}
}
}
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 />
<!--明示的なデフォルトメンバー-->
<remove value="ndc" />
<remove value="message" />
<!--デフォルトの書式設定済みメッセージメンバーを削除します-->
<member value="message:messageobject" />
<!--未加工のメッセージを追加します-->
</layout>
</appender>
</log4net>
<!-- 他の構成をここから始めます... -->
ロガーをインスタンス化し、イベントの生成を開始します。
using log4net;
namespace Datadog
{
class Program
{
// 現在のクラスロガーを取得します
private static ILog logger = LogManager.GetLogger(typeof(Program));
static void Main(string[] args)
{
// App.config から構成を読み込みます
XmlConfigurator.Configure();
// 簡単なデバッグメッセージをログに記録します
logger.Debug("This is my first debug message");
// この後にコードを続けます ...
}
}
}
上の手順に従った場合は、ログファイル (例: 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 に送信するカスタムログ収集を設定します。
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: csharp
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 の status サブコマンドを実行し、Checks
セクションで csharp
を探し、ログが Datadog に正常に送信されることを確認します。
ログが JSON 形式の場合、Datadog は自動的にログメッセージをパースし、ログ属性を抽出します。ログエクスプローラーを使用して、ログを表示し、トラブルシューティングを行うことができます。
APM が有効になっているアプリケーションの場合は、APM .NET の指示に従いログにトレース ID、スパン ID、env
、service
、version
を自動的に追加し、ログとトレースを接続します。
注: APM トレーサーがログに service
を挿入する場合、Agent 構成で設定されている値は上書きされます。
.NET APM 自動インスツルメンテーションライブラリを使用して、コードを変更することなく、アプリケーションから Datadog に直接ログをストリームすることが可能です。この方法は、Datadog に直接ログを送信するため、Datadog Agent が提供する機密データスクラビングなどの機能の恩恵を受けることができません。そのため、可能な限りファイルテールロギングを使用することを推奨しますが、これが不可能な環境 (例えば Azure App Service を使用している場合) においては有用です。なお、機密データスキャナーによって実行されるサーバーサイドのスクラビング機能には、これまで通り依存することが可能です。
エージェントレスロギング (「ダイレクトログ送信」とも呼ばれる) は、以下のフレームワークに対応しています。
アプリケーションのコードを修正したり、アプリケーションに依存するものを追加でインストールする必要はありません。
エージェントレスロギングは、APM を自動インスツルメンテーションで使用する場合にのみ利用できます。まず、以下のドキュメントで説明されているように、アプリケーションをインスツルメントしてください。
インストール後、トレースが正しく受信されていることを確認します。
エージェントレスロギングを有効にするには、以下の環境変数を設定します。
DD_API_KEY
DD_SITE
datadoghq.com
(US1)、datadoghq.eu
(EU)、us3.datadoghq.com
(US3)、us5.datadoghq.com
(US5)、ddog-gov.com
(US1-FED)datadoghq.com
(US1)DD_LOGS_INJECTION
true
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
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
DD_SITE
で指定されたドメインを使用します。https://http-intake.logs.datadoghq.com:443
(DD_SITE
に基づく)DD_LOGS_DIRECT_SUBMISSION_URL
DD_SITE
で指定されたドメインを使用します。https://http-intake.logs.us3.datadoghq.com:443
(DD_SITE
に基づく)DD_LOGS_DIRECT_SUBMISSION_URL
DD_SITE
で指定されたドメインを使用します。https://http-intake.logs.us5.datadoghq.com:443
(DD_SITE
に基づく)DD_LOGS_DIRECT_SUBMISSION_URL
DD_SITE
で指定されたドメインを使用します。https://http-intake.logs.ap1.datadoghq.com:443
(DD_SITE
に基づく)DD_LOGS_DIRECT_SUBMISSION_URL
DD_SITE
で指定されたドメインを使用します。https://http-intake.logs.datadoghq.eu:443
(DD_SITE
に基づく)DD_LOGS_DIRECT_SUBMISSION_URL
DD_SITE
で指定されたドメインを使用します。https://http-intake.logs.ddog-gov.com:443
(DD_SITE
に基づく)DD_LOGS_DIRECT_SUBMISSION_SOURCE
csharp
に設定する必要があります。csharp
DD_LOGS_DIRECT_SUBMISSION_MAX_BATCH_SIZE
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 トレーサーライブラリ v2.20.0 で導入されました。
{
"Logging": {
"Datadog": {
"LogLevel": {
"Microsoft.AspNetCore": "Warning"
},
}
}
}
もし、ファイルテールロギングや APM エージェントレスロギングを使用することができず、Serilog
フレームワークを使用している場合は、Datadog Serilog シンクを使用して直接 Datadog にログを送信することが可能です。
Datadog Serilog シンクをアプリケーションにインストールします。このシンクは、イベントとログを Datadog に送信し、デフォルトではポート 443 の HTTPS 経由でログを転送します。 パッケージマネージャーコンソールで、次のコマンドを実行してください。
PM> Install-Package Serilog.Sinks.Datadog.Logs
次に、アプリケーションでロガーを直接初期化します。必ずご使用の <API_KEY>
を追加してください。
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "https://http-intake.logs.datadoghq.com" })
.CreateLogger())
{
// コード
}
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "https://http-intake.logs.us3.datadoghq.com" })
.CreateLogger())
{
// コード
}
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "https://http-intake.logs.ap1.datadoghq.com" })
.CreateLogger())
{
// コード
}
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "https://http-intake.logs.us5.datadoghq.com" })
.CreateLogger())
{
// コード
}
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "https://http-intake.logs.datadoghq.eu" })
.CreateLogger())
{
// コード
}
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs("<API_KEY>", configuration: new DatadogConfiguration(){ Url = "https://http-intake.logs.ddog-gov.com" })
.CreateLogger())
{
// コード
}
デフォルトの動作を上書きして、ログを TCP で転送することもできます。それには、必須プロパティ url
、port
、useSSL
、および useTCP
を手動で指定します。また、オプションで、source
、service
、host
、およびカスタムタグを指定できます。
たとえば、Datadog US リージョンに TCP でログを転送する場合は、次のようなシンクコンフィギュレーションを使用します。
var config = new DatadogConfiguration(url: "intake.logs.datadoghq.com", port: 10516, useSSL: true, useTCP: true);
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs(
"<API_KEY>",
source: "<SOURCE_NAME>",
service: "<SERVICE_NAME>",
host: "<HOST_NAME>",
tags: new string[] {"<TAG_1>:<VALUE_1>", "<TAG_2>:<VALUE_2>"},
configuration: config
)
.CreateLogger())
{
// コード
}
デフォルトの動作を上書きして、ログを TCP で転送することもできます。それには、必須プロパティ url
、port
、useSSL
、および useTCP
を手動で指定します。また、オプションで、source
、service
、host
、およびカスタムタグを指定できます。
たとえば、Datadog EU リージョンに TCP でログを転送する場合は、次のようなシンクコンフィギュレーションを使用します。
var config = new DatadogConfiguration(url: "tcp-intake.logs.datadoghq.eu", port: 443, useSSL: true, useTCP: true);
using (var log = new LoggerConfiguration()
.WriteTo.DatadogLogs(
"<API_KEY>",
source: "<SOURCE_NAME>",
service: "<SERVICE_NAME>",
host: "<HOST_NAME>",
tags: new string[] {"<TAG_1>:<VALUE_1>", "<TAG_2>:<VALUE_2>"},
configuration: config
)
.CreateLogger())
{
// コード
}
これで、新しいログが Datadog に直接送信されるようになります。
または、0.2.0
以降、Serilog.Setting.Configuration
パッケージで appsettings.json
ファイルを使用して Datadog シンクを構成できます。
Serilog.WriteTo
配列で、DatadogLogs
のエントリを追加します。以下に例を示します。
"Serilog": {
"Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.Datadog.Logs" ],
"MinimumLevel": "Debug",
"WriteTo": [
{ "Name": "Console" },
{
"Name": "DatadogLogs",
"Args": {
"apiKey": "<API_キー>",
"source": "<ソース名>",
"host": "<ホスト名>",
"tags": ["<タグ_1>:<値_1>", "<タグ_2>:<値_2>"],
}
}
],
"Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
"Properties": {
"Application": "Sample"
}
}