- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
コードを使用してトレーシングライブラリをセットアップし、APM データを収集するように Agent を構成した後、オプションで統合サービスタグ付けのセットアップなど、必要に応じてトレーシングライブラリを構成してください。
PHP トレーサーは環境変数および INI 設定を使用して構成できます。
INI 設定は、php.ini
ファイルで、または特定のウェブサーバーやバーチャルホストに対してなど、グローバルに構成できます。
注: コードの自動インスツルメンテーションを使用する場合(推奨されるアプローチ)、インスツルメンテーションコードはどのユーザーコードよりも先に実行されることに注意してください。そのため、以下の環境変数および INI 設定はサーバーレベルで設定し、ユーザーコードが実行される前に PHP ランタイムで使用できるようにします。たとえば、putenv()
や .env
ファイルは機能しません。
php-fpm を使用する Apache の場合、www.conf
コンフィギュレーションファイルの env
ディレクトリを使用して PHP トレーサーを構成します。次に例を示します。
; ホスト環境変数 SOME_ENV を
; DD_AGENT_HOST として PHP プロセスへ渡す例
env[DD_AGENT_HOST] = $SOME_ENV
; 値 'my-app' を DD_SERVICE として PHP
; プロセスへ渡す例
env[DD_SERVICE] = my-app
; または同等の INI 設定を使用
php_value datadog.service my-app```
サーバーコンフィギュレーション、仮想ホスト、ディレクトリ、または `.htaccess` ファイルから [`SetEnv`][2] を使用することも可能です。
```text
# バーチャルホストコンフィギュレーションで環境変数として
SetEnv DD_TRACE_DEBUG 1
# バーチャルホストコンフィギュレーションで INI 設定として
php_value datadog.service my-app
env[...]
ディレクティブの値として false
をサポートしていません。true
のかわりに 1
を、false
のかわりに 0
を使用します。NGINX の場合、php-fpm の www.conf
ファイルの env
ディレクティブを使用します。次に例を示します。
; ホスト環境変数 SOME_ENV を
; DD_AGENT_HOST として PHP プロセスへ渡す例
env[DD_AGENT_HOST] = $SOME_ENV
; 値 'my-app' を DD_SERVICE として PHP
; プロセスへ渡す例
env[DD_SERVICE] = my-app
; または同等の INI 設定を使用
php_value[datadog.service] = my-app
注: NGINX サーバーで APM を有効にしている場合、分散トレースが正常に機能するように opentracing_fastcgi_propagate_context
設定を適切に構成してください。詳細は、NGINX APM コンフィギュレーションを参照してください。
コマンドラインで設定しサーバーを起動します。
DD_TRACE_DEBUG=1 php -d datadog.service=my-app -S localhost:8888
以下のテーブルには、トレースの構成用の環境変数と、対応する INI 設定 (利用可能な場合) およびデフォルトが示されています。
DD_AGENT_HOST
datadog.agent_host
localhost
DD_AUTOFINISH_SPANS
datadog.autofinish_spans
0
DD_DISTRIBUTED_TRACING
datadog.distributed_tracing
1
DD_ENV
datadog.env
null
prod
、pre-prod
、stage
など、アプリケーションの環境を設定します。バージョン 0.47.0
で追加されました。DD_PROFILING_ENABLED
datadog.profiling.enabled
INI は 0.82.0
から利用可能です。1
0.69.0
で追加されました。PHP プロファイラーを有効にする]4を参照してください。バージョン 0.81.0
以降では、デフォルトで 0
になっています。DD_PROFILING_ENDPOINT_COLLECTION_ENABLED
datadog.profiling.endpoint_collection_enabled
INI は 0.82.0
から利用可能です。1
0.79.0
で追加されました。DD_PROFILING_ALLOCATION_ENABLED
datadog.profiling.allocation_enabled
。0.88.0
以降で利用可能な INI。1
0.88.0
で追加されました。
注: これは 0.84
から利用できるようになった DD_PROFILING_EXPERIMENTAL_ALLOCATION_ENABLED
環境変数 (datadog.profiling.experimental_allocation_enabled
INI 設定) よりも優先されます。両方が設定されている場合は、こちらが優先されます。DD_PROFILING_EXPERIMENTAL_CPU_TIME_ENABLED
datadog.profiling.experimental_cpu_time_enabled
。INI は 0.82.0
から利用可能です。1
0.69.0
に追加されています。バージョン 0.76
以下では、デフォルトで 0
になっていました。DD_PROFILING_LOG_LEVEL
datadog.profiling.log_level
。INI は 0.82.0
から利用可能です。off
off
、error
、warn
、info
、debug
、trace
です。プロファイラーのログは、プロセスの標準エラーストリームに書き込まれます。バージョン 0.69.0
に追加されています。DD_PRIORITY_SAMPLING
datadog.priority_sampling
1
DD_SERVICE
datadog.service
null
DD_SERVICE_NAME
に相当します。DD_SERVICE_MAPPING
datadog.service_mapping
null
DD_SERVICE_MAPPING=pdo:payments-db,mysqli:orders-db
(インテグレーション名を参照してください)DD_TRACE_HEALTH_METRICS_ENABLED
datadog.trace_health_metrics_enabled
false
sigaction
が利用可能な場合、トレーサーはセグメンテーションの際にキャッチされない例外のメトリクスを送信します。DD_TRACE_AGENT_ATTEMPT_RETRY_TIME_MSEC
datadog.trace.agent_attempt_retry_time_msec
5000
DD_TRACE_AGENT_CONNECT_TIMEOUT
datadog.trace.agent_connect_timeout
100
DD_TRACE_AGENT_MAX_CONSECUTIVE_FAILURES
datadog.trace.agent_max_consecutive_failures
3
DD_TRACE_AGENT_PORT
datadog.trace.agent_port
8126
receiver_port
や DD_APM_RECEIVER_PORT
をデフォルトの 8126
以外に設定した場合、DD_TRACE_AGENT_PORT
や DD_TRACE_AGENT_URL
をそれに一致させる必要があります。DD_TRACE_AGENT_TIMEOUT
datadog.trace.agent_timeout
500
DD_TRACE_AGENT_URL
datadog.trace.agent_url
null
DD_AGENT_HOST
と DD_TRACE_AGENT_PORT
よりも優先されます。例: https://localhost:8126
Agent 構成で receiver_port
や DD_APM_RECEIVER_PORT
をデフォルトの 8126
以外に設定した場合、DD_TRACE_AGENT_PORT
や DD_TRACE_AGENT_URL
をそれに一致させる必要があります。バージョン 0.47.1
で追加されました。DD_DOGSTATSD_URL
datadog.dogstatsd_url
null
DD_AGENT_HOST
と DD_DOGSTATSD_PORT
よりも優先されます。udp://
または unix://
スキーマのみをサポートします。DD_DOGSTATSD_PORT
datadog.dogstatsd_port
8125
DD_TRACE_HEALTH_METRICS_ENABLED
が有効な場合に、DogStatsD への接続をネゴシエートするために DD_AGENT_HOST
と組み合わせて使用されるポート。DD_TRACE_AUTO_FLUSH_ENABLED
datadog.trace.auto_flush_enabled
0
DD_TRACE_GENERATE_ROOT_SPAN=0
と併せて 1
に設定されます。DD_TRACE_CLI_ENABLED
datadog.trace.cli_enabled
0
DD_TRACE_DEBUG
datadog.trace.debug
0
1
の場合、ログメッセージは INI 設定の error_log
で設定されたデバイスまたはファイルに送信されます。実際の error_log
の値は PHP-FPM/Apache のコンフィギュレーションファイルで上書きされる可能性があるため、php -i
の出力とは異なる場合があります。DD_TRACE_FORKED_PROCESS
datadog.trace.forked_process
1
1
に設定するとフォークされたプロセスをトレースし、0
に設定するとフォークされたプロセスのトレースを無効にします。0
に設定した場合でも、コード内で ini_set("datadog.trace.enabled", "1");
を使って手動でプロセスのトレースを再有効化することができますが、新しいトレースとして表示されることになります。フォークされたプロセスのトレースは、DD_TRACE_FORKED_PROCESS
と DD_DISTRIBUTED_TRACING
の両方が 1
(オン) に構成されている場合にのみ、全体の分散型トレースとして表示されるようになりました。DD_TRACE_ENABLED
datadog.trace.enabled
1
DD_TRACE_GENERATE_ROOT_SPAN
datadog.trace.generate_root_span
1
DD_TRACE_AUTO_FLUSH_ENABLED=1
と併せて 0
に設定されます。DD_TAGS
datadog.tags
null
key1:value1,key2:value2
など、すべてのスパンに設定されるタグ。バージョン 0.47.0
に追加されていますDD_TRACE_HEADER_TAGS
datadog.trace.header_tags
null
DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAIN
datadog.trace.http_client_split_by_domain
0
host-<hostname>
に設定します。例: https://datadoghq.com
に対する curl_exec()
コールのサービス名は、デフォルトのサービス名 curl
ではなく host-datadoghq.com
となります。DD_TRACE_REDIS_CLIENT_SPLIT_BY_HOST
datadog.trace.redis_client_split_by_host
0
redis-<hostname>
に設定します。バージョン 0.51.0
に追加されています DD_TRACE_<INTEGRATION>_ENABLED
datadog.trace.<INTEGRATION>_enabled
1
0.47.1
以前の場合、このパラメーターは DD_INTEGRATIONS_DISABLED
に相当し、無効にするインテグレーションの CSV リストを取得します (例: curl,mysqli
)。DD_TRACE_MEASURE_COMPILE_TIME
datadog.trace.measure_compile_time
1
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
datadog.trace.resource_uri_fragment_regex
null
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
datadog.trace.resource_uri_mapping_incoming
null
DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
datadog.trace.resource_uri_mapping_outgoing
null
DD_TRACE_RETAIN_THREAD_CAPABILITIES
datadog.trace.retain_thread_capabilities
0
true
に設定すると、有効なユーザー ID を変更しても Datadog のバックグラウンドスレッド機能を維持することができます。このオプションはほとんどの設定には影響しませんが、一部のモジュールで影響が出る場合があります。現時点で Datadog が確認している限りでは、Apache の mod-ruid2 で setuid()
や類似の syscall を呼び出した場合に影響が生じ、クラッシュや機能の不具合につながる可能性があります。setcap
ユーティリティを使用して Web サーバーの機能を制限することをお勧めしています。DD_TRACE_SAMPLE_RATE
datadog.trace.sample_rate
1.0
0.0
および 1.0
)。0.36.0
以前では、このパラメーターは DD_SAMPLING_RATE
となります。DD_TRACE_SAMPLING_RULES
datadog.trace.sampling_rules
null
'[{"sample_rate": 0.2}]'
となります。‘a’ ではじまる、スパン名が ‘b’ のサービスのサンプルレートを 10% に、その他のサービスのサンプルレートを 20% に設定する場合は '[{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]'
のようになります (インテグレーション名 を参照してください) 。二重引用符 ("
) のエスケープ処理による問題を防ぐため、JSON オブジェクトは必ず単一引用符 ('
) で囲むようにしてください。DD_TRACE_RATE_LIMIT
datadog.trace.rate_limit
0
DD_TRACE_SPANS_LIMIT
datadog.trace.spans_limit
1000
memory_limit
で増加できます。DD_SPAN_SAMPLING_RULES
datadog.span_sampling_rules
null
sample_rate
の値は 0.0 から 1.0 の間でなければなりません (この値を含む)。'[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'
JSON オブジェクトは、ダブルクォート ('
) 文字のエスケープの問題を避けるために、シングルクォート ("
) で囲む必要があります。DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED
datadog.trace.url_as_resource_names_enabled
1
DD_VERSION
datadog.version
null
1.2.3
、6c44da20
、2020.02.13
) を設定します。バージョン 0.47.0
で追加されました。DD_TRACE_HTTP_URL_QUERY_PARAM_ALLOWED
datadog.trace.http_url_query_param_allowed
*
*
を設定します。バージョン 0.74.0
で追加されました。DD_TRACE_HTTP_POST_DATA_PARAM_ALLOWED
datadog.trace.http_post_data_param_allowed
*
に設定した場合、POST 送信されたすべてのデータが収集されますが、DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
難読化ルールに一致するフィールドの値は編集されます。特定のフィールドが指定された場合、これらのフィールドの値のみが表示され、その他すべてのフィールドの値は編集されます。バージョン 0.86.0
で追加されました。qux=quux&foo[bar][password]=Password12!&foo[bar][username]=admin&foo[baz][bar]=qux&foo[baz][key]=value
DD_TRACE_HTTP_POST_DATA_PARAM_ALLOWED
は foo.baz,foo.bar.password
に設定http.request.foo.bar.password=Password12!
http.request.foo.bar.username=<redacted>
http.request.foo.baz.bar=qux
http.request.foo.baz.key=value
http.request.qux=<redacted>
DD_TRACE_RESOURCE_URI_QUERY_PARAM_ALLOWED
datadog.trace.resource_uri_query_param_allowed
*
*
を設定します。バージョン 0.74.0
で追加されました。DD_TRACE_CLIENT_IP_ENABLED
datadog.trace.client_ip_enabled
false
0.84.0
で追加されました。DD_TRACE_CLIENT_IP_HEADER
datadog.trace.client_ip_header
null
x-forwarded-for
。バージョン 0.84.0
(ASM を使用している場合は 0.76.0
) で追加されました。DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
datadog.trace.obfuscation_query_string_regexp
(?i)(?:p(?:ass)?w(?:or)?d|pass(?:_?phrase)?|secret|(?:api_?|private_?|public_?|access_?|secret_?)key(?:_?id)?|token|consumer_?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?)(?:(?:\s|%20)*(?:=|%3D)[^&]+|(?:"|%22)(?:\s|%20)*(?::|%3A)(?:\s|%20)*(?:"|%22)(?:%2[^2]|%[^2]|[^"%])+(?:"|%22))|bearer(?:\s|%20)+[a-z0-9\._\-]|token(?::|%3A)[a-z0-9]{13}|gh[opsu]_[0-9a-zA-Z]{36}|ey[I-L](?:[\w=-]|%3D)+\.ey[I-L](?:[\w=-]|%3D)+(?:\.(?:[\w.+\/=-]|%3D|%2F|%2B)+)?|[\-]{5}BEGIN(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY[\-]{5}[^\-]+[\-]{5}END(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY|ssh-rsa(?:\s|%20)*(?:[a-z0-9\/\.+]|%2F|%5C|%2B){100,}
URL の一部として含まれるクエリ文字列を難読化するために使用される正規表現。この表現は、HTTP POST データの編集プロセスでも使用されます。バージョン 0.76.0
で追加されました。
DD_TRACE_PROPAGATION_STYLE_INJECT
datadog.trace.propagation_style_inject
tracecontext,Datadog
DD_TRACE_PROPAGATION_STYLE_EXTRACT
datadog.trace.propagation_style_extract
tracecontext,Datadog,b3multi,B3 single header
DD_DBM_PROPAGATION_MODE
datadog.dbm_propagation_mode
'disabled'
'service'
または 'full'
に設定すると、APM から送信されるデータとデータベースモニタリング製品との連携が可能になります。'service'
オプションは、DBM と APM のサービス間の接続を有効にします。Postgres、MySQL、SQLServer で利用可能です。'full'
オプションは、データベースクエリイベントを持つデータベーススパン間の接続を可能にします。Postgres と MySQL で利用可能です。以下の表は、各インテグレーションに紐付くデフォルトのサービス名をまとめたものです。サービス名は DD_SERVICE_MAPPING
に変更してください。
インテグレーション固有のコンフィギュレーションを設定する場合は、DD_TRACE_<INTEGRATION>_ENABLED
形式で名前を付けてください。例: Laravel の場合、 DD_TRACE_LARAVEL_ENABLED
。
インテグレーション | サービス名 |
---|---|
CakePHP | cakephp |
CodeIgniter | codeigniter |
cURL | curl |
ElasticSearch | elasticsearch |
Eloquent | eloquent |
Guzzle | guzzle |
Laravel | laravel |
Lumen | lumen |
Memcached | memcached |
Mongo | mongo |
Mysqli | mysqli |
PDO | pdo |
PhpRedis | phpredis |
Predis | predis |
Slim | slim |
Symfony | symfony |
WordPress | wordpress |
Yii | yii |
ZendFramework | zendframework |
DD_TRACE_RESOURCE_URI_MAPPING
は非推奨となります。しばらくはまだ機能しますが、レガシーサポートが外された際の問題を回避するために、ここにある新しい設定を使用することを強くお勧めします。以下の設定: DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
、DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
、DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
は新しいリソース正規化アプローチをオプトインし、DD_TRACE_RESOURCE_URI_MAPPING
の値はすべて無視されることに注意してください。
HTTP サーバーとクライアントインテグレーションでは、URL はクエリ文字列が URL から削除された状態で、トレースリソース名を作成するために <HTTP_REQUEST_METHOD> <NORMALIZED_URL>
の形式で使用されます。URL を正規化し 1 つのリソースの下に一般的なエンドポイントをグループ化することで、自動インスツルメンテーションされないカスタムフレームワークにおける可視性を向上することができます。
HTTP リクエスト | リソース名 |
---|---|
GET request to /foo?a=1&b=2 | GET /foo |
POST request to /bar?foo=bar | POST /bar |
数値 ID、UUID (ダッシュの有無不問)、32〜512 ビットの 16 進数ハッシュは、自動的に ?
に置換されます。
URL (GET リクエスト) | リソース名 |
---|---|
/user/123/show | GET /user/?/show |
/widget/b7a992e0-3300-4030-8617-84553b11c993 | GET /widget/? |
/api/v2/b7a992e033004030861784553b11c993/123 | GET /api/v2/?/? |
/book/0dbf3596 | GET /book/? |
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=0
を使用してこの機能をオフにすることも可能です。
適用された自動正規化ではカバーされないケースがいくつかあります。
URL (GET リクエスト) | 考えられるリソース名 |
---|---|
/using/prefix/id123/for/id | GET /using/prefix/?/for/id |
/articles/slug-of-title | GET /articles/? |
/cities/new-york/rivers | GET /cities/?/rivers |
/nested/cities/new-york/rivers | GET /nested/cities/?/rivers |
自動正規化ではカバーされないシナリオには、次の 2 つのクラスがあります。
id<number>
)。このシナリオは、次の DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
設定でカバーされます。/cities/new-york
は、new-york
は都市名のため正規化する必要があることが分かります。このシナリオは以下の設定でカバーされます DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
、 DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
(それぞれ、受信リクエストと発信リクエスト)。DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
この設定は、各パスフラグメントに個々に適用される正規表現の CSV です。たとえば、 /using/prefix/id123/for/id
のパスとして DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
を ^id\d+$
に設定すると、各フラグメント(using
、prefix
、id123
、for
、id
)に正規表現が適用されます。
URL | 正規表現 | 考えられるリソース名 |
---|---|---|
/using/prefix/id123/for/id | ^id\d+$ | GET /using/prefix/?/for/id |
この変数の形式は CSV であるため、カンマ記号 ,
はエスケープされず、正規表現では使用できないことに注意してください。
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
および DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
この設定はワイルドカード *
を含むことのできるパターンの CSV です。たとえば、パターン cities/*
を追加すると、URL を分析中にフラグメント cities
が見つかる度に、次のフラグメントがある場合 ?
に置き換えられます。パターンは深さを問わず適用されるため、次の規則を適用することで、上記の表の /cities/new-york
と /nested/cities/new-york
の両方が正規化されます。
パターンは特定のフラグメントの一部に適用することもできます。たとえば、path/*-fix
は URL /some/path/changing-fix/nested
を /some/path/?-fix/nested
に正規化します。
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
は受信リクエスト(ウェブフレームワークなど)のみに適用され、DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
は発信リクエスト(curl
や guzzle
リクエストなど)のみに適用されることに、ご注意ください。
open_basedir
制限open_basedir
設定が使用される場合、許可されるディレクトリに /opt/datadog-php
を追加する必要があります。
アプリケーションを Docker コンテナで実行する場合は、許可されるディレクトリにパス /proc/self
も追加する必要があります。
分散トレースコンテキストの伝播を目的としてヘッダーの抽出と挿入を行うための PHP トレーシングライブラリの構成については、トレースコンテキストの伝播をお読みください。