apmtrace.get

説明

integer/array apmtrace.get(object parameters)

このメソッドを使用すると、指定したパラメータに従ってトレースを取得できます。

このメソッドは、すべてのタイプのユーザーが使用できます。 メソッドを呼び出す権限は、ユーザーロールの設定で取り消すことができます。 詳細については、ユーザーロールを参照してください。

パラメータ

(object) 目的の出力を定義するパラメータ。

このメソッドは、以下のパラメータをサポートしています。

パラメータ タイプ 説明
time_from timestamp 指定した時刻以降にルートスパンが開始されたトレースのみを返します。

パラメータの動作:
- 必須
time_till timestamp 指定した時刻より前にルートスパンが開始されたトレースのみを返します。

パラメータの動作:
- 必須
traceids string/array 指定したIDを持つトレースのみを返します。
resource_attributes object/array 指定したリソース属性をルートスパンが持つトレースのみを返します。
形式: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...]。
空の配列を指定すると、すべてのトレースを返します。

指定可能な演算子の値:
0 - (デフォルト) 含む;
1 - 等しい;
2 - 含まない;
3 - 等しくない;
4 - 存在する;
5 - 存在しない。
resource_attributes_evaltype integer resource_attributes の条件に対する評価方法。

指定可能な値:
0 - (デフォルト) And/Or;
2 - Or。
span_attributes object/array 指定したスパン属性をルートスパンが持つトレースのみを返します。
形式: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...]。
空の配列を指定すると、すべてのトレースを返します。

指定可能な演算子の値:
0 - (デフォルト) 含む;
1 - 等しい;
2 - 含まない;
3 - 等しくない;
4 - 存在する;
5 - 存在しない。
span_attributes_evaltype integer span_attributes の条件に対する評価方法。

指定可能な値:
0 - (デフォルト) And/Or;
2 - Or。
min_duration integer ルートスパンの duration が指定した値以上であるトレースのみを、ナノ秒単位で返します。
max_duration integer ルートスパンの duration が指定した値未満であるトレースのみを、ナノ秒単位で返します。
filter object 指定したフィルターに完全に一致する結果のみを返します。

プロパティ名をキーとし、一致させる単一の値または値の配列を値とするオブジェクトを受け取ります。

サポートされるプロパティ: traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, status_code, status_message。
search object 指定したパターンに一致する結果を返します（大文字と小文字を区別しません）。

プロパティ名をキーとし、検索対象の文字列を値とするオブジェクトを受け取ります。追加のオプションを指定しない場合、LIKE "%…%" 検索を実行します。

サポートされるプロパティ: trace_state, span_name, service_name, scope_name, scope_version, status_message。
sortfield string/array 指定したプロパティで結果をソートします。

指定可能な値: timestamp, traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, duration, status_code, status_message。
offset integer 結果を返す前にスキップするレコード数。
countOutput boolean これらのパラメータについては、リファレンスコメントで説明しています。
excludeSearch boolean
limit integer
output query
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch boolean

戻り値

(integer/array) 以下のいずれかを返します。

  • オブジェクトの配列
  • countOutput パラメータが使用されている場合は、取得したオブジェクトの数

例

遅いトレースの取得

zabbix-nginx サービスの中で最も遅い2つのトレースを取得します。
2026年10月1日（UTC）の10:00から11:00までのトレースを検索し、所要時間が1秒以上のものだけを含めます。

リクエスト:

{
    "jsonrpc": "2.0",
    "method": "apmtrace.get",
    "params": {
        "output": ["timestamp", "traceid", "span_name", "service_name", "duration", "status_code", "span_count", "error_count"],
        "time_from": 1790848800,
        "time_till": 1790852400,
        "filter": {
            "service_name": "zabbix-nginx"
        },
        "min_duration": 1000000000,
        "sortfield": "duration",
        "sortorder": "DESC",
        "limit": 2
    },
    "id": 1
}

レスポンス:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "timestamp": "1790849274910226417",
            "traceid": "8a4f1c7e2b9d4e6fa0c3b5d7e9f1a2c4",
            "span_name": "POST /zabbix.php",
            "service_name": "zabbix-nginx",
            "duration": "30412907815",
            "status_code": "Error",
            "span_count": "49",
            "error_count": "2"
        },
        {
            "timestamp": "1790850512338104952",
            "traceid": "dee625f33cb0994e86c5cd4640e3b09c",
            "span_name": "POST /zabbix.php",
            "service_name": "zabbix-nginx",
            "duration": "1104826531",
            "status_code": "Unset",
            "span_count": "27",
            "error_count": "0"
        }
    ],
    "id": 1
}

関連項目

ソース

ui/include/classes/api/services/CApmTrace.php の CApmTrace::get()。