DBMS_OBSERVABILITY

DBMS_OBSERVABILITY manages ADBS Native Observability (OpenTelemetry) and provides native, in-database OpenTelemetry tracing and logging.

DBMS_OBSERVABILITY natively tracks SQL operations as a database span and emits unified OTEL (OpenTelemetry) signals to your OpenTelemetry compliant collector.

DBMS_OBSERVABILITY Overview

You can use the functions and procedures contained in the DBMS_OBSERVABILITY package to configure the OpenTelemetry repository for Oracle AI Database.

The DBMS_OBSERVABILITY package enables you to configure and manage Oracle AI Database Observability for OpenTelemetry. Use the procedures and functions in this package to:

Enable or disable observability services and options
Configure endpoints for exporting traces and logs to OpenTelemetry collectors
Manage credentials for secure communication with external endpoints
View current service status and endpoint configurations

The following terms are used with OpenTelemetry. A definition of each is provided.

Distributed tracing (spans) - Units of work with timing and attributes used for distributed correlation.
Log correlation - Discrete textual or structured records (for example, “hello, world”) emitted by distributed tracing. Logs are not traces. OpenTelemetry correlates distributed tracing log records to spans using the trace_id and span_id for unified analysis.

DBMS_OBSERVABILITY Security Model

The DBMS_OBSERVABILITY package consists of a number of observability related subprograms.

Oracle Database installs this package in the SYS schema. The EXECUTE privilege is granted to users with the DBA role and should not be extended to general users. The DBMS_OBSERVABILITY package runs with the invoker’s permissions. This package invokes DBMS_CREDENTIAL internally. Relevant security and privilege requirements also apply.

DBMS_OBSERVABILITY Constants

The DBMS_OBSERVABILITY package defines various constants for specifying parameter values.

Table 1 DBMS_OBSERVABILITY

Name	Type	Value	Description
`ALL_SERVICES`	`BINARY_INTEGER`	`0`	Represents all services. This is the default value.

Table 2 DBMS_OBSERVABILITY

Name	Type	Value	Description
`ALL_OPTIONS`	`BINARY_INTEGER`	`0`	Represents all service options.
`SHOW_EXTRA_METADATA`	`BINARY_INTEGER`	`1`	Shows extra metadata. This option is disabled by default.
`EXPORT_WHEN_EMPTY`	`BINARY_INTEGER`	`2`	Enables information even if no records were generated for an operation. This option is disabled by default.
`CAPTURE_TRACES`	`BINARY_INTEGER`	`3`	Captures information that goes to disk by default. This option is enabled by default.

Table 3 DBMS_OBSERVABILITY Constants-Info Levels

Name	Type	Value	Description
`ALL_INFO`	`BINARY_INTEGER`	`0`	Shows all information levels.
`RUNTIME_INFO`	`BINARY_INTEGER`	`1`	Shows the CDB configuration so that the client can determine if a service or option is available for use.
`CONTAINER_INFO`	`BINARY_INTEGER`	`2`	Shows the current container’s information.

Table 4 DBMS_OBSERVABILITY Constants-Token Types

Name	Type	Value	Description
`OCI_DATAKEY`	`BINARY_INTEGER`	`0`	Represents a token of the type DATAKEY.

Table 5 DBMS_OBSERVABILITY Constants-Endpoint Types

Name	Type	Value	Description
`OTEL_LOGS`	`BINARY_INTEGER`	`0`	Specifies that the endpoint type can ingest OTLP (OpenTelemetry Protocol) logs.^*
`OTEL_TRACES`	`BINARY_INTEGER`	`1`	Specifies that the endpoint type can ingest OTLP (OpenTelemetry Protocol) traces.^*

*Only HTTP2 is supported.

Summary of DBMS_OBSERVABILITY Subprograms

This table lists the DBMS_OBSERVABILITY subprograms and briefly describes them.

Table 6 DBMS_OBSERVABILITY Package

Subprogram	Description
`ADD_ENDPOINT`	Adds an endpoint to monitor.
`ATTACH_CREDENTIAL`	Attaches a credential to an endpoint.
`CREATE_CREDENTIAL`	Creates a user-only, username-password, or token-based credential.
`DETACH_CREDENTIAL`	Detaches a credential from an endpoint.
`DISABLE_ENDPOINT`	Disables monitoring of an endpoint.
`DISABLE_SERVICE`	Disables a service.
`DISABLE_SERVICE_OPTION`	Disables a service option.
`DROP_CREDENTIAL`	Drops a credential.
`ENABLE_ENDPOINT`	Enables an endpoint.
`ENABLE_SERVICE`	Enables a service.
`ENABLE_SERVICE_OPTION`	Enables a service option.
`SHOW_ENDPOINTS`	Shows a list of all endpoints.
`SHOW_SERVICE_STATUS`	Shows the configuration of all services on the current container, the CDB, or both.
`UPDATE_CREDENTIAL`	Updates the specified credential attribute.

ADD_ENDPOINT Procedure

The ADD_ENDPOINT procedure creates an endpoint that the Oracle AI Database can connect to and export OTLP (OpenTelemetry Protocol) data.

Syntax

DBMS_OBSERVABILITY.ADD_ENDPOINT( endpoint_type   IN BINARY_INTEGER,
                                 endpoint        IN VARCHAR2,
                                 credential_name IN VARCHAR2 DEFAULT NULL );

Parameters

Table 7 ADD_ENDPOINT Procedure

Parameter	Description
`endpoint_type`	The endpoint type.
`endpoint`	The endpoint URI to add.
`credential_name`	The name of the credential used with the specified endpoint.

Usage Notes

The endpoint should be configured inside the container in which it will be used and is enabled by default.

Examples

The following example illustrates how to add an endpoint for https://example.com:1234/ot_endp/v1/traces where no credential is required:

execute dbms_observability.add_endpoint( endpoint_type   => dbms_observability.otel_traces,
                                         endpoint        => 'https://example.com:1234/ot_endp/v1/traces',
                                         credential_name => NULL );

ATTACH_CREDENTIAL Procedure

The ATTACH_CREDENTIAL procedure attaches a credential to the specified endpoint.

Syntax

DBMS_OBSERVABILITY.ATTACH_CREDENTIAL( endpoint IN VARCHAR2, credential_name IN VARCHAR2 );

Parameters

Table 8 ATTACH_CREDENTIAL Procedure

Parameter	Description
`endpoint`	Specifies the endpoint.
`credential_name`	The name of the credential.

Examples

The following example illustrates how to attach a credential to the endpoint https://example.com:1234/ot_endp/v1/traces:

SQL> execute dbms_observability.attach_credential( endpoint        => 'https://example.com:1234/ot_endp/v1/traces',
                                                   credential_name => 'my_cred' );

CREATE_CREDENTIAL Procedure

The CREATE_CREDENTIAL procedure creates either a user-only, user-password, or token-based credential.

Syntax

To create a user-only or username-password credential:

DBMS_OBSERVABILITY.CREATE_CREDENTIAL( credential_name IN VARCHAR2,
                                      username        IN VARCHAR2,
                                      password        IN VARCHAR2,
                                      comments        IN VARCHAR2 DEFAULT NULL );

To create a token-based credential:

DBMS_OBSERVABILITY.CREATE_CREDENTIAL( credential_name IN VARCHAR2,
                                      token_type      IN BINARY_INTEGER,
                                      token           IN VARCHAR2,
                                      comments        IN VARCHAR2 DEFAULT NULL );

Parameters

Table 9 CREATE_CREDENTIAL Procedure

Parameter	Description
`credential_name`	The user-specified name of the credential.
`username`	The username for the credential.
`password`	The user password for the credential.
`token_type`	The type of the token to create.
`token`	The token itself.
`comments`	User specified comments about the credential.

Usage Notes

You must use this Oracle API to create and manage credentials used for DBMS_OBSERVABILITY services or Oracle does not guarantee the usability of the observability services.

Examples

The following example illustrates how to create a user-only credential:

execute dbms_observability.create_credential( credential_name => 'my_cred_1',
                                              username        => 'my_usr',
                                              password        => NULL,
                                              comments        => 'My dbms_observability credential' );

The following example illustrates how to create a user-password credential:

execute dbms_observability.create_credential( credential_name => 'my_cred_2',
                                              username        => 'my_usr',
                                              password        => 'my_pwd',
                                              comments        => NULL );

The following example illustrates how to create a token-based credential:

execute dbms_observability.create_credential( credential_name => 'my_cred_3',
                                              token_type      => dbms_observability.oci_datakey,
                                              token           => 'abcdefghijklmnopqrstuvwxyz',
                                              comments        => 'This is my token credential!' );

DETACH_CREDENTIAL Procedure

The DETACH_CREDENTIAL procedure detaches a credential from the specified endpoint.

Syntax

DBMS_OBSERVABILITY.DETACH_CREDENTIAL( endpoint IN VARCHAR2 );

Parameters

Table 10 DETACH_CREDENTIAL Procedure

Parameter	Description
`endpoint`	Specifies the endpoint.

Examples

The following example illustrates how to detach a credential from the endpoint https://example.com:1234/ot_endp/v1/traces:

SQL> execute dbms_observability.detach_credential( endpoint => 'https://example.com:1234/ot_endp/v1/traces' );

DISABLE_ENDPOINT Procedure

The DISABLE_ENDPOINT procedure disables the specified endpoint.

Syntax

DBMS_OBSERVABILITY.DISABLE_ENDPOINT( endpoint IN VARCHAR2 );

Parameters

Table 11 DISABLE_ENDPOINT Procedure

Parameter	Description
`endpoint`	Specifies the endpoint to disable.

Examples

The following example illustrates how to disable the endpoint https://example.com:1234/ot_endp/v1/traces:

SQL> execute dbms_observability.disable_endpoint( endpoint => 'https://example.com:1234/ot_endp/v1/traces' );

DISABLE_SERVICE Procedure

The DISABLE_SERVICE procedure disables the specified services.

Syntax

DBMS_OBSERVABILITY.DISABLE_SERVICE( svc_id IN BINARY_INTEGER DEFAULT all_services );

Parameters

Table 12 DISABLE_SERVICE Procedure

Parameter	Description
`svc_id`	Specifies the service or services to disable.

Usage Notes

The CDB is a global reference for service availability, that is, the PDBs will only be able to use a service enabled both on the current container and at the CDB.

Examples

The following example illustrates how to disable all services using the default value:

SQL> execute dbms_observability.disable_service;

DISABLE_SERVICE_OPTION Procedure

The DISABLE_SERVICE_OPTION procedure disables the specified services options.

Syntax

DBMS_OBSERVABILITY.DISABLE_SERVICE_OPTION( option_id IN BINARY_INTEGER DEFAULT all_options );

Parameters

Table 13 DISABLE_SERVICE_OPTION

Parameter	Description
`option_id`	Specifies the service option or options to disable

Usage Notes

The CDB is a global reference for service availability, that is, the PDBs will only be able to use a service enabled both on the current container and at the CDB.

Examples

The following example illustrates how to disable capturing traces:

SQL> execute dbms_observability.disable_service_option( option_id => dbms_observability.capture_traces );

The following example illustrates how to disable all service options:

SQL> execute dbms_observability.disable_service_option( option_id => dbms_observability.all_options );

DROP_CREDENTIAL Procedure

The DROP_CREDENTIAL procedure drops a credential.

Syntax

DBMS_OBSERVABILITY.DROP_CREDENTIAL( credential_name IN VARCHAR2 );

Parameters

Table 14 DROP_CREDENTIAL Procedure

Parameter	Description
`credential_name`	Specifies the name of the credential to drop.

Usage Notes

The procedure does not validate that the credential was created through the DBMS_OBSERVABILITY interface. This action can not be undone.

Examples

The following example illustrates how to a credential named MY_CRED:

SQL> execute dbms_observability.drop_credential( credential_name => 'my_cred' );

ENABLE_ENDPOINT Procedure

The ENABLE_ENDPOINT procedure enables the specified endpoint.

Syntax

DBMS_OBSERVABILITY.ENABLE_ENDPOINT( endpoint IN VARCHAR2 );

Parameters

Table 15 ENABLE_ENDPOINT Procedure

Parameter	Description
`endpoint`	Specifies the endpoint to enable.

Examples

The following example illustrates how to enable the endpoint https://example.com:1234/ot_endp/v1/traces:

SQL> execute dbms_observability.enable_endpoint( endpoint => 'https://example.com:1234/ot_endp/v1/traces' );

ENABLE_SERVICE Procedure

The ENABLE_SERVICE procedure enables the specified services.

Syntax

DBMS_OBSERVABILITY.ENABLE_SERVICE( svc_id IN BINARY_INTEGER DEFAULT all_services );

Parameters

Table 16 ENABLE_SERVICE Procedure

Parameter	Description
`svc_id`	Specifies the service or services to enable.

Usage Notes

The CDB is a global reference for service availability, that is, the PDBs will only be able to use a service enabled both on the current container and at the CDB.

Examples

The following example illustrates how to enable all services using the default value:

SQL> execute dbms_observability.enable_service;

ENABLE_SERVICE_OPTION Procedure

The ENABLE_SERVICE_OPTION procedure enables the specified services options.

Syntax

DBMS_OBSERVABILITY.ENABLE_SERVICE_OPTION( option_id IN BINARY_INTEGER DEFAULT all_options );

Parameters

Table 17 ENABLE_SERVICE Procedure

Parameter	Description
`option_id`	Specifies the service option or options to enable.

Usage Notes

The CDB is a global reference for service availability, that is, the PDBs will only be able to use a service enabled both on the current container and at the CDB.

Examples

The following example illustrates how to enable capturing traces:

SQL> execute dbms_observability.enable_service_option( option_id => dbms_observability.capture_traces );

The following example illustrates how to enable all options using the default option:

SQL> execute dbms_observability.enable_service_option;

SHOW_ENDPOINTS Function

The SHOW_ENDPOINTS functions returns all endpoints as a JSON list.

Syntax

DBMS_OBSERVABILITY.SHOW_ENDPOINTS;

Usage Notes

The SHOW_ENDPOINTS function returns a CLOB containing a JSON array as follows:

[{"Id":Endpoint's id,"Type":"Endpoint's type","Endpoint":"URL", "Status":"Enabled or Disabled","Credential":"Credential's name or None"}]

Examples

The following example illustrates how to show all endpoints:

set serveroutput on;
DECLARE
  v_endpoints CLOB;
BEGIN
  select dbms_observability.show_endpoints into v_endpoints;

  dbms_output.put_line( v_endpoints );
END;
/

SHOW_SERVICE_STATUS Function

The SHOW_SERVICE_STATUS function returns the configuration of all services either on the current container, the CDB, or both.

Syntax

DBMS_OBSERVABILITY.SHOW_SERVICE_STATUS( info_level IN BINARY_INTEGER DEFAULT all_info );

Parameters

Table 18 SHOW_SERVICE_STATUS Function

Parameter	Description
`info_level`	Specifies the level of information to return. The default is all information.

Usage Notes

The SHOW_SERVICE_STATUS function returns a CLOB containing a list of JSONs as follows:

[{"Component":[{"Service/Option":"Name","Enabled":0 or 1}]}]

Examples

The following example illustrates how to show the runtime information:

set serveroutput on;
DECLARE
  v_config  VARCHAR2;
BEGIN
  -- See global configuration
  SELECT dbms_observability.show_service_status( info_level => dbms_observability.runtime_info )
  INTO   v_config;

  dbms_output.put_line( v_config );
END;
/

The following example illustrates how to show the container configuration:

set serveroutput on;
DECLARE
  v_config  VARCHAR2;
BEGIN
  -- See container's configuration
  SELECT dbms_observability.show_service_status( info_level => dbms_observability.container_info )
  INTO   v_config;

  dbms_output.put_line( v_config );
END;
/

The following example illustrates two methods of showing all information:

set serveroutput on;
DECLARE
  v_config  VARCHAR2;
BEGIN
  -- See all with default value
  SELECT dbms_observability.show_service_status
  INTO   v_config;
  -- or see all information using the all_info constant
  SELECT dbms_observability.show_service_status( info_level => dbms_observability.all_info )
  INTO   v_config;

  dbms_output.put_line( v_config );
END;
/

UPDATE_CREDENTIAL Procedure

The UPDATE_CREDENTIAL procedure updates credential values.

Syntax

DBMS_OBSERVABILITY.UPDATE_CREDENTIAL( credential_name IN VARCHAR2,
                                      attribute       IN VARCHAR2,
                                      value           IN VARCHAR2 );

Parameters

Table 19 UPDATE_CREDENTIAL Procedure

Parameter	Description
`credential_name`	Specifies the name of the credential to update.
`attribute`	<p>Name of the credential attribute to update. Valid values are: <ul id="GUID-A86360BB-E259-4992-A71A-55D2D53EB190__UL_SCM_PGB_NHC" style="list-style-type: disc;"> <li>`username`</li> <li>`password`</li> <li>`token`</li> <li>`comments`</li> </ul> </p>
`value`	The new value for the specified attribute.

Exceptions

Table 20 UPDATE_CREDENTIAL Procedure

Exception	Description
`ORA-20020`	An attribute cannot be changed or the credential is an invalid DBMS_OBSERVABILITY credential.

Usage Notes

If you are updating a token-based credential, you can not specify a USERNAME or PASSWORD attribute. If you are updating a user-only or user-password credential, you can not specify a TOKEN attribute. The CREDENTIAL_NAME and TOKEN_TYPE attributes can not be updated.

Examples

The following example illustrates how to update the comments value for a specific credential:

SQL> execute dbms_observability.update_credential(
       credential_name => 'my_cred',
       attribute       => 'comments',
       value           => 'This is my credential for observability'
     );