Get database measures

Die Funktion Get database measures gibt detaillierte Informationen über Ereignisse der 4D Datenbank Engine zurück. Dies umfasst Lese- und Schreibzugriffe auf die Festplatte oder den Memory Cache, sowie die Verwendung von Indizes, Suchen und Sortieren in der Datenbank.

Get database measures gibt ein einzelnes Objekt mit allen relevanten Messwerten zurück. Im Parameter Optionen können Sie die gewünschten Informationen genauer definieren.

Das zurückgegebene Objekt enthält eine einzelne Eigenschaft mit Namen "DB" mit folgender Grundstruktur:

Dieses Objekt enthält bis zu acht elementare Eigenschaften mit Messwerten ("diskReadBytes", "cacheReadBytes", "cacheMissBytes", "diskWriteBytes", "diskReadCount", "cacheReadCount", "cacheMissCount", "diskWriteCount") gültig für die gesamte Datenbank, sowie zusätzlich eine weitere Unterteilung in "dataSegment1", "indexSegment", "tables", "indexes". Diese Eigenschaften haben wiederum selbst die elementaren Eigenschaften, jeweils gültig für die entsprechende Untergruppe. Diese fein abgestimmte Unterteilung erlaubt die Analyse der Datenzugriffe je nach Bedarf vom Gesamtsystem bis hin zu Zugriffen auf einzelne Tabellen oder Indizes.

Hinweis: Eine Eigenschaft erscheint nur im Objekt, wenn sie Inhalt enthält. Eine Eigenschaft ohne Inhalt wird nicht in das Objekt aufgenommen. Wurde die Anwendung z.B. im Nur-Lesen Modus geöffnet und keine Indizes verwendet, enthält das zurückgegebene Objekt nicht die Messwerte "diskWriteBytes", "diskWriteCount", "indexSegment" und "indexes".

Elementare Eigenschaften gibt es auf verschiedenen Ebenen im Objekt DB. Sie enthalten dieselbe Informationsart, aber für unterschiedliche Datenbankobjekte. Hier die Beschreibung der einzelnen Eigenschaften:

Alle acht elementaren Eigenschaften enthalten dieselbe Objektunterstruktur. Hier ein Beispiel:

"diskReadBytes": {
    "value": 33486473620,
    "history": [        // optional
        {"value": 52564,"time": -1665},
        {"value": 54202,"time": -1649},
            …
    ]
}

• "value" (Zahl): Die Eigenschaft "value" enthält eine Zahl, die entweder eine Anzahl Bytes oder eine Anzahl Zugriffe angibt. Dieser Wert ist im allgemeinen die Summe der Werte des Objekts "history" (auch wenn das Objekt "history" nicht vorhanden ist).

• "history" (Array der Objekte): Das Array "history" ist eine Zusammenstellung von Ereigniswerten, gruppiert nach Sekunden. Die Eigenschaft "history" gibt es nur, wenn sie über den Parameter Optionen angefordert wurde (siehe unten). Dieses Array enthält maximal 200 Einträge. Jedes Element des Array ist selbst ein Objekt mit den beiden Eigenschaften "value" und "time".
  
  • "value" (Zahl): Anzahl Bytes oder Zugriffe, die während der Zeitspanne, definiert in der zugeordneten Eigenschaft "time", verwaltet wird.
  • "time" (Zahl): Anzahl Sekunden, die seit Aufrufen der Funktion verstrichen ist. Im obigen Beispiel ("time": -1649) bedeutet die Zahl vor 1649 Sekunden, oder genauer zwischen den Sekunden 1649 und 1650. In dieser Zeitspanne von einer Sekunde wurden 54.202 Bytes auf die Festplatte gelesen.
    Das Array "history" enthält keine sequentiellen Werte (-1650,-1651,-1652, etc.). Der vorige Wert ist -1665, d.h., in den 15 Sekunden zwischen 1650 und 1665 wurde nichts von der Festplatte gelesen.
    Hinweis: Das Array enthält nur vorhandene Informationen. Werte mit Null sind nicht aufgeführt.
    Da die Größe des Array auf 200 begrenzt ist, ist "history" bei intensiver Nutzung der Datenbank (jede Sekunde wird etwas auf die Festplatte gelesen) 200 Sekunden lang. Passiert dagegen nur wenig, gibt es z.B. nur alle 3 Minuten ein Ereignis, kann "history" 600 Minuten (3*200) enthalten.
    Hierzu ein Beispiel:
    

Die Eigenschaften "dataSegment1" und "indexSegment" enthalten bis zu vier der elementaren Eigenschaften (sofern verfügbar):

Diese Eigenschaften enthalten dieselbe Information wie die elementaren Eigenschaften, jedoch aufgeschlüsselt nach Datei der Datenbank:

• "dataSegment1" ist die Datendatei .4dd auf der Festplatte
• "indexSegment" ist die Indexdatei .4dx auf der Festplatte

Ihr Objekt könnte z.B. folgendermaßen aussehen:

{
"DB": {
"diskReadBytes": {
    "value": 718260
    },
"diskReadCount": {
    "value": 229
    },

"dataSegment1": {
    "diskReadBytes": {
    "value": 679092
    },
    "diskReadCount": {
    "value": 212
    }
    },
"indexSegment": {
    "diskReadBytes": {
    "value": 39168
    },
    "diskReadCount": {
    "value": 17
    }
}

Die Werte werden so berechnet:

diskReadBytes.value = dataSegment1.diskReadBytes.value + indexSegment.diskReadBytes.value
diskWriteBytes.value = dataSegment1.diskWriteBytes.value + indexSegment.diskWriteBytes.value
diskReadCount.value = dataSegment1.diskReadCount.value + indexSegment.diskReadCount.value
diskWriteCount.value = dataSegment1.diskWriteCount.value + indexSegment.diskWriteCount.value

Die Eigenschaft "tables" enthält alle Tabellen, auf die seit Öffnen der Datenbank im Lese- oder Schreibmodus zugegriffen wurde. Der Name der Eigenschaft leitet sich vom jeweiligen Tabellennamen ab, zum Beispiel: 

"tables": {
    "Employees": {…)
    "Companies": {…)
    }

Jedes Objekt "table" enthält 10 Eigenschaften:

• Die ersten acht Eigenschaften sind die elementaren Eigenschaften (siehe oben) mit Werten zur betreffenden Tabelle.
• Die beiden anderen Eigenschaften "records" und "blobs" haben dieselben acht Eigenschaften, jedoch nur für bestimmte Feldtypen:
  
  • Die Eigenschaft "records" betrifft alle Feldtypen der Tabelle (Strings, Datum, Zahlenarten, etc.) mit Ausnahme von Text, Bild und Blobs
  • Die Eigenschaft "blobs" betrifft die Felder vom Typ Text, Bild und Blob der Tabelle.

Je nach Such- oder Sortierläufen in der Tabelle können zusätzliche Eigenschaften "fields" und "queries" vorhanden sein:

• Die Eigenschaft "fields" enthält soviel Attribute "field name" (die auch Unterobjekte sind), wie Felder für Suchen oder Sortieren verwendet werden.
  Jedes Objekt Feldname enthält:
  
  • Ein Objekt "queryCount" (mit oder ohne Chronik, abhängig vom Parameter Optionen), wenn eine Suche mit diesem Feld ausgeführt wurde.
  • und/oder ein Objekt "sortCount" (mit oder ohne Chronik, abhängig vom Parameter Optionen), wenn eine Sortierung mit diesem Feld ausgeführt wurde.
  Dieses Attribut basiert nicht auf der Verwendung von Indizes; alle Such- und Sortierläufe werden berücksichtigt.
  Beispiel: Seit Starten der Datenbank wurden mehrere Such- und Sortierläufe mit den Feldern CompID, Name und FirstName ausgeführt. Das zurückgegebene Objekt enthält das folgende Unterobjekt "fields" (Optionen sind mit Pfad und ohne Chronik):
  
  

  {
      "DB": {
          "tables": {
              "Employees": {
                  "fields": {
                      "CompID": {
                          "queryCount": {
                              "value": 3
                          }
                      },
                      "Name": {
                          "queryCount": {
                              "value": 1
                          },
                          "sortCount": {
                              "value": 3
                          }
                      },
                      "FirstName": {
                          "sortCount": {
                              "value": 2
                          }
                      }
  (...)

  
  Hinweis: Das Attribut "fields" wird nur erstellt, wenn in der Tabelle eine Suche oder Sortierung durchgeführt wurde; andernfalls ist dieses Attribut nicht vorhanden.

• "queries" ist ein Array mit Objekten, das jede in der Tabelle durchgeführte Suche beschreibt. Jedes Element des Array enthält drei Attribute:

  • "queryStatement" (String): Suchstring (enthält Feldnamen, aber keine Werte der Suchkriterien). Zum Beispiel: "(Companies.PK_ID != ?)"
  • "queryCount" (Objekt):
    
    • "value" (Zahl): wieviele Male die Suchanweisung ausgeführt wurde, unabhängig von den Werten der Suchkriterien.
    • "history" (Array mit Objekten) (wenn in Optionen angefordert): "value" und "time" standardmäßige Chronik-Eigenschaften
  • "duration" (Objekt) wenn "value" >0)
    
    • "value" (Zahl): Anzahl Millisekunden
    • "history" (Array mit Objekten) (wenn in Optionen angefordert): "value" und "time" standardmäßige Chronik-Eigenschaften

  Beispiel: Seit dem Start der Datenbank wurde in der Tabelle Employees eine Suche durchgeführt (Optionen sind mit Pfad und ohne Chronik):
  

  {
      "DB": {
          "tables": {
              "Employees": {
                  "queries": [
                      {
                          "queryStatement": "(Employees.Name == ?)",
                          "queryCount": {
                              "value": 1,
                              "history": [
                                  {
                                      "value": 1,
                                      "time": -2022
                                  }
                              ]
                          },
                          "duration": {
                              "value": 2,
                              "history": [
                                  {
                                      "value": 2,
                                      "time": -2022
                                  }
                              ]
                          }
                      },
  (...)

  
  
  Hinweis: Das Attribut "queries" wird erstellt, wenn in der Tabelle mindestens eine Suche durchgeführt wurde.

Dies ist das umfangreichste Objekt. Alle Tabellen, auf die über einen oder mehrere Indizes zugegriffen wurde, werden als Eigenschaften gespeichert, die verwendeten Indizes darin wieder als Eigenschaften aufgeführt. Volltextindexes erscheinen separat und an ihren Namen wird "(Keyword)" angehängt. Schließlich erscheint jede Eigenschaft Indexname jeweils wieder mit den acht elementaren Eigenschaften und, je nach Index-Verwendung seit Starten der Datenbank, mit bis zu vier Unterobjekten. Jedes dieser Unterobjekte existiert nur, wenn die dazugehörige Operation seit Starten der Datenbank an irgendeinem Punkt ausgeführt wurde.

Beispiel: Seit dem Starten der Datenbank wurden mehrere Indizes des Feldes [Employees]EmpLastName angefordert. Außerdem wurden in der Tabelle [Companies] 2 Datensätze erstellt und 16 gelöscht. Diese Tabelle hat das indizierte Feld "name". Sie wurde über dieses Feld auch durchsucht und sortiert. Als Ergebnis ergibt sich folgendes:

"indexes": {
    "Employees": {
        "EmpLastName": {
                    "diskReadBytes": {…},
                    "cacheReadBytes": {…},
                    "cacheMissBytes": {…},
                    "diskWriteBytes": {…},

                    "diskReadCount": {…},
                    "cacheReadCount": {…},
                    "cacheMissCount": {…},
                    "diskWriteCount": {…}
            }
        "EmpLastName (Keyword)": {...},
        "index3Name": {…},
        "index4Name": {…},
        …
        }
        "Companies": {
            "Name": 
            (...)
                "queryCount": {
                    "value": 41
                },
                "sortCount": {
                    "value": 3
                },
                "insertKeyCount": {
                    "value": 2
                },
                "deleteKeyCount": {
                    "value": 16
                }
    table3Name: {…}
}

Mit dem Parameter Optionen können Sie die zurückgegebene aktuelle Information anpassen. In Optionen übergeben Sie ein Objekt mit bis zu drei Eigenschaften: "withHistory", "historyLength" und "path".

(*) Wie oben beschrieben, wird der Verlauf nicht sekundenweise gespeichert, sondern nur nach relevanten Werten. Passiert ein paar Sekunden lang nichts, wird nichts gespeichert und im internen Verlauf des Array entsteht eine zeitliche Lücke. "time" kann z.B. -2, -4, -5, -10, -15, -30 mit den Werten 200, 300, 250, 400, 500,150 enthalten. Hat die Eigenschaft "historyLength" den Wert 600 (10 Minuten), enthält das zurückgegebene Array 0, -1, -2, -3 … -599 für Zeit, aber nur die Werte von -2, -4, -5, -10, -15, -30 werden gefüllt. Alle anderen Werte erhalten den Wert 0 (Null). Wie bereits beschrieben, ist die Begrenzung des internen Array die Größe (200) und nicht die Zeit. Folglich kann bei geringer Aktivität einer bestimmten Eigenschaft die älteste Zeit länger zurückliegen, z.B. -3600 für eine ganze Stunde. Das Array kann auch weniger als 200 Werte enthalten, wenn die Datenbank gerade gestartet wurde. Liegt dann die interne Zeitspanne der Chronik unter der angeforderten ODER erscheinen alle relevanten Werte bereits im zurückgegebenen Array, lautet der zurückgegebene Wert -1. 

Beispiel: Die Datenbank wurde vor 20 Sekunden gestartet, die Chronik der Anfrage ist 60 Sekunden. Die zurückgegebenen Werte zwischen 0 und -20 werden mit Werten oder Nullen gefüllt, die anderen werden auf -1 gesetzt. Wird ein Wert "-1" zurückgegeben, bedeutet dies entweder, dass die Anfragezeit zu alt ist oder der Wert nicht mehr in der Chronik liegt, z.B. weil der 200. Eintrag erreicht ist bzw. ältere Werte entfernt wurden.

Hinweis: Das Filtern über "historyLength" verlangsamt deutlich die Abarbeitung des Befehls. Zur statistischen Auswertung belasteter Server ist es sinnvoller, das gesamte Objekt ohne Angabe von "historyLength" abzufragen und das Ergebnis offline auszuwerten.

Get database measures gibt ein gültiges Objekt mit relevanten Werten nur in folgendem Kontext zurück:

• bei 4D im lokalen Modus (bei Aufruf über eine Komponente wird Information über die Host Datenbank zurückgegeben)
• auf dem Server im Client/Server-Modus

Bei Aufruf über ein remote 4D bleibt das Objekt leer.
Benötigen Sie in remote 4D Information über die Datenbank auf dem Server, legen Sie einfach eine Methode an und aktivieren dafür die Option "auf Server ausführen".
Dieses Prinzip funktioniert auch für eine Komponente: Im lokalen Kontext von 4D gibt sie Information über die Host Datenbank zurück; im remote Kontext von 4D gibt sie Information über die Server Datenbank zurück.

Im zurückgegebenen Objekt die Chronik anzeigen:

Nur die globale Anzahl der im Cache gelesenen Bytes anfordern ("cacheReadBytes"):

Das zurückgegebene Objekt könnte folgendermaßen aussehen:

{
    "DB": {
        "cacheReadBytes": {
            "value": 9516637
        }
    }
}

Die Meßwerte für im Cache gelesene Bytes der letzten zwei Minuten anfordern: