DBMS_TELEMETRY_INGEST

The DBMS_TELEMETRY_INGEST package provides a collection of user functions to ingest metrics into Oracle AI Database Telemetry Streaming.

This chapter contains the following topics:

DBMS_TELEMETRY_INGEST Overview

The ingest APIs that are implemented using the DBMS_TELEMETRY_INGEST package enable the users in a workspace to ingest metrics into Oracle AI Database Telemetry Streaming.

See Also:

DBMS_TELEMETRY_INGEST Security Model

The DBMS_TELEMETRY_INGEST package is an invoker’s right package that enables a Telemetry workspace ingest user to ingest metrics into Oracle AI Database Telemetry Streaming.

A Telemetry workspace user is an existing database user who has been explicitly granted access and the required privileges by the Telemetry workspace administrator using the DBMS_TELEMETRY_ADMIN.ENABLE_WORKSPACE_USER procedure with user_role set to ‘INGEST’.

A user can be an ingest, a query user, or both for only one workspace.

Summary of DBMS_TELEMETRY_INGEST Subprograms

This table lists and briefly describes the DBMS_TELEMETRY_INGEST package subprograms.

Table 1 DBMS_TELEMETRY_INGEST Package

Subprogram Description
INGEST_METRICS Function Ingests data as a metric sample into Oracle AI Database Telemetry Streaming
INGEST_METRICS Function Ingests data in bulk into Oracle AI Database Telemetry Streaming

INGEST_METRICS Function

This function enables users in a workspace to ingest data as a single metric sample into Oracle AI Database Telemetry Streaming.

The INGEST_METRICS function does a single sample ingest with metric_name, metric_tags (JSON as VARCHAR), metric_value, and metric_time (epoch secs).

Syntax

function ingest_metrics(
         metric_name        IN VARCHAR2,
         metric_tags        IN VARCHAR2,
         metric_value       IN NUMBER,
         metric_time_epoch  IN NUMBER)
return clob;

Parameters

Table 2 INGEST_METRICS Function

Parameter Description
metric_name

metric_name should be a valid VARCHAR2 with length less than or equal to 512.

metric_name should follow semantics similar to the Prometheus metrics.

See Also:

Data Formats and Naming Conventions in Oracle AI Database Telemetry Streaming Developer's Guide for more information about metric_name.
metric_tags

The metric tags should be a valid VARCHAR2 with a length less than 4000. It is stored as JSON in the database with an IS JSON check constraint and the (STRICT) qualifier added to ensure valid JSON. Thus, respective formatting should be applied to tags input.

See Also:

JSON in Oracle Database in JSON Developer's Guide for more information about using JSON in Oracle Database.
metric_value The point-in-time (PIT) value of the time series
metric_time_epoch The time in seconds since epoch

INGEST_METRICS Function

This function enables users in a workspace to ingest data in bulk into Oracle AI Database Telemetry Streaming.

This INGEST_METRICS function does a bulk ingest formatted in native JSON format (Telemetry protocol) or line protocol format and returns a JSON with information about the ingest performed.

Syntax

ingest_metrics(
         metrics        IN  CLOB,
         status         OUT NUMBER,
         metrics_format IN  VARCHAR2 default 'telemetry protocol') -- Other value 'line protocol'
return clob;

Parameters

Table 3 INGEST_METRICS Function

Parameter Description
metrics Metric data that needs to be inserted as CLOB
status status specifies if data has been ingested successfully (201- success, 400 - unsuccessful)
metrics_format Data format used for ingestion. metrics_format can be the native JSON format (Telemetry protocol) or Influx DB Line protocol format

The Telemetry protocol and Line protocol formats used in metrics_format are given in the following examples.

Telemetry Protocol Example

Format:

{ "metrics" : [
                [<metric_name>, <tags as JSON>, <value>, <time in secs since epoch>],
                [<metric_name>, <tags as JSON>, <value>, <time in secs since epoch>]
                   ..
              ]
}

Example:

{ "metrics" : [
                ["scrape_duration_seconds", {"http_scheme":"http","net_host_port":"2112"}, 0, 1704700084],
                ["scrape_samples_scraped", {"http_scheme":"http","net_host_port":"2112"}, 12, 1704700085]
                   ..
              ]
}

Line Protocol Example

Format:

<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]

Example:

trig,host=phoenix92613 sine=0 1752215852000000000
mem,host=phoenix92613 sine=0 1752215852000000000