| Lesson 9 | Using Trace Assistant |
| Objective | Format traces using the Trace Assistant |
Using Trace Assistant
Oracle Net Services includes a tool called the Trace Assistant to help make sense of what is in a trace file, by converting existing lines of trace file text into a more readable paragraph. It dates back to SQL*Net version 2.3, from the same Net8 era whose connectivity methods have since given way to Easy Connect Plus and OCI-native connections (see
Oracle 23ai OCI Service Connection Methods for the current approach). The Trace Assistant tool itself, unlike those older naming conventions, has not been replaced or desupported: it remains a documented, current part of Oracle Net Services through Oracle 26ai.
A raw level-16 trace file is not written for human readers. It is a dense sequence of internal calls, packet dumps, and layer-by-layer protocol detail, exactly the level of information a developer or Oracle Support needs for the hardest connectivity and performance problems, and exactly the level of noise that makes it slow to read by eye. Trace Assistant's whole job is to take that raw sequence and group it into the handful of readable sections covered in this lesson: connectivity information, Two-Task Common (TTC) calls, errors, and statistics.
Two conditions govern when Trace Assistant actually works:
- It reads only level 16 (support) Oracle Net Services trace files; lower trace levels do not contain the detail it needs.
- It works only when
DIAG_ADR_ENABLED is set to OFF. Under the ADR default, trace output does not land in the flat-file format Trace Assistant expects, so a trace intended for Trace Assistant has to be captured with ADR disabled for that component.
Both of these are worth checking before you spend time reproducing a problem specifically to get a Trace Assistant-readable file: a
SUPPORT-level trace captured under the ADR default will not open cleanly with
trcasst, and a trace captured at
ADMIN or lower will not have the detail Trace Assistant needs even with ADR off.
This also explains why Trace Assistant and the ADR-era tools covered in the previous lesson,
adrci and Oracle Trace File Analyzer, are not competing replacements for one another.
adrci is the right tool for locating and browsing whatever ADR has already collected, under the default configuration almost every environment actually runs. Trace Assistant is the right tool for the specific case where you have deliberately captured a level-16, non-ADR trace because you need the kind of packet-and-TTC-level detail that ADR's own browsing commands do not format for you. Most troubleshooting never reaches that second case at all.
Trace Assistant Syntax
Run Trace Assistant from the command line:
trcasst [options] filename
If no options are provided, the default is
-odt -e0 -s, which produces detailed connectivity information, detailed Two-Task Common (TTC) information, error level 0, and statistics, all in one pass.
The documented options:
-o, connectivity and TTC information, followed by one of:
c: summary connectivity information
d: detailed connectivity information
u: summary TTC information
t: detailed TTC information
q: SQL commands, layered on top of the summary TTC information
TTC, Two-Task Common, is the layer that handles the actual database requests riding on top of the connection, opening a cursor, selecting rows, updating rows, and so on. The connectivity sub-options (c, d) show how the connection itself was established; the TTC sub-options (u, t, q) show what happened once it was. A connection-establishment problem is usually easier to spot with -od; a problem that only shows up after the connection succeeds, slow or failing SQL calls over an otherwise healthy connection, is a better fit for -ot or -ouq.
-p: Oracle internal use only.
-s: statistical information.
-e, error information, followed by an optional decoding level:
0 or nothing: translates the NS error numbers from the nserror function and lists all other errors (the default).
1: shows only the translated NS error.
2: shows the raw, untranslated error numbers.
In practice, -e1 is usually the right level to start with: it gives you the translated NS error without the extra surrounding detail -e0 includes, which is often enough to confirm the cause on its own. Reach for -e2 only when you need the raw, untranslated numbers, for example to compare them directly against the numeric error stack you may already have pulled from a log file.
-la: connection-oriented output, showing, per connection ID, the socket ID and other connection-level detail.
-li <connection_id>: output filtered to one specific connection ID, when you already know which connection you care about.
A Worked Example
dbhost01 $ trcasst -s cli_12489.trc
Trace Assistant Utility for Linux: Version 26.1.0.0.0 - Production on 04-OCT-2026 11:20:05
Copyright (c) 1991, 2026, Oracle. All rights reserved.
*************************************************************************
* Trace Assistant Tool *
* TRCASST *
*************************************************************************
======================================================
Trace File Statistics:
----------------------------------------------------------------------
DATABASE:
Operation Counts: 1842 opens, 2615 parses, 2301 executes, 18940 fetches.
SQL*Net:
Total Calls: 4126 sent, 4126 received, 0 upi
Total Bytes: 312048 sent, 891204 received
Maximum Bytes: 8192 sent, 8192 received
*************************************************************************
* Trace Assistant has completed *
* TRCASST *
*************************************************************************
Here, the
-s option alone produces the statistics summary: call counts, byte totals, and maximums, useful for a quick sense of connection volume before diving into connection-level detail with
-la or a specific connection with
-li.
Narrowing In on One Connection
A busy trace file can cover many connections at once, which is exactly where
-la and
-li earn their place. Running
trcasst -la against the file lists every connection it contains, each identified by a connection ID and socket ID, which is the quickest way to see how many distinct sessions are represented before picking one to investigate further. Once you have the connection ID you actually care about, perhaps because it matches the
CONNECTION_ID you already pulled from a log file in the previous lesson,
trcasst -li <connection_id> filters the output down to just that connection, rather than making you scroll past every other session in the file.
Used together, this is a practical two-step workflow for a trace that covers more activity than you need: run
-la first to see what is in the file and find the connection ID you want, then run
-li with that ID to get a focused view of just that connection's TTC calls and errors.
A
-la run against a multi-connection trace looks roughly like this, one block per connection:
dbhost01 $ trcasst -la svr_18204.trc
*************************************************************************
* Trace Assistant *
*************************************************************************
Connection ID: 00000B1F00000008
Socket ID: 14
(CID=(PROGRAM=app_server)(HOST=appsrv02)(USER=appuser))
Connection ID: 00000B1F00000011
Socket ID: 17
(CID=(PROGRAM=app_server)(HOST=appsrv03)(USER=appuser))
*************************************************************************
* Trace Assistant has completed *
*************************************************************************
With the connection ID for the session you actually care about in hand, for example the one from
appsrv02,
-li filters down to it:
dbhost01 $ trcasst -li 00000B1F00000008 svr_18204.trc
That second command reproduces only the TTC calls and errors belonging to connection ID
00000B1F00000008, leaving every other session in the file out of the output entirely.
Putting It Together: A Worked Scenario
Suppose the previous lesson's client-to-Connection-Manager-to-server investigation has narrowed a timeout down to the server leg, but the log alone does not explain why. The next step is a level-16 server trace, captured with
DIAG_ADR_ENABLED=OFF for that session so Trace Assistant can read it:
- Set
TRACE_LEVEL_SERVER=SUPPORT and DIAG_ADR_ENABLED=OFF, reproduce the problem, and locate the resulting .trc file.
- Run
trcasst -s against it first, to confirm the trace actually captured meaningful activity before investing time in a deeper read.
- Run
trcasst -la to list the connections in the file and find the one matching the application server in question.
- Run
trcasst -li <connection_id> with that connection's ID, and add -e1 if an error is involved, to get a focused, readable account of exactly what happened on that one connection.
Once the cause is confirmed, turn tracing back off and disable it the same way it was enabled, by setting
TRACE_LEVEL_SERVER back to
OFF and re-enabling ADR if it was only disabled for this investigation.
It is worth being realistic about how often this is actually needed: reading a raw trace file, even with Trace Assistant's help, is a comparatively rare activity even for an experienced DBA. In the large majority of cases, a connectivity problem is resolved using the log files and the general diagnostic steps covered earlier in this module, well before anyone needs to open a level-16 trace file at all. Trace Assistant is there for the harder remaining cases, not the everyday ones.
A short recap of this lesson:
- Trace Assistant (
trcasst) remains current in Oracle 26ai; it has not been replaced by ADR-based tooling, it works alongside it, under different conditions.
- It needs a level-16 (
SUPPORT) trace, captured with DIAG_ADR_ENABLED=OFF for that component.
- With no options, it produces detailed connectivity, detailed TTC, error level 0, and statistics in one pass.
-s gives a quick statistical overview; -la lists every connection in the file; -li <connection_id> narrows the output to one connection once you know which one you want.
The next lesson concludes this module.
