Introduction to Oracle AI Database Telemetry Streaming

1 Introduction to Oracle AI Database Telemetry Streaming

Oracle AI Database Telemetry Streaming (hereinafter called Telemetry Streaming) is a time series database built on Oracle AI Database for metrics streaming. Telemetry Streaming is designed specifically to store, retrieve, and manage times series data. You can use Telemetry Streaming with Oracle AI Database to build your time series database applications.

These topics provide the conceptual understanding that is needed to get started with Telemetry Streaming.

1.1 Concepts

The following are some basic concepts used in Telemetry Streaming.

Metric

A metric is the name of a variable whose value you want to track over a specific period. Metric names are labels that help us uniquely identify the metric that we are tagging. CPU_USAGE is an example of a metric name. Other examples can be something like OFFICE_TEMP, STOCK_PRICE, or NETWORK_USAGE. A metric may also include additional metadata like tags. Each data point in a metric has a timestamp.

Metric Tags

Metric tags let you capture different instances of the same metric name. For example, CPU_USAGE{device_owner : "JACK"} is one time series and CPU_USAGE{device_owner : "BENJAMIN"} is another time series.

Metric Sample

A metric sample is the record of the value of a metric at a specific point in time. A metric sample tells you when the measurement was taken and what value was recorded. For example, at 2025-05-21 10:00:00, a metric sample might record that the value of office temperature is 21.5. A metric sample can be represented as a tuple of metric name and tags.

The following is an example in JSON format that shows a single measurement of CPU usage value at a specific time:

{ 
  "metric": "cpu_usage",
  "timestamp": "2025-05-21T10:00:00",
  "value": 45.3,
  "tags": {
   "host": "server-01",
   "device_owner: "Jack"
  }
}

Time Series

A time series is a collection of metric samples for a given metric, arranged in a chronological order. Each data entry in a time series is timestamped and represented in time-value pairs. Metrics derived from time series data help analyze how a variable value changes over time. These samples are collected over a period to observe trends, detect anomalies, and perform analysis. Time series data includes server metrics, application performance monitoring data, network data, sensor data, events, clicks, trades in a market, and many other types of analytical data. For example, your office room temperature metric could measure the room temperature once per minute to show the associated values in Celsius for every minute in a series, such as 25 at time T1, 26 at time T2, and 24 at time T3, and so on.

{
  "metric": "room_temperature",
  "tags": {
    "unit": "Celsius",
    "building": "XYZ",
    "room": "LivingRoom",
    "sensor_id": "sensor-001",
    "floor": "1"
  },
  "samples": [
    {
      "timestamp": "2025-07-01T10:00:00Z",
      "value": 25
    },
    {
      "timestamp": "2025-07-01T10:01:00Z",
      "value": 26
    },
    {
      "timestamp": "2025-07-01T10:02:00Z",
      "value": 26.5
    }
  ]
}

The following example shows an extract of a time series depicted in JSON format for CPU usage values recorded over an hour:

{
  "metric": "cpu_usage",
  "tags": {
   "host": "server-01",
   "device_owner: "Jack"
  },
  "samples": [
    { 
    "timestamp": "2025-05-21T10:00:00Z", 
    "value": 45.3 
    },
    { 
    "timestamp": "2025-05-21T10:01:00Z", 
    "value": 46.1 
    },
    { 
    "timestamp": "2025-05-21T10:02:00Z", 
    "value": 44.8 
    }
  ]
}

Time Series Database

A Time Series Database (TSDB) is a database that is specifically designed for storing, retrieving, and managing time series data. A TSDB is therefore more efficient than a general-purpose database in handling time series data. TSDBs have different architectural design properties that make them very different from other databases. These include timestamp data storage and compression, data lifecycle management, data summarization, ability to handle large time series-dependent scans of many records, and time series-aware queries. A TSDB is optimized for large volumes of sequential writes, making it easy to ingest high-throughput streams without bottlenecks.

Every TSDB has these components:

Ingest clients to stream time series data into TSDB
Database engine for storage and query of time series data
Query component used by visualization application that are external to TSDB for visualizing and analyzing time series data
Data lifecycle management

Ingesting and Querying Metrics

Ingesting and querying are the two core operations for handling time series data. Ingesting means collecting and storing metric data into the time series database. This involves writing metric samples into the database. These data may be derived from sensors for IoT devices, application logs, or third-party agents.

Querying means retrieving and analyzing stored metric data from the time series database for the purposes of visualization, alerting, or analysis. You can use query languages such as SQL or PromQL (Prometheus' query language) for querying data.

Epoch Time

Epoch time is a way to represent time as a single number by calculating the number of seconds that have elapsed since January 1, 1970 at 00:00:00 UTC.

Workspace

Workspace is an Oracle-specific concept that is used in Telemetry Streaming.

In the context of Telemetry Streaming, workspace is a namespace for storing data. Each workspace enables you to separate out metrics data from a manageability point of view, enabling you to manage the users who ingest data and the users who query data for each workspace. For example, you may want to store the metrics received from data center 1 in one workspace, and store the metrics from data center 2 in another workspace. You can restrict data center 1 to only certain users, while data center 2 to other users. Hence, workspaces allow you to segregate the data along with the user privileges. You can create different workspaces and give privileges for each workspace to specific users.

User

A user in the context of a workspace can be one of the following:

An administrator of the workspace
An ingest user who can ingest metric data into a workspace
A query user who can query metric data from a workspace

1.2 Telemetry Streaming Overview

Telemetry Streaming is a Time Series Database (TSDB) built on Oracle AI Database to collect, store, and process time series data. Telemetry Streaming offers a comprehensive, turnkey solution for metrics streaming with Oracle AI Database.

Metrics Streaming is essential for modern enterprise use cases such as DevOps monitoring, asset tracking, and anomaly detection. While Oracle AI Database offers best-of-breed features for building a metrics streaming solution, assembling these components can be complex and time-consuming. Telemetry Streaming simplifies this process by packaging Oracle’s powerful technologies into a streamlined, ready-to-use solution, enabling faster deployment, easier management, and reduced operational overhead for metrics streaming applications.

You can enable Oracle AI Database to run Telemetry Streaming on a basic setup with only the Telemetry Streaming PL/SQL packages installed. You also have the option of a full-fledged implementation of Telemetry Streaming with functionality that:

Supports ultra-fast metrics ingestion using REST and PL/SQL
Enables users to query metrics data for monitoring and alerting purposes through SQL, PL/SQL, or PromQL (Prometheus' Query Language)
Automates data lifecycle management, including compression and downsampling for older metrics data, data retention, and optimizing storage and performance over time

Parent topic: Introduction to Oracle AI Database Telemetry Streaming

1.3 Time Series in Telemetry Streaming

In Telemetry Streaming, time series is represented in the following manner.

A typical time series is identified by a combination of a metric name, say CPU_SECONDS, and a set of tags. The tags are key-value pairs that are specified in the JSON format. For example: {"server":"localhost", "ID":1, "make":"Intel"}. This combination uniquely identifies a time series.
Each time series is associated with an array of tuples <value, time> that signifies the value of the time series at the specified time.
The value can be a float or an integer. The time is a float that specifies the time in seconds since epoch (1-Jan-1971 00:00 UTC). Fractional seconds can be used for sub-seconds.
The value and time are immutable after they enter the system. They can only be deleted after the data retention time is over, but cannot be updated.

Parent topic: Introduction to Oracle AI Database Telemetry Streaming

1.4 Data Format and Naming Conventions

Metric Data Format

In Telemetry Streaming, each metric data sample is canonicalized into the following set of information.

Table 1-1 Metric Data Format in Telemetry Streaming

Name	Data Type	Description
`METRIC_NAME`	`VARCHAR2(512)`	The metric name part of the time series.
`METRIC_TAGS`	`VARCHAR2(4000)`	The tags part of the time series in JSON format.
`METRIC_VALUE`	`NUMBER`	The point-in-time (PIT) value of the time series.
`METRIC_TIME_EPOCH`	`NUMBER`	The time in seconds since epoch.

Naming Conventions

PromQL queries should conform to the rules of the PromQL.

Table 1-2 Naming Conventions for PromQL Queries

Name	Format
Metric Names	Metric names can include ASCII letters, digits, and underscores. They must match the regular expression (regex): `[a-zA-Z_][a-zA-Z0-9_]*`.
Tag/Label Keys	Tag or label keys may consist of ASCII letters, digits, and underscores, and should match the following pattern: `[a-zA-Z_][a-zA-Z0-9_]*`.
Tag/Label Values	Tag or label values can be enclosed in either single or double quotes and may contain any character. The corresponding regex pattern to match a label value is: `'.*'`.