18.6 Enable Diagnostic Tracing

Oracle Deep Data Security (Deep Sec) generates trace files at the system or session level to capture detailed diagnostic information regarding data grant enforcement, query rewrites, data definition language (DDL) operations, and security context establishment.

You can use trace files to capture detailed operations when standard troubleshooting does not resolve an issue, or when requested by Oracle Support. Set the tracing level to high to ensure that the maximum level of diagnostic information is recorded.

Note:

  • Tracing generates substantial output that increases storage consumption and may degrade database performance. To minimize the impact, enable tracing for the minimum time necessary, reproduce the issue immediately, and disable tracing as soon as you capture the required data.
  • Trace files capture relevant data (such as query text, applied predicates, and rewritten queries) only on the first execution of a query. After the first successful execution, the cursor is cached and subsequent executions bypass the query rewrite phase.
Prerequisites:
  • Connect to the pluggable database (PDB) as a database user or a Deep Sec user.
  • Ensure you have the ALTER SYSTEM privilege to enable system-level tracing, or the ALTER SESSION privilege to enable session-level tracing.

Topics:

18.6.1 Trace Data Grants and Query Rewrites

Diagnose issues with data grant enforcement, predicate application, and query rewrite behavior.

  1. Enable tracing.
    Run the following commands to enable data security tracing at the system level (all sessions):
    ALTER SYSTEM SET events '10053 TRACE NAME CONTEXT FOREVER';
ALTER SYSTEM SET events 'TRACE[XSXDS] disk=high';
ALTER SYSTEM SET events 'TRACE[XSVPD] disk=high';
ALTER SYSTEM SET events 'TRACE[DATA_GRANTS] disk=high';
    Run the following commands to enable data security tracing at the session level (current session only):
    ALTER SESSION SET events '10053 TRACE NAME CONTEXT FOREVER';
ALTER SESSION SET events 'TRACE[XSXDS] disk=high';
ALTER SESSION SET events 'TRACE[XSVPD] disk=high';
ALTER SESSION SET events 'TRACE[DATA_GRANTS] disk=high';
  2. Reproduce the issue.

    After enabling the trace, immediately execute the queries or operations that are causing the issue.

  3. Locate and examine the trace file.
    Run the following query to locate the trace file for your session:
    SELECT VALUE FROM V$DIAG_INFO WHERE NAME = 'Default Trace File';

    Open the trace file and inspect it for the generated query text, applied predicates, rewritten query, and any errors related to Deep Sec logic. Share this file with Oracle Support if requested.

  4. Disable tracing after troubleshooting is complete.
    At the system level:
    ALTER SYSTEM SET events '10053 TRACE NAME CONTEXT OFF';
ALTER SYSTEM SET events 'TRACE[XSXDS] OFF';
ALTER SYSTEM SET events 'TRACE[XSVPD] OFF';
ALTER SYSTEM SET events 'TRACE[DATA_GRANTS] OFF';
    At the session level:
    ALTER SESSION SET events '10053 TRACE NAME CONTEXT OFF';
ALTER SESSION SET events 'TRACE[XSXDS] OFF';
ALTER SESSION SET events 'TRACE[XSVPD] OFF';
ALTER SESSION SET events 'TRACE[DATA_GRANTS] OFF';

    Note:

    Session-level tracing is automatically disabled when the database session ends.

18.6.2 Trace End-User and Data Role DDLs

Diagnose issues with DDL statements for end users and data roles (for example, CREATE END USER or CREATE DATA ROLE).

  1. Enable tracing.
    At the system level (all sessions):
    ALTER SYSTEM SET events 'TRACE[END_USER_AND_DATA_ROLE] disk=high';
    At the session level (current session only):
    ALTER SESSION SET events 'TRACE[END_USER_AND_DATA_ROLE] disk=high';
  2. Reproduce the issue.

    After enabling the trace, immediately execute the queries or operations that are causing the issue.

  3. Locate and examine the trace file.
    Run the following query to locate the trace file for your session:
    SELECT VALUE FROM V$DIAG_INFO WHERE NAME = 'Default Trace File';

    Open the trace file and inspect it for end user and data role creation or modification details, privilege assignments, and any related errors. Share this file with Oracle Support if requested.

  4. Disable tracing after troubleshooting is complete.
    At the system level:
    ALTER SYSTEM SET events 'TRACE[END_USER_AND_DATA_ROLE] OFF';
    At the session level:
    ALTER SESSION SET events 'TRACE[END_USER_AND_DATA_ROLE] OFF';

    Note:

    Session-level tracing is automatically disabled when the database session ends.

18.6.3 Trace End-User Context Attributes

Diagnose issues with context attribute loading, evaluation, and PL/SQL callback execution.

  1. Enable tracing.
    At the system level (all sessions):
    ALTER SYSTEM SET events 'TRACE[END_USER_CONTEXT] disk=high';
    At the session level (current session only):
    ALTER SESSION SET events 'TRACE[END_USER_CONTEXT] disk=high';
  2. Reproduce the issue.

    After enabling the trace, immediately execute the queries or operations that are causing the issue.

  3. Locate and examine the trace file.
    Run the following query to locate the trace file for your session:
    SELECT VALUE FROM V$DIAG_INFO WHERE NAME = 'Default Trace File';

    Open the trace file and inspect it for context attribute loading details, attribute evaluation results, PL/SQL callback execution, and any related errors. Share this file with Oracle Support if requested.

  4. Disable tracing after troubleshooting is complete.
    At the system level:
    ALTER SYSTEM SET events 'TRACE[END_USER_CONTEXT] OFF';
    At the session level:
    ALTER SESSION SET events 'TRACE[END_USER_CONTEXT] OFF';

    Note:

    Session-level tracing is automatically disabled when the database session ends.

18.6.4 Trace End-User Security Contexts

Diagnose issues with end-user security context establishment, token validation, and data role enablement during context attachment.

  1. Enable tracing.
    At the system level (all sessions):
    ALTER SYSTEM SET events 'TRACE[END_USER_SECURITY_CONTEXT] DISK=HIGHEST';
ALTER SYSTEM SET events 'TRACE[DBIAM] DISK=HIGHEST';
ALTER SYSTEM SET events 'TRACE[TOKEN] DISK=HIGHEST';
ALTER SYSTEM SET events 'TRACE[XSSESSION] DISK=HIGHEST';
ALTER SYSTEM SET events 'TRACE[END_USER_CONTEXT] DISK=LOW'; -- Context attributes in end-user security context
    At the session level (current session only):
    ALTER SESSION SET events 'TRACE[END_USER_SECURITY_CONTEXT] DISK=HIGHEST';
ALTER SESSION SET events 'TRACE[DBIAM] DISK=HIGHEST';
ALTER SESSION SET events 'TRACE[TOKEN] DISK=HIGHEST';
ALTER SESSION SET events 'TRACE[XSSESSION] DISK=HIGHEST';
ALTER SESSION SET events 'TRACE[END_USER_CONTEXT] DISK=LOW'; -- Context attributes in end-user security context
  2. Reproduce the issue.

    After enabling the trace, immediately execute the queries or operations that are causing the issue.

  3. Locate and examine the trace file.
    Run the following query to locate the trace file for your session:
    SELECT VALUE FROM V$DIAG_INFO WHERE NAME = 'Default Trace File';

    Open the trace file and inspect it for context establishment details, token validation results, data role enablement details, and any related errors. Share this file with Oracle Support if requested.

  4. Disable tracing after troubleshooting is complete.
    At the system level:
    ALTER SYSTEM SET events 'TRACE[END_USER_SECURITY_CONTEXT] OFF';
ALTER SYSTEM SET events 'TRACE[DBIAM] OFF';
ALTER SYSTEM SET events 'TRACE[TOKEN] OFF';
ALTER SYSTEM SET events 'TRACE[XSSESSION] OFF';
ALTER SYSTEM SET events 'TRACE[END_USER_CONTEXT] OFF';
    At the session level:
    ALTER SESSION SET events 'TRACE[END_USER_SECURITY_CONTEXT] OFF';
ALTER SESSION SET events 'TRACE[DBIAM] OFF';
ALTER SESSION SET events 'TRACE[TOKEN] OFF';
ALTER SESSION SET events 'TRACE[XSSESSION] OFF';
ALTER SESSION SET events 'TRACE[END_USER_CONTEXT] OFF';

    Note:

    When enabling session-level tracing for application-mediated access scenarios, enable the trace on the connection pool user account's database session.