- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
サービスは様々なリクエストを扱うことができますが、その中にはトレースから除外したい、またはトレースメトリクスに含めたくないものがあるかもしれません。例としては、Web アプリケーションのヘルスチェックなどが挙げられます。
次の 2 つの方法で、このようなエンドポイントをトレースせず、トレースメトリクスから除外するよう指定することができます。
ヘルプが必要な場合は、Datadog のサポートチームまでお問合せください。
Datadog Agent 内の Trace Agent コンポーネントには、特定のトレースを除外するために「スパンタグの無視」と「リソースの無視」という 2 つのメソッドが用意されています。これらの設定によりトレースが取り込まれなかった場合、トレースメトリクスはこれらのリクエストを除外します。
特定のスパンやリソースを無視するよう Trace Agent を設定すると、この特定の Datadog Agent にトレースを送信するすべてのサービスに適用されます。アプリケーション固有の要件がある場合は、代わりにトレーサーのコンフィギュレーションメソッドを使用してください。
Datadog Agent 6.27.0/7.27.0 より、filter tags オプションは、指定されたスパンタグにマッチするルートスパンを持つトレースを無視します。このオプションは、この特定の Datadog Agent にトレースを送信するすべてのサービスに適用されます。フィルタータグが原因で無視されたトレースは、トレースメトリクスに含まれません。
Datadog に送信したくないトレースのセットをプログラムで特定でき、このガイドの他のオプションで要件を解決することができない場合は、カスタムスパンタグを追加してトレースを除外することを検討できます。サポートにお問い合わせいただき、この機能を継続的に拡張するためのユースケースについてご相談ください。
フィルタータグオプションでは、文字列の完全一致が必要です。正規表現により除外したい場合は、「リソースに基づいて無視する」を参照してください。
環境変数のキーと値をカンマで区切ったリストを使って、必要とするスパンタグや拒否するスパンタグを指定することができます。
DD_APM_FILTER_TAGS_REQUIRE
DD_APM_FILTER_TAGS_REQUIRE="key1:value1 key2:value2"
です。DD_APM_FILTER_TAGS_REJECT
DD_APM_FILTER_TAGS_REJECT="key1:value1 key2:value2"
です。または、Agent のコンフィギュレーションファイルでこれらを設定することもできます。
datadog.yaml
apm_config:
filter_tags:
require: ["db:sql", "db.instance:mysql"]
reject: ["outcome:success", "key2:value2"]
たとえば、http.url
がこのエンドポイントに一致するヘルスチェックを無視するには次のようにします。
datadog.yaml
apm_config:
filter_tags:
reject: ["http.url:http://localhost:5050/healthcheck"]
この方法でトレースをフィルターすると、トレースメトリクスからこれらのリクエストが削除されます。トレースメトリクスに影響を与えずに取り込みを減らす方法については、Ingestion Controls を参照してください。
バックエンドでは、Datadog は取り込み後に以下のスパンタグを作成し、スパンに追加します。これらのタグは、Datadog Agent レベルでトレースをドロップするために使用することはできません。
名前 | 説明 |
---|---|
http.path_group | http.url タグからの完全な URL パス。 |
http.url_details.host | http.url タグのホスト名部分。 |
http.url_details.path | HTTP リクエスト行で渡された完全なリクエスト対象、またはそれに相当するもの。 |
http.url_details.scheme | http.url タグからのリクエストスキーム。 |
http.url_details.queryString | http.url タグからのクエリ文字列部分。 |
http.url_details.port | http.url タグからの HTTP ポート。 |
http.useragent_details.os.family | User-Agent によって報告された OS ファミリー。 |
http.useragent_details.browser.family | User-Agent によって報告されたブラウザファミリー。 |
http.useragent_details.device.family | User-Agent によって報告されたデバイスファミリー。 |
名前 | Remap from |
---|---|
network.host.ip | tcp.local.address - Node.js |
network.destination.ip | out.host - すべての言語 |
network.destination.port | grpc.port - Pythontcp.remote.port - Node.jsout.port - すべての言語 |
名前 | Remap from |
---|---|
http.route | aspnet_core.route - .NETaspnet.route - .NETlaravel.route - PHPsymfony.route - PHP |
http.useragent | user_agent - Java |
http.url_details.queryString | http.query.string - Python |
名前 | Remap from |
---|---|
db.system | db.type - Java、Python、Node.js、Goactive_record.db.vendor - Rubysequel.db.vendor - Ruby |
db.instance | mongodb.db - Pythonsql.db - Pythondb.name - すべての言語 |
db.statement | cassandra.query - Goconsul.command - Pythonmemcached.query - Pythonmongodb.query - Python、.NET、Goredis.command - Pythonredis.raw_command - Pythonsql.query - Python、PHP、Node.js、Java |
db.row_count | cassandra.row_count - Pythondb.rowcount - Python、PHPmongodb.rows - Pythonsql.rows - Python |
db.cassandra.cluster | cassandra.cluster - Python、Go |
db.cassandra.consistency_level | cassandra.consistency_level - Python、Go |
db.cassandra.table | cassandra.keyspace - Python、Go |
db.redis.database_index | db.redis.dbIndex - Javaout.redis_db - Python、Ruby |
db.mongodb.collection | mongodb.collection - Python、.NET、Ruby、PHP |
db.cosmosdb.container | cosmosdb.container - .NET |
名前 | Remap from |
---|---|
messaging.destination | amqp.destination - Node.jsamqp.queue - .NETmsmq.queue.path - .NETaws.queue.name - .NET |
messaging.url | aws.queue.url - .NET、Java |
messaging.message_id | server_id - Go |
messaging.message_payload_size | message.size - .NET、Java |
messaging.operation | amqp.command - .NETmsmq.command - .NET |
messaging.rabbitmq.routing_key | amqp.routing_key - Javaamqp.routingKey - Nodes.js |
messaging.rabbitmq.delivery_mode | messaging.rabbitmq.exchange - .NET |
messaging.msmq.message.transactional | msmq.message.transactional - .NET |
messaging.msmq.queue.transactional | msmq.queue.transactional - .NET |
messaging.kafka.consumer_group | kafka.group - Java |
messaging.kafka.tombstone | kafka.tombstone - .NETtombstone - Java |
messaging.kafka.partition | kafka.partition - .NETpartition - Node.js、Go、Java |
messaging.kafka.offset | kafka.offset - .NET |
messaging.msmq.message.transactional | msmq.message.transactional - .NET |
名前 | Remap from |
---|---|
rpc.service | grpc.method.service - Python、.NET |
rpc.method | grpc.method.name - Python、.NET、Go |
rpc.grpc.package | grpc.method.package - Python、.NET、Go |
rpc.grpc.status_code | grpc.code - Gostatus.code - Python、.NET、Node.jsgrpc.status.code - Python、.NET、Node.js |
rpc.grpc.kind | grpc.method.kind - Python、Node.js、Go、.NET |
rpc.grpc.path | rpc.grpc.path - Python、Node.js、Go、.NET |
rpc.grpc.request.metadata.* | grpc.request.metadata.* - Python、Node.jsrpc.grpc.request.metadata - Go |
rpc.grpc.response.metadata.* | grpc.response.metadata.* - Python、Node.js |
名前 | Remap from |
---|---|
error.message | error.msg - すべての言語 |
ignore resources オプションを使用すると、トレースのグローバルルートスパンが特定の基準に一致する場合にリソースを除外することができます。リソースを収集から除外を参照してください。このオプションは、この特定の Datadog Agent にトレースを送信するすべてのサービスに適用されます。ignore resources により無視されたトレースは、トレースメトリクスに含まれません。
無視するリソースは、Agent のコンフィギュレーションファイル、datadog.yaml
、または DD_APM_IGNORE_RESOURCES
環境変数で指定します。以下の例を参照してください。
datadog.yaml
apm_config:
## @param ignore_resources - list of strings - optional
## 正規表現のリストを提供し、リソース名に基づいて特定のトレースを除外することができます。
## すべての入力項目は二重引用符で囲み、カンマ区切りにする必要があります。
ignore_resources: ["(GET|POST) /healthcheck","API::NotesController#index"]
注:
トレースを必要としない /api/healthcheck
の呼び出しを含むトレースを考えてみましょう。
グローバルルートスパンのリソース名に注意してください。
rack.request
Api::HealthchecksController#index
/api/healthcheck
ignore resource オプションを正しく使用するためには、記述された正規表現ルールがリソース名 Api::HealthchecksController#index
に一致している必要があります。いくつかの正規表現オプションが利用できますが、このリソースからのトレースをそのままフィルタリングする場合は `Api::HealthchecksController#index{TX-PL-LABEL}#x60; を使用するのが良いでしょう。
デプロイ方法に応じて、構文は少しずつ異なります。
datadog.yaml
apm_config:
ignore_resources: Api::HealthchecksController#index$
複数の値の場合
apm_config:
ignore_resources: ["value1","Api::HealthchecksController#index$"]
Datadog Agent コンテナの環境変数のリストに、以下の例のようなパターンで DD_APM_IGNORE_RESOURCES
を追加します。Docker Compose には、独自の変数の置換機能があり、$
などの特殊文字を使用する場合に考慮する必要があります。
environment:
// その他の Datadog Agent の環境変数
- DD_APM_IGNORE_RESOURCES=Api::HealthchecksController#index$$
複数の値の場合
environment:
// その他の Datadog Agent の環境変数
- DD_APM_IGNORE_RESOURCES="value1","Api::HealthchecksController#index$$"
Datadog Agent をスピンアップするための docker run コマンドに、DD_APM_IGNORE_RESOURCES
を追加します。
docker run -d --name datadog-agent \
--cgroupns host \
--pid host \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /proc/:/host/proc/:ro \
-v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
-e DD_API_KEY=<> \
-e DD_APM_IGNORE_RESOURCES="Api::HealthchecksController#index$" \
-e DD_APM_ENABLED=true \
-e DD_APM_NON_LOCAL_TRAFFIC=true \
gcr.io/datadoghq/agent:latest
複数の値の場合
-e DD_APM_IGNORE_RESOURCES=["value1","Api::HealthchecksController#index$"] \
trace-agent 専用コンテナに、環境変数 DD_APM_IGNORE_RESOURCES
を追加します。
- name: trace-agent
image: "gcr.io/datadoghq/agent:latest"
imagePullPolicy: IfNotPresent
command: ["trace-agent", "-config=/etc/datadog-agent/datadog.yaml"]
resources: {}
ports:
- containerPort: 8126
hostPort: 8126
name: traceport
protocol: TCP
env:
- name: DD_API_KEY
valueFrom:
secretKeyRef:
name: "datadog-secret"
key: api-key
- name: DD_KUBERNETES_KUBELET_HOST
valueFrom:
fieldRef:
fieldPath: status.hostIP
- name: KUBERNETES
value: "yes"
- name: DOCKER_HOST
value: unix:///host/var/run/docker.sock
- name: DD_LOG_LEVEL
value: "INFO"
- name: DD_APM_ENABLED
value: "true"
- name: DD_APM_NON_LOCAL_TRAFFIC
value: "true"
- name: DD_APM_RECEIVER_PORT
value: "8126"
- name: DD_KUBELET_TLS_VERIFY
value: "false"
- name: DD_APM_IGNORE_RESOURCES
value: "Api::HealthchecksController#index$"
複数の値の場合
- name: DD_APM_IGNORE_RESOURCES
value: ["value1","Api::HealthchecksController#index$"]
values.yaml
ファイルの traceAgent
セクションで、env
セクションに DD_APM_IGNORE_RESOURCES
を追加し、通常通りに Helm をスピンアップします。
values.yaml
traceAgent:
# agents.containers.traceAgent.env -- trace-agent コンテナ向けの追加の環境変数
env:
- name: DD_APM_IGNORE_RESOURCES
value: Api::HealthchecksController#index$
複数の値の場合
- name: DD_APM_IGNORE_RESOURCES
value: value1, Api::HealthchecksController#index$
代わりに、helm install
コマンドで agents.containers.traceAgent.env
を設定することもできます。
helm install dd-agent -f values.yaml \
--set datadog.apiKeyExistingSecret="datadog-secret" \
--set agents.containers.traceAgent.env[0].name=DD_APM_IGNORE_RESOURCES, \
agents.containers.traceAgent.env[0].value="Api::HealthchecksController#index$" \
datadog/datadog
AWS ECS を使用している場合 (EC2など) は、Datadog Agent のコンテナ定義で、環境変数 DD_APM_IGNORE_RESOURCES
および JSON が以下のように評価されるような値を追加します。
"environment": [
// Datadog Agent 向けのその他の環境変数
{
"name": "DD_APM_IGNORE_RESOURCES",
"value": "Api::HealthchecksController#index$"
}
]
言語固有のトレーサーの中には、Datadog Agent に送信する前にスパンを修正するオプションがあります。アプリケーション固有の要件があり、以下の言語を使用している場合にはこのオプションを使用してください。
Ruby トレーサーには、特定の条件を満たすトレースを除去する後処理パイプラインがあります。詳しい情報や例はトレースの後処理を参照してください。
たとえば、リソース名が Api::HealthchecksController#index
である場合、そのリソース名を含むトレースを除去するために Datadog::Tracing::Pipeline::SpanFilter
クラスを使用します。このフィルターは、スパンオブジェクトで利用可能な他のメタデータを照合するためにも使用できます。
Datadog::Tracing.before_flush(
Datadog::Tracing::Pipeline::SpanFilter.new { |span| span.resource =~ /Api::HealthchecksController#index/ }
)
Pythonトレーサーには、特定のエンドポイントからのトレースを削除するように設定できる FilterRequestsOnUrl
フィルターがあります。また、カスタムフィルターを書くこともできます。詳細はトレースフィルター を参照してください。
ルートスパンの http.url
スパンタグの値が http://<domain>/healthcheck
の場合の例を考えます。healthcheck
で終わるすべてのエンドポイントに一致するよう、次の正規表現を使用します。
from ddtrace import tracer
from ddtrace.filters import FilterRequestsOnUrl
tracer.configure(settings={
'FILTERS': [
FilterRequestsOnUrl(r'http://.*/healthcheck$'),
],
})
Http プラグインにブロックリストを設定します。ブロックリストが一致する対象については API ドキュメントを参照してください。例えば、Http は URL に一致するため、トレースの http.url
スパンタグが http://<domain>/healthcheck
であれば、healthcheck
URL に一致するルールを記述します。
const tracer = require('dd-trace').init();
tracer.use('http', {
blocklist: ["/healthcheck"]
})
// http をインポート
Java トレーサーには、カスタム TraceInterceptor
で特定のスパンをフィルタリングするオプションがあります。トレーサーの拡張を参照してください。
例えば、リソース名が GET /healthcheck
であれば、このリソース名を含むトレースを無視するトレースインターセプターを記述します。ユースケースに合わせてロジックを調整してください。
public class GreetingController {
static {
// クラスの static ブロックで複数回の初期化を回避。
GlobalTracer.get().addTraceInterceptor(new TraceInterceptor() {
@Override
public Collection<? extends MutableSpan> onTraceComplete(Collection<? extends MutableSpan> trace) {
for (MutableSpan span : trace) {
if ("GET /healthcheck".contentEquals(span.getResourceName())) {
return Collections.emptyList();
}
}
return trace;
}
@Override
public int priority() {
return 200; // Some unique number
}
});
}
}