3 Telemetry Streaming Administration

This chapter explains the administration and user management in Telemetry Streaming.

Topics:

3.1 Administration Overview

Learn in brief about the different types of users in Telemetry Streaming and their privileges.

Telemetry Streaming can have users that are existing database users or Oracle REST Data Services (ORDS) users.

Types of Database Users in Telemetry Streaming

Telemetry Streaming has 4 types of database users, based on their privileges and responsibilities:

  1. TELEMETRY_DBA (also called Telemetry DBA), which is created automatically on Telemetry Streaming installation and owns the Telemetry Streaming infrastructure

  2. Workspace, which is backed by an underlying schema and is used to logically separate Telemetry Streaming time series data for manageability

  3. Workspace administrator, is a database user, who is designated by an Oracle DBA to one or more Telemetry Streaming workspaces for workspace administration

  4. Telemetry Streaming users, are database users, who are assigned to workspaces by the workspace administrator for ingesting metric data, querying metric data, or both

See Also:

Database User Types and Privileges for more information about the user roles and privileges of database users

Types of ORDS Users in Telemetry Streaming

Telemetry Streaming has 2 main types of ORDS users, based on their privileges and responsibilities:

  1. ORDS Administrator user, who has administrative privileges for a workspace

  2. ORDS Ingest or ORDS Query users, who have privileges to ingest data, query data, or both using ORDS endpoints

See Also:

ORDS User Types and Privileges for more information about the user roles and privileges of ORDS users

Parent topic: Telemetry Streaming Administration

3.2 User Roles and Privileges

This section explains the user roles in Telemetry Streaming and their associated privileges.

Parent topic: Telemetry Streaming Administration

3.2.1 Database User Types and Privileges

The following table describes the different roles that each database user type plays in the Telemetry Streaming setup.

Table 3-1 Database User Types and Responsibilities

User Type Composition Responsibility

TELEMETRY_DBA (also called Telemetry DBA)

One Per PDB

When Telemetry Streaming is installed, a Telemetry DBA user called TELEMETRY_DBA is also created. The Telemetry DBA owns all the PL/SQL packages that provide the Telemetry Streaming infrastructure.

The Telemetry DBA is created with the Telemetry Streaming install script: $ORACLE_HOME/admin/telemetry_install_plsql.sql.

Workspace

Many per PDB

A workspace is used to logically separate time series data. Users can be assigned to each workspace for administration, ingestion, and querying.

For each workspace that the customer creates, a passwordless database user (schema) is created that owns the data, metadata, and scheduler jobs for lifecycle management of data. The name of the passwordless schema is in the following format: TM$<workspace name>.

Telemetry Workspace Administrator (also called admin user)

Many per workspace

Any Oracle AI Database user with the DBA role can enable an existing PDB user to be the administrator for a particular workspace.

Any Oracle DBA can assign appropriate privileges to the administrator by invoking the dbms_telemetry_workspace.enable_workspace_admin procedure.

The workspace administrator can designate other existing PDB users to act as ingest or query users by using dbms_telemetry_admin.enable_workspace_user with appropriate arguments.

The admin user has access to all the workspace administration PL/SQL packages and views.

See Also:

Telemetry Workspace Users

Many per workspace

An existing PDB user is enabled to be the user of a particular time series use case, which is represented as a workspace.

A Telemetry workspace administrator can enable or disable existing database users using the PL/SQL APIs. A Telemetry workspace administrator for a particular workspace invokes the dbms_telemetry_admin.enable_workspace_user procedure to enable an existing PDB user for the workspace.

These users can be assigned to ingest data, query data, or both. A PDB user can be assigned as an ingest user or query user to only one workspace at a time.

The ingest user has access to the ingest package and the query user has access to the query package and the query user views.

See Also:

Parent topic: User Roles and Privileges

3.2.2 ORDS User Types and Privileges

The following table describes the different roles that each ORDS user type plays in the Telemetry Streaming setup.

Table 3-2 ORDS User Types and Responsibilities

User Type Composition Responsibility

Telemetry ORDS Administrator (or ORDS Admin)

One per workspace

The Telemetry ORDS administrator is created for a workspace after the workspace is ORDS-enabled using DBMS_TELEMETRY_ADMIN.ENABLE_WORKSPACE_ORDS.

The admin credentials (client ID and client secret) retrieved using DBMS_TELEMETRY_ADMIN.GET_WORKSPACE_ORDS_ADMIN_AUTH enables the ORDS admin user to carry out workspace administration tasks such as, adding ORDS ingest or query users, and viewing and manipulating parameters for their workspace.

Telemetry ORDS Users (ORDS Ingest Users and ORDS Query Users)

Many per workspace

The ORDS admin uses the relevant REST endpoints to add ORDS ingest or query users to a workspace. Based on their assigned roles, these ORDS users can then access the corresponding ingest or query REST endpoints using the OAuth credentials, which was generated at the time of creating these ORDS users to ingest, query, or both.

See Also:

Managing ORDS Workspace Users for more information about how ORDS administrators and ORDS users are created

Parent topic: User Roles and Privileges

3.3 Managing a Workspace

This section explains how workspaces are managed in Telemetry Streaming.

Workspaces are managed differently for database users and ORDS users. The following sections explain the workspace management and administration procedures for database users and ORDS users.

Workspaces for Database Users Overview

The DBMS_TELEMETRY_WORKSPACE PL/SQL package deals with the workspace related operations. Each workpace is backed by an exclusive schema for storage of metric data. The name of the schema starts with TM$, such as TM$<workspace_name>. Any user with the Oracle DBA role can create or drop a workspace, and also enable or disable workspace administrators.

Within a workspace, there are 3 different roles that a user can play: a workspace administrator role, a query user role, or an ingest user role. The Oracle DBA can use the DBMS_TELEMETRY_WORKSPACE PL/SQL package to:

  • Enable an existing database user as a workspace administrator

  • Disable a user as a workspace administrator

The user with the workspace administrator role can then use the DBMS_TELEMETRY_ADMIN PL/SQL package or the workspace administration REST APIs to:

  • Enable an existing database user as an ingest user, query user, or both for their workspace(s)

  • Disable a user from their workspace(s)

  • Set and get parameters for their workspace(s)

See Also:

DBMS_TELEMETRY_WORKSPACE and DBMS_TELEMETRY_ADMIN in Oracle AI Database PL/SQL Packages and Types Reference for more information about the DBMS_TELEMETRY_WORKSPACE and DBMS_TELEMETRY_ADMIN PL/SQL packages

The Oracle DBA can assign multiple workspace administrators to manage one workspace or assign one workspace administrator to manage multiple workplaces. As for workspace users, a workspace administrator can assign multiple users to a workspace, but can assign one user to only one workspace, who can be an ingest user, a query user, or both for that workspace. The following diagram shows the relationship between workspaces and workspace administrators, and the relationship between workspaces and users.

Figure 3-1 Telemetry Streaming Workspace-User Relationships

Telemetry Streaming Workspace-User Relationships

Workspaces for ORDS Users Overview

You can find detailed information about managing ORDS workspace users and using REST API for workspace administration in Managing ORDS Workspace Users and Using REST API for Workspace Administration.

Parent topic: Telemetry Streaming Administration

3.3.1 Managing Database Workspace Users

This section describes how different database user roles are managed in Telemetry Streaming.

An Oracle DBA can create or drop workspaces. After a workspace is created, the Oracle DBA can assign the administrator role for a workspace to any existing database user, who is then called a workspace administrator.

The DBMS_TELEMETRY_WORKSPACE package allows the Oracle DBA to create or drop a workspace and enable or disable workspace administrators for the workspace. The Oracle DBA invokes the DBMS_TELEMETRY_WORKSPACE.CREATE_WORKSPACE() procedure to create a workspace and the DBMS_TELEMETRY_WORKSPACE.ENABLE_WORKSPACE_ADMIN() procedure to assign appropriate privileges to a workspace administrator.

As a part of the Telemetry Streaming installation and setup, the following management and administration procedures are used to manage database users in Telemetry Streaming:

Workspace Management

Any user with Oracle DBA privileges can manage a workspace using the following PL/SQL package.

Table 3-3 DBMS_TELEMETRY_WORKSPACE

Procedure/Function Description

CREATE_WORKSPACE

Creates a new workspace

DROP_WORKSPACE

Drops a workspace

ENABLE_WORKSPACE_ADMIN

Adds an admin user to a workspace

DISABLE_WORKSPACE_ADMIN

Removes an admin user from a workspace

See Also:

DBMS_TELEMETRY_WORKSPACE in Oracle AI Database PL/SQL Packages and Types Reference for more information about the DBMS_TELEMETRY_WORKSPACE PL/SQL package.

Additionally, the Oracle DBA has access to the following views.

Table 3-4 Workspace Management Views

Views Description

TELEMETRY_DBA.TELEMETRY_WORKSPACES

Lists all the Telemetry Streaming workspaces created in the PDB

TELEMETRY_DBA.TELEMETRY_ADMINS

Lists all the admins associated with the Telemetry Streaming workspaces created in the PDB

See Also:

Tables and Views for more information about the workspace management views

Workspace Administration

An existing Oracle AI Database user can be assigned as an administrator for a workspace. A workspace administrator can add users for ingestion or querying. The workspace administrator can also alter the workspace data life cycle management parameters.

A workspace administrator can use the following PL/SQL packages.

Table 3-5 DBMS_TELEMETRY_ADMIN

Procedure/Function Description

ENABLE_WORKSPACE_USER

Adds an existing database user to a workspace

DISABLE_WORKSPACE_USER

Disables a user from the workspace

SET_WORKSPACE_PARAMETER

Sets a workspace parameter
GET_WORKSPACE_PARAMETER

Returns the value of a workspace parameter

See Also:

DBMS_TELEMETRY_ADMIN in Oracle AI Database PL/SQL Packages and Types Reference for more information about the DBMS_TELEMETRY_ADMIN PL/SQL package.

Additionally, a workspace administrator has access to the following views.

Table 3-6 Workspace Administration Views

Views Description

TELEMETRY_DBA.TELEMETRY_WORKSPACE_USERS

Lists all the users associated with all the workspaces administered by an Admin user

TM$<workspace name>.TELEMETRY_INGEST_STATS

Contains one row for every call made to ingest_metrics by the ingest users

TM$<workspace name>.TELEMETRY_INGEST_DISCARDS

Metrics whose time is older than 3600 seconds from the current time, are discarded and recorded in this view
TM$<workspace name>.TELEMETRY_QUERY_STATS

Contains one row for every call made to procedures of dbms_telemetry_query by the query users
TM$<workspace name>.TELEMETRY_ADMIN_LOG

Contains messages related to admin actions

See Also:

Tables and Views for more information about the workspace management views

Parent topic: Managing a Workspace

3.3.2 Managing ORDS Workspace Users

This section describes how ORDS workspace users are managed in Telemetry Streaming.

An ORDS workspace administrator can add ORDS users for ingestion or querying. The OAuth client ID:client secret pair of credentials, which is created by the ORDS admin user is required if the users want to push data into or query data from Telemetry Streaming through ORDS. The users then have to follow the OAuth 2-legged authorization mechanism to ingest or query data using ORDS endpoints.

To enable ORDS for a workspace and get the OAuth credentials of the ORDS workspace admin user, the following PL/SQL package is used.

Table 3-7 DBMS_TELEMETRY_ADMIN

Procedure/Function Description

ENABLE_WORKSPACE_ORDS

This procedure enables ORDS for the given workspace and creates Telemetry Streaming REST endpoints

GET_WORKSPACE_ORDS_ADMIN_AUTH

This function returns the Telemetry Streaming ORDS admin user client-ID and cliend-secret OAuth credentials

The following steps are followed to set up a Telemetry Streaming workspace for ORDS users.

Before enabling ORDS for a workspace, the workspace schema (for example, TM$WKSP1) must be enabled from any ORDS_DBA. 

exec ORDS.enable_schema(p_enabled => TRUE, p_schema => 'TM$WKSP1', p_url_mapping_type => 'BASE_PATH',
 p_url_mapping_pattern => 'wksp1', p_auto_rest_auth => FALSE);

After the schema is ORDS-enabled, you must connect as the workspace admin and run the following statement:

exec dbms_telemetry_admin.enable_workspace_ords('wksp1');

Once the workspace is ORDS-enabled, an admin user is created. The admin credentials (client ID and client secret) can then be retrieved by running the following statement:

select dbms_telemetry_admin.get_workspace_ords_admin_auth('wksp1');

After this setup, the workspace is ORDS-enabled and ready for admin-authenticated interface usage.

Once an ORDS admin user is created for a workspace, ORDS ingest or query users can be added or removed using the add_user and drop_user REST endpoints (accessible by the admin user using the admin client ID-client secret).

A user can be added using the following endpoint:

/ords/<Workspace Name>/add_user

On successfully adding the user, the API returns the client ID and client secret of the new user.

These credentials allow the users to access relevant endpoints. For example, an ingest ORDS user ing1 in workspace wksp1 can access the following ingest endpoint: 

/ords/wksp1/ing1/ingest

Users can be removed using the following endpoint:

/ords/<Workspace Name>/drop_user

Note:

A single ORDS user can be granted both ingest and query privileges.

See Also:

Using REST API for Workspace Administration for more information about the workspace administration APIs

Parent topic: Managing a Workspace

3.3.2.1 Using REST API for Workspace Administration

This section provides the documentation for REST APIs used to manage a workspace.

Note:

  • Ensure that ORDS is installed and Telemetry Streaming is REST enabled before using REST APIs.

  • To make REST API calls, you need an OAuth2 access token to use for authorization. The token can be derived after you provide the Client ID and Client Secret pair of credentials created by the ORDS workspace administrator using the PL/SQL interface.

See Also:

Installing Oracle REST Data Services for more information about the ORDS installation.

ORDS Workspace Administration REST API

The ORDS workspace administration APIs enable the ORDS workspace administrator to perform a variety of administrative tasks, such as managing ORDS users, configuring and checking workspace parameters, and accessing workspace logs. There are several admin ORDS endpoints available for performing these administrative operations, such as adding new ORDS users, removing existing users, and accessing or modifying configuration parameters for a workspace.

These admin endpoints are described in the following API documentation:

Table 3-8 REST API Summary

API Type Summary

POST /ords/<Workspace Name>/add_user

Adds an ingest or query user to a workspace

POST /ords/<Workspace Name>/drop_user

Drops an ingest or query user from a workspace

GET /ords/<Workspace Name>/list_users

Gets the list of users: user names and roles in the current workspace

GET /ords/<Workspace Name>/init_parameters

Initializes the parameters to their default values

GET /ords/<Workspace Name>/get_parameters

Gets all the parameters with their values

POST /ords/<Workspace Name>/set_parameter

Sets a new value to a parameter

GET /ords/<Workspace Name>/get_parameter/<Parameter Name>

Gets the value of a given parameter

GET /ords/<Workspace Name>/list_log/?from=<start time epoch>&to=<end time epoch>&limit=<number of entries>

Scrapes all the top data (specified by limit) in TELEMETRY_ADMIN_LOG in the time duration range specified and shows as collection_feed

GET /ords/<Workspace Name>/show_ingest_stats/?from=<start time epoch>&to=<end time epoch>&limit=<number of entries>

Scrapes all the top data (specified by limit) in telemetry_ingest_stats in the time duration range specified and shows as collection_feed

GET /ords/<Workspace Name>/show_query_stats/?from=<start time epoch>&to=<end time epoch>&limit=<number of entries>

Scrapes all the top data (specified by limit) in telemetry_query_stats in the time duration range specified and shows as collection_feed
Add a User

METHOD:

POST

PATH:

/ords/<Workspace Name>/add_user

USER:

Workspace ORDS Admin User

SUMMARY:

Adds an ingest or a query user to a workspace

DATA:

{"user_name":<User Name> , "role": <INGEST|QUERY>}

HTTP CODE:
  • 201 - Success with clientId and secret
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/add_user
  • DATA: {"user_name":"INGEST1" , "role": "INGEST"}
  • CODE: 201 - Successfully inserted
  • {"client_id":"RWRvoD2byhqNdWImmWbelA..","client_secret":"jjkvQPAZbbVTg6iozelk0Q.."}

Note:

You can add a user with both ingest and query role in ORDS by specifying the "role" as "INGEST|QUERY" or "QUERY|INGEST".
Drop a User

METHOD:

POST

PATH:

/ords/<Workspace Name>/drop_user

USER:

Workspace ORDS Admin User

SUMMARY:

Drops an ORDS ingest or an ORDS query user from a workspace

DATA:

{"user_name":<User Name>}

HTTP CODE:
  • 201 - User dropped successfully: <User Name>
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/drop_user
  • DATA: {"user_name":"INGEST1"}
  • CODE: 201 - User dropped successfully: INGEST1
LIST USERS

METHOD:

GET

PATH:

/ords/<Workspace Name>/list_users

USER:

Workspace ORDS Admin User

SUMMARY:

Gets the list of user names, their respective roles, and the client ID and client secret of the users in the current workspace

HTTP CODE:
  • 200 - Success with data {[{"user_name": <user>,"role": <role>},...]}
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/list_users
  • CODE: 200 - Success
{
    "items":[
        {
            "name":"INGEST1",
            "description":"A client for ingest management",
            "client_id":"_sPBlyIrAXpRLn6rRX4-YQ..",
            "client_secret":"C2e33aDKGM0-AowcgPjmmg.."
        },
        {
            "name":"admin_client",
            "description":"default admin client",
            "client_id":"CCpAyUsiCggqZNMrm4l3ZA..",
            "client_secret":"KPQF3kDOCClFanMDCS1Ugg.."
        }
    ],
    "hasMore":false,
    "limit":20,"offset":0,
    "count":2
}
Initialize Parameters

METHOD:

GET

PATH:

/ords/<Workspace Name>/init_parameters

USER:

Workspace ORDS Admin User

SUMMARY:

Initializes the parameters to default values

HTTP CODE:
  • 200 - Success, params initialized to default values
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/init_parameters
  • CODE: 200 - Success
Get Parameters

METHOD:

GET

PATH:

/ords/<Workspace Name>/get_parameters

USER:

Workspace ORDS Admin User

SUMMARY:

Gets all the parameters with their values

HTTP CODE:
  • 200 - Success
  • {[{"parameter_name": <name>,"parameter_value": <value>, "parameter_modified_timestamp":<modified date>},...]}
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/get_parameters
  • CODE: 200 - Success
{
    "items":[
      {"parameter_name":"delete_after_duration_hours","parameter_value":"240","parameter_modified_timestamp":"2025-07-04T11:17:38.381Z"},
      {"parameter_name":"compress_after_duration_hours","parameter_value":"24","parameter_modified_timestamp":"2025-07-04T11:17:38.392Z"},
      {"parameter_name":"downsample_after_duration_hours","parameter_value":"24","parameter_modified_timestamp":"2025-07-04T11:17:38.398Z"},
      {"parameter_name":"downsample_interval_seconds","parameter_value":"60","parameter_modified_timestamp":"2025-07-04T11:17:38.400Z"},
      {"parameter_name":"downsample_method","parameter_value":"avg","parameter_modified_timestamp":"2025-07-04T11:17:38.404Z"}
    ],
    "hasMore":false,"limit":20,"offset":0,"count":5
}
SET Parameter Value

METHOD:

POST

PATH:

/ords/<Workspace Name>/set_parameter

USER:

Workspace ORDS Admin User

SUMMARY:

Sets a new value to a parameter

DATA:

{"parameter_name":<param_name>, "value":<new_value>}

HTTP CODE:
  • 201 - Success, parameter:param_name value set to:new_value
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/set_parameter
  • DATA: {"parameter_name":"downsample_interval_seconds", "value":70}
  • CODE: 201 - Success
  • {"parameter":"downsample_interval_seconds","value":"70"}
Get Parameter Value

METHOD:

GET

PATH:

/ords/<Workspace Name>/get_parameter/<Parameter Name>

USER:

Workspace ORDS Admin User

SUMMARY:

Gets the value for a given parameter

HTTP CODE:
  • 200 - Success with data
  • {"parameter_name": <name>,"parameter_value": <value>, "default":<value>, last_modified: "timestamp"}
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/get_parameter/downsample_interval_seconds
  • CODE: 200 - Success
{"parameter_name":"downsample_interval_seconds", "parameter_value":70,
 "default":60, "last_modified":"04-JUL-25 12.00.06.542000 PM"}
Get Admin Logs

METHOD:

GET

PATH:

/ords/<Workspace Name>/list_log/?from=<start time epoch>&to=<end time epoch>&limit=<number of entries>

USER:

Workspace ORDS Admin User

SUMMARY:

This API scrapes all the top data (specified by limit) in TELEMETRY_ADMIN_LOG in the time duration range specified and shows as collection_feed.

HTTP CODE:
  • 200 - Success with data
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/list_log/?from=1704700084&to=1704710884&limit=1
  • CODE: 200 - Success
{
   "items":[
       {
           "log_message":"DOWNSAMPLE:Checking Table_flat Done: .040007",
           "log_timestamp":"2025-07-04T12:04:30.173Z"
       }
   ],
   "hasMore":false,"limit":0,"offset":0,"count":1
}
Get Ingest Data

METHOD:

GET

PATH:

/ords/<Workspace Name>/show_ingest_stats/?from=<start time epoch>&to=<end time epoch>&limit=<number of entries>

USER:

ORDS Ingest User

SUMMARY:

This API scrapes all the top data (specified by limit) in TELEMETRY_INGEST_STATS in the time duration range specified and shows as collection_feed

HTTP CODE:
  • 200 - Success with data
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/show_ingest_stats/?from=1704700084&to=1704710884&limit=100
  • OUTPUT:
{
    "items":[
        {
            "payload_size":559,
            "metrics_ingested":6,
            "metrics_given":6,
            "ingest_user_name":"INGEST1",
            "ingest_duration_milliseconds":1100,
            "ingest_method":"ords",
            "ingest_timestamp":"2025-07-03T09:21:05.236Z"
        }
    ],
    "hasMore":false,
    "limit":0,
    "offset":0,
    "count":2
}
Get Query Data

METHOD:

GET

PATH:

/ords/<Workspace Name>/show_query_stats/?from=<start time epoch>&to=<end time epoch>&limit=<number of entries>

USER:

ORDS Query User

SUMMARY:

This API scrapes all the top data (specified by limit) in TELEMETRY_QUERY_STATS in the time duration range specified and shows as collection_feed

HTTP CODE:
  • 200 - Success with data
  • 400 - Failed with error message {"error_code": <code>, "error_message":<message>}
  • 401 - Unauthorized

EXAMPLE:
  • PATH: /ords/workspace1/show_query_stats/?from=1751636250&to=1751636258&limit=1
  • OUTPUT:
{
    "items":[
        {
            "query_type":"promql_instant",
            "start_time_epoch":1751636257,
            "end_time_epoch":null,
            "step_size_seconds":null,
            "query_user_name":"QUERYUSER1",
            "query_duration_milliseconds":380,
            "query_method":"ords",
            "query_timestamp":"2025-07-04T13:43:12.590Z"
        }
    ],
    "hasMore":false,"limit":0,"offset":0,"count":1
}