Metriken

DuckDB stellt eine Reihe von Metriken bereit, mit denen Leistung und Zustand der Datenbank überwacht werden können.

Der Query-Baum hat zwei Knotentypen: die Knoten QUERY_ROOT und OPERATOR. QUERY_ROOT bezeichnet ausschließlich den obersten Knoten; die darin enthaltenen Metriken werden über die gesamte Abfrage gemessen. Die Knoten OPERATOR bezeichnen die einzelnen Operatoren im Abfrageplan. Manche Metriken sind nur für QUERY_ROOT-Knoten verfügbar, andere nur für OPERATOR-Knoten. Die folgende Tabelle beschreibt jede Metrik und für welche Knoten sie verfügbar ist.

Außer OPERATOR_TYPE können alle Metriken ein- oder ausgeschaltet werden.

Alle Metriken

Name	Gruppe	Beschreibung
`CPU_TIME`	core	CPU-Zeit, die für die Abfrage aufgewendet wurde
`CUMULATIVE_CARDINALITY`	core	Kumulative Kardinalität der Abfrage
`CUMULATIVE_ROWS_SCANNED`	core	Kumulative Anzahl der von der Abfrage gescannten Zeilen
`EXTRA_INFO`	core	Einzigartige Operator-Metriken
`LATENCY`	core	Zeit für die Ausführung der gesamten Abfrage
`QUERY_NAME`	core	Die SQL-Zeichenkette der Abfrage
`RESULT_SET_SIZE`	core	Die Größe des Ergebnisses
`ROWS_RETURNED`	core	Die Anzahl der von der Abfrage zurückgegebenen Zeilen
`BLOCKED_THREAD_TIME`	execution	Wartezeit, bis ein Thread verfügbar wird
`SYSTEM_PEAK_BUFFER_MEMORY`	execution	Spitzenspeicherverbrauch des Systems
`SYSTEM_PEAK_TEMP_DIR_SIZE`	execution	Spitzengröße des temporären Verzeichnisses
`TOTAL_MEMORY_ALLOCATED`	execution	Der vom Buffer Manager insgesamt zugewiesene Speicher.
`ATTACH_LOAD_STORAGE_LATENCY`	file	Zeit für das Laden aus dem Storage.
`ATTACH_REPLAY_WAL_LATENCY`	file	Zeit für das Replay der WAL-Datei.
`CHECKPOINT_LATENCY`	file	Zeit für das Ausführen von Checkpoints
`COMMIT_LOCAL_STORAGE_LATENCY`	file	Zeit für das Committen des transaktionslokalen Speichers.
`TOTAL_BYTES_READ`	file	Die vom Dateisystem insgesamt gelesenen Bytes.
`TOTAL_BYTES_WRITTEN`	file	Die vom Dateisystem insgesamt geschriebenen Bytes.
`WAITING_TO_ATTACH_LATENCY`	file	Wartezeit, um eine Datei per ATTACH anzuhängen.
`WAL_REPLAY_ENTRY_COUNT`	file	Die Gesamtzahl der in der WAL wiederzugebenden Einträge.
`WRITE_TO_WAL_LATENCY`	file	Zeit für das Schreiben in die WAL.
`ALL_OPTIMIZERS`	phase_timing	Aktiviert alle Optimizer
`CUMULATIVE_OPTIMIZER_TIMING`	phase_timing	Zeit in allen Optimizern
`PHYSICAL_PLANNER`	phase_timing	Die Zeit für die Erzeugung des physischen Plans
`PHYSICAL_PLANNER_COLUMN_BINDING`	phase_timing	Die Zeit für das Binden der Spalten im logischen Plan an physische Spalten
`PHYSICAL_PLANNER_CREATE_PLAN`	phase_timing	Die Zeit für das Erstellen des physischen Plans
`PHYSICAL_PLANNER_RESOLVE_TYPES`	phase_timing	Die Zeit für das Auflösen der Typen im logischen Plan zu physischen Typen
`PLANNER`	phase_timing	Die Zeit, um aus den geparsten SQL-Knoten den logischen Plan zu erzeugen.
`PLANNER_BINDING`	phase_timing	Die Zeit für das Binden des logischen Plans.
`OPERATOR_CARDINALITY`	operator	Kardinalität des Operators
`OPERATOR_NAME`	operator	Name des Operators
`OPERATOR_ROWS_SCANNED`	operator	Anzahl der vom Operator gescannten Zeilen
`OPERATOR_TIMING`	operator	Zeit im Operator
`OPERATOR_TYPE`	operator	Typ des Operators

Metrikgruppen

Die Metriken sind in Gruppen organisiert, mit denen zusammengehörige Metriken gemeinsam ein- oder ausgeschaltet werden können. Die folgenden Metrikgruppen sind verfügbar:

ALL: Alle Metriken
DEFAULT: Der Standard-Metriksatz
CORE
EXECUTION
FILE
OPERATOR
OPTIMIZER
PHASE_TIMING

Kernmetriken {#core-metrics}

Kernmetriken

`CPU_TIME`

Hinweis:

CPU_TIME misst die kumulativen Operatorzeiten. Zeit in anderen Phasen wie Parsen, Query Planning usw. ist nicht enthalten. Daher kann bei manchen Abfragen die LATENCY im QUERY_ROOT größer sein als die CPU_TIME.

`CUMULATIVE_CARDINALITY`

`CUMULATIVE_ROWS_SCANNED`

`EXTRA_INFO`

`LATENCY`

`QUERY_NAME`

`RESULT_SET_SIZE`

`ROWS_RETURNED`

Ausführungsmetriken {#execution-metrics}

Metriken, die während der Abfrageausführung erfasst werden

`BLOCKED_THREAD_TIME`

`SYSTEM_PEAK_BUFFER_MEMORY`

`SYSTEM_PEAK_TEMP_DIR_SIZE`

`TOTAL_MEMORY_ALLOCATED`

Dateimetriken {#file-metrics}

Metriken, die bei Dateioperationen erfasst werden

`ATTACH_LOAD_STORAGE_LATENCY`

`ATTACH_REPLAY_WAL_LATENCY`

`CHECKPOINT_LATENCY`

`COMMIT_LOCAL_STORAGE_LATENCY`

`TOTAL_BYTES_READ`

`TOTAL_BYTES_WRITTEN`

`WAITING_TO_ATTACH_LATENCY`

`WAL_REPLAY_ENTRY_COUNT`

`WRITE_TO_WAL_LATENCY`

Operator-Metriken {#operator-metrics}

Metriken, die für jeden Operator erfasst werden

`OPERATOR_CARDINALITY`

`OPERATOR_NAME`

`OPERATOR_ROWS_SCANNED`

`OPERATOR_TIMING`

`OPERATOR_TYPE`

Phase_timing-Metriken {#phase_timing-metrics}

Diese Gruppe enthält Metriken zum Planner und zum Physical Planner. Der Planner erzeugt den logischen Plan, der Physical Planner erzeugt aus dem logischen Plan den physischen Plan.

`ALL_OPTIMIZERS`

`CUMULATIVE_OPTIMIZER_TIMING`

`PHYSICAL_PLANNER`

`PHYSICAL_PLANNER_COLUMN_BINDING`

`PHYSICAL_PLANNER_CREATE_PLAN`

`PHYSICAL_PLANNER_RESOLVE_TYPES`

`PLANNER`

`PLANNER_BINDING`

Optimizer-Metriken {#optimizer-metrics}

Optimizer-Metriken sitzen auf der Ebene QUERY_ROOT und messen die Zeit jedes Optimizers. Diese Metriken sind nur verfügbar, wenn der jeweilige Optimizer aktiviert ist. Die verfügbaren Optimierungen können mit der Tabellenfunktion duckdb_optimizers(){:.language-sql .highlight} abgefragt werden.

Jeder Optimizer hat eine zugehörige Metrik nach dem Schema: OPTIMIZER_⟨OPTIMIZER_NAME⟩{:.language-sql .highlight}. Zum Beispiel entspricht die Metrik OPTIMIZER_JOIN_ORDER dem Optimizer JOIN_ORDER.

Zusätzlich stehen die folgenden Metriken zur Unterstützung der Optimizer-Metriken zur Verfügung:

ALL_OPTIMIZERS
CUMULATIVE_OPTIMIZER_TIMING

Kumulative Metriken {#cumulative-metrics}

DuckDB unterstützt außerdem mehrere kumulative Metriken, die in allen Knoten verfügbar sind. Im Knoten QUERY_ROOT stellen diese Metriken die Summe der entsprechenden Metriken über alle Operatoren der Abfrage dar. Die OPERATOR-Knoten stellen die Summe der jeweiligen Operator-Metrik und derjenigen aller Kindknoten rekursiv dar.

Diese kumulativen Metriken können unabhängig aktiviert werden, auch wenn die zugrunde liegenden spezifischen Metriken deaktiviert sind.

Die folgenden kumulativen Metriken sind verfügbar:

CPU_TIME
CUMULATIVE_CARDINALITY
CUMULATIVE_ROWS_SCANNED
CUMULATIVE_OPTIMIZER_TIMING

Beispiele

Die folgenden Beispiele zeigen, wie Sie benutzerdefiniertes Profiling aktivieren und das Ausgabeformat auf json setzen. Im ersten Beispiel aktivieren wir Profiling und schreiben die Ausgabe in eine Datei. Wir aktivieren nur EXTRA_INFO, OPERATOR_CARDINALITY und OPERATOR_TIMING.

CREATE TABLE students (name VARCHAR, sid INTEGER);
CREATE TABLE exams (eid INTEGER, subject VARCHAR, sid INTEGER);
INSERT INTO students VALUES ('Mark', 1), ('Joe', 2), ('Matthew', 3);
INSERT INTO exams VALUES (10, 'Physics', 1), (20, 'Chemistry', 2), (30, 'Literature', 3);

PRAGMA enable_profiling = 'json';
PRAGMA profiling_output = '/path/to/file.json';

PRAGMA configure_profiling = '{"CPU_TIME": "false", "EXTRA_INFO": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TIMING": "true"}';

SELECT name
FROM students
JOIN exams USING (sid)
WHERE name LIKE 'Ma%';

Der Inhalt der Datei nach Ausführung der Abfrage:

{
    "extra_info": {},
    "query_name": "SELECT name\nFROM students\nJOIN exams USING (sid)\nWHERE name LIKE 'Ma%';",
    "children": [
        {
            "operator_timing": 0.000001,
            "operator_cardinality": 2,
            "operator_type": "PROJECTION",
            "extra_info": {
                "Projections": "name",
                "Estimated Cardinality": "1"
            },
            "children": [
                {
                    "extra_info": {
                        "Join Type": "INNER",
                        "Conditions": "sid = sid",
                        "Build Min": "1",
                        "Build Max": "3",
                        "Estimated Cardinality": "1"
                    },
                    "operator_cardinality": 2,
                    "operator_type": "HASH_JOIN",
                    "operator_timing": 0.00023899999999999998,
                    "children": [
...

Das zweite Beispiel fügt der Ausgabe detaillierte Metriken hinzu.

PRAGMA profiling_mode = 'detailed';

SELECT name
FROM students
JOIN exams USING (sid)
WHERE name LIKE 'Ma%';

Der Inhalt der ausgegebenen Datei:

{
  "all_optimizers": 0.001413,
  "cumulative_optimizer_timing": 0.0014120000000000003,
  "planner": 0.000873,
  "planner_binding": 0.000869,
  "physical_planner": 0.000236,
  "physical_planner_column_binding": 0.000005,
  "physical_planner_resolve_types": 0.000001,
  "physical_planner_create_plan": 0.000226,
  "optimizer_expression_rewriter": 0.000029,
  "optimizer_filter_pullup": 0.000002,
  "optimizer_filter_pushdown": 0.000102,
...
  "optimizer_column_lifetime": 0.000009999999999999999,
  "rows_returned": 2,
  "latency": 0.003708,
  "cumulative_rows_scanned": 6,
  "cumulative_cardinality": 11,
  "extra_info": {},
  "cpu_time": 0.000095,
  "optimizer_build_side_probe_side": 0.000017,
  "result_set_size": 32,
  "blocked_thread_time": 0.0,
  "query_name": "SELECT name\nFROM students\nJOIN exams USING (sid)\nWHERE name LIKE 'Ma%';",
  "children": [
    {
      "operator_timing": 0.000001,
      "operator_rows_scanned": 0,
      "cumulative_rows_scanned": 6,
      "operator_cardinality": 2,
      "operator_type": "PROJECTION",
      "cumulative_cardinality": 11,
      "extra_info": {
        "Projections": "name",
        "Estimated Cardinality": "1"
      },
      "result_set_size": 32,
      "cpu_time": 0.000095,
      "children": [
...