Hinweis:

Benutzerdefinierte Metriken aus Oracle Autonomous Database mit Oracle Cloud Infrastructure Monitoring Service veröffentlichen

Einführung

Oracle Autonomous Database revolutioniert die Verwaltung von Daten mit der Einführung der weltweit ersten selbststeuernden Datenbank. Oracle Autonomous Database unterstützt wichtige Geschäftsanwendungen von Unternehmen auf der ganzen Welt als primäre Datenquelle.

Oracle Autonomous Database stellt dank der tiefgehenden Integration mit dem Oracle Cloud Infrastructure-(OCI-)Monitoring-Service stets viele wichtige datenbankbezogene Servicemetriken bereit. Davon ausgehend wollen viele unserer innovativen Kunden ihre Beobachtbarkeit weiter verbessern. Diese Kunden möchten ihre eigenen Metriken zu den in Oracle Autonomous Database gespeicherten Anwendungsdaten erfassen, veröffentlichen und analysieren. Wir nennen diese benutzerdefinierten Metriken. Dabei handelt es sich um die Metriken, die Anwendungen über eine einfache REST-API, die vom OCI-SDK bereitgestellt wird, erfassen und an den OCI Monitoring-Service senden können.

In diesem Tutorial wird gezeigt, wie einfach Sie benutzerdefinierte Metriken aus Oracle Autonomous Database mit nur wenigen PL/SQL-Skripten und nur wenigen Klicks in der Oracle Cloud-Konsole veröffentlichen können.

In diesem Tutorial wird ein Datenbankschema für E-Commerce-Einkaufsaufträge als Beispiel verwendet, um zu zeigen, wie Sie Datenmetriken berechnen und erfassen können. Sie sehen, wie Sie regelmäßig eine Metrik berechnen können, die für jeden Auftragsstatus (erfüllt, akzeptiert, abgelehnt usw.) für jeden Auftrag steht, den die E-Commerce-Anwendung erhält. Anschließend veröffentlichen Sie diese benutzerdefinierten Metriken im Oracle Cloud Monitoring Service.

Voraussetzungen

  1. Zugriff auf eine kostenlose Oracle Cloud-Tier oder einen kostenpflichtigen Account.

  2. Beliebiger Typ von Oracle Autonomous Database-Instanz, freigegeben oder dediziert.

    Hinweis: In diesem Tutorial verwenden Sie eine Oracle Autonomous Database für eine Oracle Autonomous Transaction Processing-Instanz mit nur 1 OCPU und 1 TB Speicher auf einer gemeinsamen Infrastruktur. Sie können dies mit einem kostenlosen Oracle Cloud-Tier-Account erstellen.

  3. Grundlegende PL/SQL-Kenntnisse.
  4. Machen Sie sich mit der Oracle Cloud-Konsole vertraut.
  5. Sie können beliebige Oracle Database-Clients wie SQL Developer oder SQL*Plus verwenden. Wenn Sie mit Oracle Autonomous Transaction Processing neu sind, finden Sie weitere Informationen unter Verbindungen zu Autonomous Database herstellen. Informationen zu Oracle Autonomous Transaction Processing finden Sie unter SQL Developer Web, das über die Oracle Cloud-Konsolenseite für Oracle Autonomous Transaction Processing verfügbar ist. Bei Verwendung von SQL Developer Web ist kein Oracle Wallet erforderlich.
  6. ADMIN-Benutzerzugriff auf Ihre Oracle Autonomous Transaction Processing-Instanz.
  7. Grundlegende Kenntnisse mit Oracle Cloud-Konzepten wie OCI-Überwachungsservice, PostMetricData-API zur Veröffentlichung benutzerdefinierter Metriken und dynamischer Gruppen und Ressourcengrundsätze.

Lösung auf einen Blick

Wir nutzen ein einfaches PL/SQL-Skript in unserer Oracle Autonomous Database-Instanz, für das die regelmäßige Ausführung zur Berechnung, Erfassung und Veröffentlichung der benutzerdefinierten Metriken im OCI-Überwachungsservice geplant ist.

Darüber hinaus kann die Oracle Autonomous Database-Instanz über einen privaten oder öffentlichen Endpunkt verfügen. Die Kommunikation zwischen Oracle Autonomous Database und dem OCI Monitoring-Service findet im Oracle Cloud-Netzwerk statt, das extrem schnell und hochverfügbar ist. Sie müssen kein Servicegateway einrichten.

In diesem Tutorial finden Sie alles, was Sie wissen müssen, bis Sie die benutzerdefinierten Metriken von Oracle Autonomous Database zu OCI Monitoring Service erhalten müssen.

Überblick

  1. Erstellen Sie eine dynamische Gruppe für Ihre Oracle Autonomous Transaction Processing-Instanz, und autorisieren Sie sie, Metriken über eine Policy an den Oracle Cloud Infrastructure-(OCI-)Überwachungsservice zu posten.
  2. Erstellen Sie einen neuen Datenbankbenutzer oder ein neues Schema mit den erforderlichen Berechtigungen in Ihrer Oracle Autonomous Transaction Processing-Instanz, oder aktualisieren Sie einen vorhandenen Datenbankbenutzer oder -schema mit den erforderlichen Berechtigungen.
  3. Erstellen Sie eine Tabelle mit dem Namen SHOPPING_ORDER, um Daten für unsere Beispiel-E-Commerce-Anwendung zu speichern (Sie berechnen benutzerdefinierte Metriken für die in dieser Tabelle gespeicherten Kundenaufträge).
  4. Definieren Sie das PL/SQL-Skript, um zufällige Daten für Kundenaufträge in der Tabelle SHOPPING_ORDER aufzufüllen.
  5. Definieren Sie das PL/SQL-Skript, um benutzerdefinierte Metriken im OCI Monitoring-Service zu berechnen, zu sammeln und zu puffern.
  6. Skripte aus Schritt 4 und 5 planen und ausführen
  7. Sehen Sie sich die veröffentlichten benutzerdefinierten Metriken in der Oracle Cloud-Konsole an.

In einem Production-Anwendungsfall haben Sie eine eigene Anwendung, um die realen Daten und Updates aufzufüllen. Daher sind die Schritte 3 und 4 in diesem Fall nicht erforderlich.

Schritte

  1. Erstellen Sie eine dynamische Gruppe für Ihre Oracle Autonomous Transaction Processing-Instanz, und autorisieren Sie sie, Metriken über die Policy an den Oracle Cloud Infrastructure-(OCI-)Überwachungsservice zu posten.

    1. Erstellen Sie eine dynamische Gruppe namens adb_dg für Ihre Oracle Autonomous Transaction Processing-Instanz (oder -Instanzen) mit der Regel:

      ALL {resource.type = 'autonomousdatabase', resource.compartment.id = '<compartment OCID for your ADB instance>'}

      Alternativ können Sie eine einzelne Oracle Autonomous Transaction Processing-Instanz anstelle aller Instanzen im Compartment auswählen:

      ALL {resource.type = 'autonomousdatabase', resource.id = '<OCID for your ATP instance>'}

      Dynamische Gruppe für Oracle Autonomous Database

    2. Erstellen Sie eine Oracle Cloud Infrastructure Identity and Access Management-(IAM-)Policy, um die dynamische Gruppe adb_dg zu autorisieren, Metriken mit einer Policy mit dem Namen adb_dg_policy und den Policy-Regeln Allow dynamic-group adb_dg to read metrics in compartment <Your Oracle Autonomous Transaction Processing compartment OCID> an den OCI Monitoring-Service zu posten.

      Jetzt ist der Oracle Autonomous Transaction Processing-Service (gemäß der Definition der dynamischen Gruppe adb_dg) autorisiert, Metriken im selben Compartment zu posten.

      Sie haben keine Oracle Autonomous Transaction Processing-Datenbankbenutzer, die berechtigt sind, Metriken im OCI Monitoring-Service zu veröffentlichen. Auf Oracle Autonomous Transaction Processing ausgeführte PL/SQL kann weiterhin keine Metriken an den OCI-Überwachungsservice posten. Führen Sie diesen Schritt in Schritt 3c aus.

  2. Erstellen Sie einen neuen Datenbankbenutzer oder ein neues Schema mit den erforderlichen Berechtigungen in Ihrer Oracle Autonomous Transaction Processing-Instanz, oder aktualisieren Sie einen vorhandenen Datenbankbenutzer oder ein vorhandenes Schema mit den erforderlichen Berechtigungen.

    1. Erstellen Sie einen Datenbankbenutzer oder ein Datenbankschema mit dem Namen ECOMMERCE_USER in Ihrer Oracle Autonomous Transaction Processing-Instanz. Sie können dies als ADMIN-Benutzer für jede Oracle Autonomous Transaction Processing-Instanz erstellen. Sie können diesen Schritt überspringen, wenn Sie einen vorhandenen Benutzer verwenden möchten.

      CREATE USER ECOMMERCE_USER IDENTIFIED BY "Password of your choice for this User";

      Hinweis: Nun wird der Benutzer (oder das Schema) als ECOMMERCE_USER bezeichnet. Die restlichen Schritte bleiben unverändert, unabhängig davon, ob Sie einen vorhandenen Benutzer oder einen neu erstellten Benutzer verwenden.

    2. Erteilen Sie der ECOMMERCE_USER die erforderlichen Oracle Database-Berechtigungen.

      GRANT  CREATE TABLE, ALTER ANY INDEX, CREATE PROCEDURE, CREATE JOB, 
       SELECT ANY TABLE, EXECUTE ANY PROCEDURE, 
       UPDATE ANY TABLE, CREATE SESSION,
       UNLIMITED TABLESPACE, CONNECT, RESOURCE TO ECOMMERCE_USER;
GRANT  SELECT ON "SYS"."V_$PDBS" TO ECOMMERCE_USER;
GRANT  EXECUTE ON "C##CLOUD$SERVICE"."DBMS_CLOUD" to ECOMMERCE_USER;
GRANT  SELECT ON SYS.DBA_JOBS_RUNNING TO ECOMMERCE_USER;

    3. Aktivieren Sie Oracle Database-Zugangsdaten für den Oracle Cloud-Ressourcen-Principal, und erteilen Sie dem DB-Benutzer ECOMMERCE_USER Zugriff. Dadurch wird die in Schritt 1 erstellte dynamische Gruppe adb_dg mit dem Datenbankbenutzer ECOMMERCE_USER verbunden, sodass der Benutzer Metriken an den OCI Monitoring-Service posten kann. Weitere Informationen finden Sie unter Ressourcen-Principal für den Zugriff auf Oracle Cloud Infrastructure-Ressourcen verwenden.

      EXEC DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL(username => 'ECOMMERCE_USER');

    4. (Optional) Prüfen Sie die Vorgänge, die Sie im vorherigen Schritt abgeschlossen haben.

      Hinweis: Nachdem die Oracle Database-Zugangsdaten für den Oracle Cloud-Ressourcen-Principal aktiviert wurden, befindet sie sich immer im Besitz des ADMIN-Benutzers für Oracle Autonomous Database. Sie können Folgendes prüfen:

      SELECT OWNER, CREDENTIAL_NAME FROM DBA_CREDENTIALS WHERE CREDENTIAL_NAME = 'OCI$RESOURCE_PRINCIPAL'  AND OWNER =  'ADMIN';

-- To check if any other user, here ECOMMERCE_USER has access DB credential(hence to OCI Resource Principal), you have to check *DBA_TAB_PRIVS* view, as follows.
SELECT * from DBA_TAB_PRIVS WHERE DBA_TAB_PRIVS.GRANTEE='ECOMMERCE_USER';

  3. Erstellen Sie eine Beispieldatentabelle mit dem Namen SHOPPING_ORDER, um die Berechnung von Metriken in einer Datenbanktabelle anzuzeigen.

    Das Tabellenschema ist selbsterklärend. Beachten Sie jedoch die Spalte STATUS:

     DROP TABLE SHOPPING_ORDER;
 CREATE TABLE SHOPPING_ORDER (
     ID                NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY
     PRIMARY KEY,
     CREATED_DATE      TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
     DETAILS           VARCHAR2(1000) DEFAULT NULL,
     LAST_UPDATED_DATE TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
     STATUS            VARCHAR2(30 CHAR),
     TOTAL_CHARGES     FLOAT DEFAULT 0.0,
     CUSTOMER_ID       NUMBER(19)
 )
     PARTITION BY LIST ( STATUS ) 
     (   PARTITION ACCEPTED VALUES ( 'ACCEPTED' ),
         PARTITION PAYMENT_REJECTED VALUES ( 'PAYMENT_REJECTED' ),
         PARTITION SHIPPED VALUES ( 'SHIPPED' ),
         PARTITION ABORTED VALUES ( 'ABORTED' ),
         PARTITION OUT_FOR_DELIVERY VALUES ( 'OUT_FOR_DELIVERY' ),
         PARTITION ORDER_DROPPED_NO_INVENTORY VALUES ( 'ORDER_DROPPED_NO_INVENTORY' ),
         PARTITION PROCESSED VALUES ( 'PROCESSED' ),
         PARTITION NOT_FULLFILLED VALUES ( 'NOT_FULFILLED' )
     );
 /

 -- we move rows from one partition to another, hence we enable row movement for this partioned table
 ALTER TABLE SHOPPING_ORDER ENABLE ROW MOVEMENT;

    Jeder Einkaufsauftrag kann einen von acht Statuswerten während seiner Lebensdauer haben: [ACCEPTED, PAYMENT_REJECTED, SHIPPED, ABORTED, OUT_FOR_DELIVERY, ORDER_DROPPED_NO_INVENTORY, PROCESSED, NOT_FULFILLED].

  4. Lesen Sie das folgende PL/SQL-Skript. Es füllt Daten in der Tabelle SHOPPING_ORDER auf. Führen Sie sie auf dem Oracle Database-Client Ihrer Wahl aus.

    Das Skript fügt zuerst die TOTAL_ROWS_IN_SHOPPING_ORDER-Zeilenanzahl mit zufällig generierten Bestelldaten zur Tabelle SHOPPING_ORDER hinzu. Anschließend werden die Daten aktualisiert, und die STATUS-Werte jeder SHOPPING_ORDER-Zeile werden nach dem Zufallsprinzip geändert.

    CREATE OR REPLACE PROCEDURE POPULATE_DATA_FEED IS
    ARR_STATUS_RANDOM_INDEX      INTEGER;
    CUSTOMER_ID_RANDOM           INTEGER;
    TYPE STATUS_ARRAY IS VARRAY(8) OF VARCHAR2(30);
    ARRAY STATUS_ARRAY := STATUS_ARRAY('ACCEPTED', 'PAYMENT_REJECTED',
                                    'SHIPPED', 'ABORTED', 'OUT_FOR_DELIVERY',
                                    'ORDER_DROPPED_NO_INVENTORY', 
                                    'PROCESSED', 'NOT_FULFILLED');
    TOTAL_ROWS_IN_SHOPPING_ORDER INTEGER := 15000;
    TYPE ROWID_NT IS TABLE OF ROWID;
    ROWIDS                       ROWID_NT;
BEGIN     
    -- starting from scratch just be idempotent and have predictable execution time for this stored procedure
    -- deleting existing rows is optional 
    DELETE SHOPPING_ORDER;

    -- insert data
    FOR COUNTER IN 1..TOTAL_ROWS_IN_SHOPPING_ORDER LOOP
        ARR_STATUS_RANDOM_INDEX := TRUNC(DBMS_RANDOM.VALUE(LOW => 1, HIGH => 9));
        CUSTOMER_ID_RANDOM := TRUNC(DBMS_RANDOM.VALUE(LOW => 1, HIGH => 8000));
        INSERT INTO SHOPPING_ORDER (STATUS,CUSTOMER_ID) VALUES (ARRAY(ARR_STATUS_RANDOM_INDEX),CUSTOMER_ID_RANDOM);
        COMMIT;          
    END LOOP;

    DBMS_OUTPUT.PUT_LINE('DONE WITH INITIAL DATA LOAD');

    -- keep on updating the same data
    FOR COUNTER IN 1..8000 LOOP        

            --Get the rowids
        SELECT R BULK COLLECT INTO ROWIDS FROM (SELECT ROWID R FROM SHOPPING_ORDER SAMPLE ( 5 ) ORDER BY DBMS_RANDOM.VALUE) RNDM
        WHERE ROWNUM < TOTAL_ROWS_IN_SHOPPING_ORDER + 1;

            --update the table
        ARR_STATUS_RANDOM_INDEX := TRUNC(DBMS_RANDOM.VALUE(LOW => 1, HIGH => 9));

        FOR I IN 1..ROWIDS.COUNT LOOP
            UPDATE SHOPPING_ORDER SET STATUS = ARRAY(ARR_STATUS_RANDOM_INDEX) WHERE ROWID = ROWIDS(I);
            COMMIT;
        END LOOP;    
        --sleep in-between if you want to run script for longer duration
        --DBMS_SESSION.SLEEP(ROUND(dbms_random.value(low => 1, high => 2)));          
    END LOOP;

    DBMS_OUTPUT.PUT_LINE('DONE WITH POPULATE_DATA_FEED');
    EXECUTE IMMEDIATE 'ANALYZE TABLE SHOPPING_ORDER COMPUTE STATISTICS';
END;
/

  5. Lassen Sie uns tief in den eigentlichen Code dieses Tutorials eintauchen: Das Skript, das die benutzerdefinierten Metriken berechnet und im OCI Monitoring-Service veröffentlicht. Führen Sie sie auf dem Oracle Datbase-Client Ihrer Wahl aus. Das Skript ist idempotent, um sicherzustellen, dass Sie mit ihm in mehreren Ausführungen spielen können. Analysieren Sie nun das Skript Piecemeal.

    1. Erstellen Sie die Tabelle SHOPPING_ORDER_METRICS_TABLE, und verwenden Sie sie, um berechnete Metriken zu sammeln und zu puffern.

      Stellen Sie sicher, dass die Datentabellen für Abfragen optimiert sind, auf denen die Metrikberechnung ausgeführt wird. Diese Abfragen sollen Ihre Datenbank nicht zu sehr belasten und Ihre Produktionsumgebungen beeinträchtigen.

      DECLARE
    COUNT_VAR NUMBER := 0;
BEGIN
    SELECT COUNT(*) INTO COUNT_VAR FROM ALL_TABLES WHERE TABLE_NAME = 'SHOPPING_ORDER_METRICS_TABLE';

    IF COUNT_VAR > 0 THEN
        DBMS_OUTPUT.PUT_LINE('TABLE EXISTS ALREADY!');
    ELSE
        -- table doesn't exist
        EXECUTE IMMEDIATE 'CREATE TABLE SHOPPING_ORDER_METRICS_TABLE(
                            ID                 NUMBER         GENERATED BY DEFAULT ON NULL AS IDENTITY PRIMARY KEY,
                            CREATED_DATE       TIMESTAMP(6)   DEFAULT CURRENT_TIMESTAMP,
                            STATUS             VARCHAR2(30 CHAR),
                            COUNT              NUMBER)';
    END IF;

END;
/

    2. Erstellen Sie eine Stored Procedure, die die Metrik berechnet: Anzahl für die Anzahl der Aufträge nach Statuswerten zum Zeitpunkt der Instanz dieser Metriksammlung.

      Die Stored Procedure puffert dann die berechneten Metriken in der Puffertabelle SHOPPING_ORDER_METRICS_TABLE, die Sie im vorherigen Schritt erstellt haben. Buffer, um sicherzustellen, dass Sie versuchen können, die Metriken in Zukunft erneut zu posten, wenn beim Veröffentlichen in OCI Monitoring Service eine vorübergehende Unterbrechung auftritt.

      CREATE OR REPLACE PROCEDURE COMPUTE_AND_BUFFER_METRICS IS
BEGIN    
    -- compute simple metric for getting count order by order-status 
    -- and store in buffer table SHOPPING_ORDER_METRICS_TABLE
    INSERT INTO SHOPPING_ORDER_METRICS_TABLE (STATUS, COUNT, CREATED_DATE) 
    SELECT STATUS, COUNT(*), SYSTIMESTAMP AT TIME ZONE 'UTC' FROM SHOPPING_ORDER SO GROUP BY SO.STATUS;

    -- we buffer at most 1000 metric points, please configure as per your needs
    DELETE FROM SHOPPING_ORDER_METRICS_TABLE SOMT WHERE SOMT.ID NOT IN
        (SELECT ID FROM SHOPPING_ORDER_METRICS_TABLE ORDER BY CREATED_DATE FETCH FIRST 1000 ROWS ONLY);

    COMMIT;    
    DBMS_OUTPUT.PUT_LINE('compute and buffering done @ ' || TO_CHAR(SYSTIMESTAMP));
END;
/

      Um die Größe der Puffertabelle zu begrenzen, kürzen Sie sie, wenn ihre Größe 1.000 Zeilen überschreitet.

    3. Verwenden Sie die PL/SQL-Funktion PREPARE_JSON_OBJECT_FROM_METRIC_ROWS, die gepufferte Metriken aus SHOPPING_ORDER_METRICS_TABLE in JSON-Objekte konvertiert, die von der PostMetricsData-API in ihrer Anforderung erwartet werden.

      Hinweis:

      • Diese Funktion konvertiert die BATCH_SIZE_FOR_EACH_POST-Anzahl der letzten Metrikdatenpunkte aus SHOPPING_ORDER_METRICS_TABLE in OCI_METADATA_JSON_OBJ JSON_OBJECT_T.
      • OCI_METADATA_JSON_OBJ ist eine Variable des vordefinierten PL/SQL-Datentyps JSON_OBJECT_T. Wir haben OCI_METADATA_JSON_OBJ mit derselben JSON-Struktur wie in PostMetricDataDetails beschrieben erstellt, dem Anforderungstext für die PostMetricsData-API.
       CREATE OR REPLACE FUNCTION GET_METRIC_DATA_DETAILS_JSON_OBJ (
     IN_ORDER_STATUS         IN VARCHAR2,
     IN_METRIC_CMPT_ID       IN VARCHAR2,
     IN_ADB_NAME             IN VARCHAR2,
     IN_METRIC_VALUE         IN NUMBER,
     IN_TS_METRIC_COLLECTION IN VARCHAR2
 ) RETURN JSON_OBJECT_T IS
     METRIC_DATA_DETAILS JSON_OBJECT_T;
     MDD_METADATA        JSON_OBJECT_T;
     MDD_DIMENSIONS      JSON_OBJECT_T;
     ARR_MDD_DATAPOINT   JSON_ARRAY_T;
     MDD_DATAPOINT       JSON_OBJECT_T;
 BEGIN
     MDD_METADATA := JSON_OBJECT_T();
     MDD_METADATA.PUT('unit', 'row_count'); -- metric unit is arbitrary, as per choice of developer

     MDD_DIMENSIONS := JSON_OBJECT_T();
     MDD_DIMENSIONS.PUT('dbname', IN_ADB_NAME);
     MDD_DIMENSIONS.PUT('schema_name', SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA'));
     MDD_DIMENSIONS.PUT('table_name', 'SHOPPING_ORDER');
     MDD_DIMENSIONS.PUT('status_enum', IN_ORDER_STATUS);
     MDD_DATAPOINT := JSON_OBJECT_T();
     MDD_DATAPOINT.PUT('timestamp', IN_TS_METRIC_COLLECTION); --timestamp value RFC3339 compliant
     MDD_DATAPOINT.PUT('value', IN_METRIC_VALUE);
     MDD_DATAPOINT.PUT('count', 1);
     ARR_MDD_DATAPOINT := JSON_ARRAY_T();
     ARR_MDD_DATAPOINT.APPEND(MDD_DATAPOINT);
     METRIC_DATA_DETAILS := JSON_OBJECT_T();
     METRIC_DATA_DETAILS.PUT('datapoints', ARR_MDD_DATAPOINT);
     METRIC_DATA_DETAILS.PUT('metadata', MDD_METADATA);
     METRIC_DATA_DETAILS.PUT('dimensions', MDD_DIMENSIONS);

     -- namespace, resourceGroup and name for the custom metric are arbitrary values, as per choice of developer
     METRIC_DATA_DETAILS.PUT('namespace', 'custom_metrics_from_adb');
     METRIC_DATA_DETAILS.PUT('resourceGroup', 'ecommerece_adb');
     METRIC_DATA_DETAILS.PUT('name', 'customer_orders_submitted');

     -- since compartment OCID is fetched using ADB metadata, our custom metrics will land up in same compartment as our ADB
     METRIC_DATA_DETAILS.PUT('compartmentId', IN_METRIC_CMPT_ID);
     RETURN METRIC_DATA_DETAILS;
 END;
 /

 CREATE OR REPLACE FUNCTION PREPARE_JSON_OBJECT_FROM_METRIC_ROWS (
     OCI_METADATA_JSON_OBJ JSON_OBJECT_T, BATCH_SIZE_FOR_EACH_POST NUMBER
 ) RETURN JSON_OBJECT_T IS
     OCI_POST_METRICS_BODY_JSON_OBJ JSON_OBJECT_T;
     ARR_METRIC_DATA                JSON_ARRAY_T;
     METRIC_DATA_DETAILS            JSON_OBJECT_T;
 BEGIN
     -- prepare JSON body for postmetrics api..
     -- for details please refer https://docs.oracle.com/en-us/iaas/api/#/en/monitoring/20180401/datatypes/PostMetricDataDetails
     ARR_METRIC_DATA := JSON_ARRAY_T();

     -- PostMetrics api has soft limit of 50 unique metric stream per call, hence we cap it at 50. 
     -- For Production usecase where every metric data point is important, we can use chunking
     FOR METRIC_ROW IN (SELECT * FROM SHOPPING_ORDER_METRICS_TABLE 
                         ORDER BY CREATED_DATE DESC FETCH FIRST BATCH_SIZE_FOR_EACH_POST ROWS ONLY) LOOP

         --DBMS_OUTPUT.PUT_LINE('inside for loop ' || METRIC_ROW.STATUS );

         METRIC_DATA_DETAILS := GET_METRIC_DATA_DETAILS_JSON_OBJ(
                             METRIC_ROW.STATUS,
                             OCI_METADATA_JSON_OBJ.GET_STRING('COMPARTMENT_OCID'), 
                             OCI_METADATA_JSON_OBJ.GET_STRING('DATABASE_NAME'), 
                             METRIC_ROW.COUNT, 
                             TO_CHAR(METRIC_ROW.CREATED_DATE, 'yyyy-mm-dd"T"hh24:mi:ss.ff3"Z"'));
         --DBMS_OUTPUT.PUT_LINE('METRIC_DATA_DETAILS '|| METRIC_DATA_DETAILS.to_clob);
         ARR_METRIC_DATA.APPEND(METRIC_DATA_DETAILS);

     END LOOP;
     DBMS_OUTPUT.PUT_LINE('done with for loop ');
     OCI_POST_METRICS_BODY_JSON_OBJ := JSON_OBJECT_T();
     OCI_POST_METRICS_BODY_JSON_OBJ.PUT('metricData', ARR_METRIC_DATA);

     RETURN OCI_POST_METRICS_BODY_JSON_OBJ;
 END;
 /

    4. Verwenden Sie den PL/SQL-Code, um diese konvertierten Metriken mit der PostMetricsData-API im OCI Monitoring-Service zu veröffentlichen.

      Hinweis: Dazu verwenden Sie die PL/SQL-Funktion POST_METRICS_DATA_TO_OCI und die Stored Procedure PUBLISH_BUFFERED_METRICS_TO_OCI.

      
 CREATE OR REPLACE FUNCTION POST_METRICS_DATA_TO_OCI(OCI_POST_METRICS_BODY_JSON_OBJ JSON_OBJECT_T, ADB_REGION VARCHAR2) 
 RETURN NUMBER 
 IS
     RETRY_COUNT                    INTEGER := 0;
     MAX_RETRIES                    INTEGER := 3;
     RESP                           DBMS_CLOUD_TYPES.RESP;
     EXCEPTION_POSTING_METRICS      EXCEPTION;
     SLEEP_IN_SECONDS               INTEGER := 5;
 BEGIN
     FOR RETRY_COUNT in 1..MAX_RETRIES  LOOP
             -- invoking REST endpoint for OCI Monitoring API
             -- for details please refer https://docs.oracle.com/en-us/iaas/api/#/en/monitoring/20180401/MetricData/PostMetricData
         RESP := DBMS_CLOUD.SEND_REQUEST(CREDENTIAL_NAME => 'OCI$RESOURCE_PRINCIPAL', 
                                         URI => 'https://telemetry-ingestion.'|| ADB_REGION|| '.oraclecloud.com/20180401/metrics', 
                                         METHOD =>DBMS_CLOUD.METHOD_POST, 
                                         BODY => UTL_RAW.CAST_TO_RAW(OCI_POST_METRICS_BODY_JSON_OBJ.TO_STRING));

         IF DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(RESP) = 200 THEN    -- when it is 200 from OCI Metrics API, all good
             DBMS_OUTPUT.PUT_LINE('POSTED METRICS SUCCESSFULLY TO OCI MONIOTRING');
             RETURN 200;
         ELSIF DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(RESP) = 429 THEN -- 429 is caused by throttling
             IF RETRY_COUNT < MAX_RETRIES THEN
                 -- increase sleep time for each retry, doing exponential backoff
                 DBMS_SESSION.SLEEP(POWER(SLEEP_IN_SECONDS, RETRY_COUNT+1));
                 DBMS_OUTPUT.PUT_LINE('RETRYING THE POSTMETRICS API CALL');
             ELSE
                 DBMS_OUTPUT.PUT_LINE('ABANDONING POSTMETRICS CALLS, AFTER 3 RETRIES, CAUSED BY THROTTLING, WILL BERETRIED IN NEXT SCHEDULED RUN');
                 RETURN 429;
             END IF;
         ELSE -- for any other http status code....1. log error, 2. raise exception and then quit posting metrics, as it is most probably a persistent error 
                 DBMS_OUTPUT.PUT_LINE('IRRECOVERABLE ERROR HAPPENED WHEN POSTING METRICS TO OCI MONITORING, PLEASE SEE CONSOLE FOR ERRORS');
                 -- Response Body in TEXT format
                 DBMS_OUTPUT.put_line('Body: ' || '------------' || CHR(10) || DBMS_CLOUD.get_response_text(resp) || CHR(10));
                 -- Response Headers in JSON format
                 DBMS_OUTPUT.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
                 -- Response Status Code
                 DBMS_OUTPUT.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_status_code(resp));
                 RETURN 500;
         END IF;

     END LOOP;
 END;
 /

 CREATE OR REPLACE PROCEDURE PUBLISH_BUFFERED_METRICS_TO_OCI IS
     OCI_METADATA_JSON_RESULT       VARCHAR2(1000);
     OCI_METADATA_JSON_OBJ          JSON_OBJECT_T;
     ADB_REGION                     VARCHAR2(25);
     OCI_POST_METRICS_BODY_JSON_OBJ JSON_OBJECT_T;
     TYPE ID_ARRAY IS VARRAY(50) OF NUMBER;
     ARRAY                          ID_ARRAY;
     TOTAL_METRICS_STREAM_CNT       NUMBER;
     HTTP_CODE                      NUMBER;
     BATCH_SIZE_FOR_EACH_POST       NUMBER:=8; -- not more than 50! as per PostMetricsData API docs
 BEGIN
     -- get the meta-data for this ADB Instance like its OCI compartmentId, region and DBName etc; as JSON in oci_metadata_json_result
     SELECT CLOUD_IDENTITY INTO OCI_METADATA_JSON_RESULT FROM V$PDBS; 
     -- dbms_output.put_line(oci_metadata_json_result);

     -- convert the JSON string into PLSQL JSON native JSON datatype json_object_t variable named oci_metadata_json_result
     OCI_METADATA_JSON_OBJ := JSON_OBJECT_T.PARSE(OCI_METADATA_JSON_RESULT);


     WHILE(TRUE) LOOP
         SELECT COUNT(*) INTO TOTAL_METRICS_STREAM_CNT FROM SHOPPING_ORDER_METRICS_TABLE;
         IF(TOTAL_METRICS_STREAM_CNT < BATCH_SIZE_FOR_EACH_POST) THEN
             DBMS_OUTPUT.PUT_LINE('Only ' || TOTAL_METRICS_STREAM_CNT || ' metrics datapoints buffered(less than batch size' || BATCH_SIZE_FOR_EACH_POST || '), hence waiting for buffer to fill up');
             EXIT;
         END IF;   

         OCI_POST_METRICS_BODY_JSON_OBJ := PREPARE_JSON_OBJECT_FROM_METRIC_ROWS(OCI_METADATA_JSON_OBJ, BATCH_SIZE_FOR_EACH_POST);
         ADB_REGION := OCI_METADATA_JSON_OBJ.GET_STRING('REGION');

         HTTP_CODE := POST_METRICS_DATA_TO_OCI(OCI_POST_METRICS_BODY_JSON_OBJ, ADB_REGION);

         IF(HTTP_CODE = 200) THEN
             DBMS_OUTPUT.PUT_LINE('Deleting the published metrics');
             DELETE FROM SHOPPING_ORDER_METRICS_TABLE WHERE ID IN 
                                 (SELECT ID FROM SHOPPING_ORDER_METRICS_TABLE 
                                 ORDER BY CREATED_DATE DESC FETCH FIRST 50 ROWS ONLY);
         END IF;    

         COMMIT;    

         -- PostMetricData API has TPS rate limit of 50, just for safety  
         -- Hence sleep for atleast seconds => (1/50) to avoid throttling
         -- DBMS_SESSION.SLEEP(seconds => (1/50));                                  
     END LOOP;
 END;
 /

      Die Funktion POST_METRICS_DATA_TO_OCI ruft die PostMetricsData-API auf. Wie bei jeder Oracle Cloud-API benötigen Sie die richtige OCI IAM-Autorisierung, um sie aufzurufen. Sie übergeben dasselbe wie folgt mit dem benannten Parameter credential_name => 'OCI$RESOURCE_PRINCIPAL'.

      Die Datenbankzugangsdaten OCI$RESOURCE_PRINCIPAL sind mit der dynamischen Gruppe adb_dg verknüpft, die Sie in Schritt 2 erstellt haben, und der Benutzer ECOMMERCE_USER aus Schritt 3 hat bereits Zugriff.

      Hence by chain of trust, this PL/SQL script executed by ECOMMERCE_USER has authorization to post the custom metrics to the OCI Monitoring service.

      RESP := DBMS_CLOUD.SEND_REQUEST(CREDENTIAL_NAME => 'OCI$RESOURCE_PRINCIPAL', 
                                        URI => 'https://telemetry-ingestion.'|| ADB_REGION|| '.oraclecloud.com/20180401/metrics', 
                                        METHOD =>DBMS_CLOUD.METHOD_POST, 
                                        BODY => UTL_RAW.CAST_TO_RAW(OCI_POST_METRICS_BODY_JSON_OBJ.TO_STRING));

      dbms_cloud.send_request ist eine integrierte PL/SQL-Stored Procedure, die jeden Restendpunkt aufruft, der mit jeder Oracle Autonomous Database vorinstalliert ist. Hier wird die REST-API für den OCI Monitoring-Service aufgerufen.

      Die Stored Procedure PUBLISH_BUFFERED_METRICS_TO_OCI sendet alle gepufferten Metriken an den OCI Monitoring-Service. Dabei werden alle Funktionen und Prozeduren verwendet, die wir bisher besprochen haben. Dazu werden Batches mit der Größe BATCH_SIZE_FOR_EACH_POST der Metrikdatenpunkte für jeden PostMetricsData API-Aufruf erstellt.

  6. Skripte aus Schritt 4 und 5 planen und ausführen In den Schritten 4 und 5 haben Sie Stored Procedures und Stored Functions in der Oracle Database definiert, aber noch nicht ausgeführt.

    1. Führen Sie das Skript aus Schritt 4 aus, um die Daten in der Tabelle SHOPPING_ORDER aufzufüllen. Das Skript wird in der Oracle Autonomouse Transaction Processing-Instanz mit 1 OCPU und 1 TB Speicher etwa 15 Minuten ausgeführt.

      -- we schedule the data feed to run immediately, asynchronously and only once!
BEGIN
     DBMS_SCHEDULER.CREATE_JOB(
                             JOB_NAME => 'POPULATE_DATA_FEED_JOB', 
                             JOB_TYPE => 'STORED_PROCEDURE', 
                             JOB_ACTION => 'POPULATE_DATA_FEED',
                             ENABLED => TRUE, 
                             AUTO_DROP => TRUE, -- drop job after 1 run.
                             COMMENTS => 'ONE-TIME JOB');
 END;
 /

 -- just for our information
 SELECT STATUS,count(*) FROM SHOPPING_ORDER GROUP BY STATUS;

    2. Es bleibt nur die regelmäßige Ausführung des PL/SQL-Skripts aus Schritt 5 übrig: Berechnung und Veröffentlichung in OCI Monitoring Service.

      Der Vorgang wird wie folgt mit der integrierten PL/SQL-Stored Procedure DBMS_SCHEDULER.CREATE_JOB ausgeführt.

      Damit wird die Oracle Database SCHEDULED_JOB für 20 Minuten (1.200 Sekunden) erstellt. Es berechnet benutzerdefinierte Metriken und veröffentlicht sie jede Minute.

      Konfigurieren Sie die Produktionsumgebung gemäß Ihren Anforderungen.

      BEGIN
    DBMS_SCHEDULER.CREATE_JOB(
                            JOB_NAME => 'POST_METRICS_TO_OCI_JOB', 
                            JOB_TYPE   => 'PLSQL_BLOCK',
                            JOB_ACTION => 'BEGIN 
                                            ECOMMERCE_USER.COMPUTE_AND_BUFFER_METRICS(); 
                                            ECOMMERCE_USER.PUBLISH_BUFFERED_METRICS_TO_OCI();
                                           END;',
                            START_DATE => SYSTIMESTAMP,                        -- start the first run immediately
                            REPEAT_INTERVAL => 'FREQ=SECONDLY;INTERVAL=60',    -- run this PLSQL_BLOCK every 60th second 
                            END_DATE => SYSTIMESTAMP + INTERVAL '1200' SECOND, -- this schedule is only active
                            AUTO_DROP => TRUE,                                 -- delete the schedule after 1200 seconds, effectively after its last run
                            ENABLED => TRUE,                                   -- enable this schedule as soon as it is created
                            COMMENTS => 'JOB TO POST DB METRICS TO OCI MONITORING SERVICE, RUNS EVERY 10TH SECOND');
END;
/

  7. Sehen Sie sich die veröffentlichten benutzerdefinierten Metriken zur Oracle Cloud-Konsole an.

    1. Klicken Sie im Navigationsmenü auf Metrik-Explorer.

      Gehen Sie zum Metrik-Explorer in der Oracle Cloud-Konsole

    2. Wählen Sie im Metrik-Explorer den Namespace als custom_metrics_from_adb, resourceGroup als ecommerece_adb und den Metriknamen als customer_orders_submitted aus, den Sie für benutzerdefinierte Metriken festgelegt haben.

      Alle Metadaten und Dimensionen, die Sie für die benutzerdefinierten Metriken festlegen, sind verfügbar.

      Sie können MQL-Abfragen erstellen, um diese Metriken entsprechend Ihren Anforderungen und Anwendungsfällen zu analysieren. Als Nächstes sollten Sie Oracle Cloud-Alarme für den Metrikstream einrichten, um Ihr Betriebsteam zu warnen.

      Dadurch wird die Beobachtbarkeitsschleife für die Oracle Autonomous Database-Metriken Ihrer Wahl automatisiert.

      Erkunden Sie die von Ihnen veröffentlichten benutzerdefinierten Metriken

Schlussfolgerung

Sie haben gelernt, wie Sie benutzerdefinierte Metriken von Oracle Autonomous Database mit einfachen PL/SQL-Skripten mit dem OCI-SDK für PL/SQL an den Oracle Cloud Infrastructure-(OCI-)Monitoring-Service ausgeben. Oracle Database ist eine Datenquelle für viele Geschäftsworkflows, sodass dies eine äußerst leistungsstarke Funktionalität ist.

Benutzerdefinierte Metriken sind erstklassige Bürger des OCI Monitoring-Service, auf der Grundlage von nativen Metriken. Sie können sie mit derselben leistungsstarken Metrikabfragesprache analysieren und Alarme dafür einrichten, dass Sie benachrichtigt werden, wenn ein beliebiges Ereignis oder ein Problem auftritt.

Dadurch erhalten Sie die ultimative "Single Pane of Glass"-Ansicht für alle Metriken, unabhängig davon, ob Sie den OCI-Service oder benutzerdefinierte Metriken generieren, die von Ihren Anwendungen und Datenbanken generiert werden.

Danksagungen

Weitere Lernressourcen

Sehen Sie sich andere Übungen zu docs.oracle.com/learn an, oder greifen Sie auf weitere Inhalte für kostenloses Lernen im Oracle Learning YouTube-Kanal zu. Außerdem besuchen Sie education.oracle.com/learning-explorer, um Oracle Learning Explorer zu werden.

Produktdokumentation finden Sie im Oracle Help Center.