If you are here, I assume you are looking for some ways to enable traces on Documentum. There are already a few blog posts here and there showing some information but Documentum being what it is, i.e., a quite complex machinery, there are just way too many places/configurations that you can have traces/debug information on. Therefore, I also wanted to contribute with what I’m mainly using when dealing with Documentum.

This blog will not include configurations that can be done in User Interfaces. That means Documentum Agent Exec (“-trace_level 1” on method args) and Job (trace level on job / trace launch and other options on methods) that can be enabled on DA is out-of-scope as well as any traces you can turn-on on the browser’s URL (API for DA), same thing for xPlore Dsearch debug logs, etc… I will also ignore anything related to generic java logging configuration. Any part of a Documentum application has its own logging framework (log4j, slf4j, logback or whatever) and you can of course configure that logging to have debug information, but it’s not specific to Documentum.

1. Repository

Alright, so let’s start the examples on traces with the Repository part. Here, you can either set the options at startup or at runtime. At startup, it’s simply about adding “-oXXX” parameters to the start script, where “XXX” is the option’s name:

[dmadmin@cs-0 ~]$ # Startup:
[dmadmin@cs-0 ~]$ $DOCUMENTUM/dba/dm_start_REPO \
                        -osqltrace \
                        -orpctrace \
                        -odocbroker_trace \
                        -otrace_authentication \
                        -otrace_complete_launch \
                        -otrace_method_server \
                        -otrace_http_post \
                        -ohttp_post \
                        -oticket_trace

starting Documentum server for repository: [REPO]
with server log: [$DOCUMENTUM/dba/log/REPO.log]
server pid: 7567
[dmadmin@cs-0 ~]$

The problem with the startup approach is that it’s simple, true, but maybe too simple. You are missing some specific options and, if you want to disable the traces, then it’s either you use the runtime approach (you can disable traces at runtime even if it was enabled using the startup command) OR you restart the repository (which means a downtime). Therefore, the runtime approach is used most of the time. Here are some iAPI commands you can use to apply the same traces:

# Runtime - Enable
apply,c,NULL,SET_OPTIONS,OPTION,S,sqltrace,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,sqltrace,VALUE,B,T,USERNAME,S,<user_name>
apply,c,NULL,SET_OPTIONS,OPTION,S,rpctrace,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,rpctrace,VALUE,B,T,USERNAME,S,<user_name>
apply,c,NULL,SET_OPTIONS,OPTION,S,docbroker_trace,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_complete_launch,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_method_server,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_http_post,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,http_post,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,ticket_trace,VALUE,B,T

# Runtime - Disable
apply,c,NULL,SET_OPTIONS,OPTION,S,sqltrace,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,sqltrace,VALUE,B,F,USERNAME,S,<user_name>
apply,c,NULL,SET_OPTIONS,OPTION,S,rpctrace,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,rpctrace,VALUE,B,F,USERNAME,S,<user_name>
apply,c,NULL,SET_OPTIONS,OPTION,S,docbroker_trace,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_complete_launch,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_method_server,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_http_post,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,http_post,VALUE,B,F
apply,c,NULL,SET_OPTIONS,OPTION,S,ticket_trace,VALUE,B,F

As you can see above, you can enable and disable SQL or RPC Traces for a specific user (“user_name“), which allows to reduce the size of logs while still getting the details you need, if you know the usernames that will participate in the needed actions. Of course, if you disable SQL/RPC traces globally, it will disable them for all users, even if you enabled traces for a specific user before.

There are other options such as “nettrace“, “debug“, “lock_trace“, “net_ip_addr“, … But the above are definitively more useful/usable from my point of view.

2. Connection broker

The second part is related to the Docbroker. To enable connection traces, you can update the “Docbroker.ini” file with “trace=true“, for example:

[dmadmin@cs-0 ~]$ # Startup:
[dmadmin@cs-0 ~]$ cat Docbroker.ini
[DOCBROKER_CONFIGURATION]
secure_connect_mode=secure
trace=true
[dmadmin@cs-0 ~]$ 
[dmadmin@cs-0 ~]$ $DOCUMENTUM/dba/dm_launch_Docbroker
starting connection broker on current host: [cs-0]
with connection broker log: [$DOCUMENTUM/dba/log/docbroker.cs-0.1489.log]
connection broker pid: 7575
[dmadmin@cs-0 ~]$

The above requires you to restart the Docbroker to be taken into account, since there is no reload for the Docbroker. Similarly, there is another set of traces that can be enabled by setting some environment variables before starting the Docbroker:

[dmadmin@cs-0 ~]$ # Startup:
[dmadmin@cs-0 ~]$ export DM_DOCBROKER_TRACE=1
[dmadmin@cs-0 ~]$ export DM_DEBUG_BROKER=1
[dmadmin@cs-0 ~]$ export DM_TRANS_LOG=1
[dmadmin@cs-0 ~]$ 
[dmadmin@cs-0 ~]$ $DOCUMENTUM/dba/dm_launch_Docbroker
starting connection broker on current host: [cs-0]
with connection broker log: [$DOCUMENTUM/dba/log/docbroker.cs-0.1489.log]
connection broker pid: 7582
[dmadmin@cs-0 ~]$

These environment variables can have any value (null, 0, 1, 10, …), as far as I know, it doesn’t have any impact on the messages being traced/logged, as long as the environment variable is present/exists. You also need to restart to take into account the change and to disable it (unset the environment variable), which might be annoying…

  • DM_DOCBROKER_TRACE is useful to see when projections from repositories are done, it’s pretty concise so it’s interesting to enable.
  • DM_DEBUG_BROKER is more for OpenText support, since it’s really debug details.
  • DM_TRANS_LOG is the most useful one from my point of view since it displays quite a bit of information on the Docbroker maps with before/after status.

Another very useful trace capability, still on the Documentum Server, is if you want to debug the full text search queries/responses from the Repository. For that purpose, and contrary to the repository debugging, it’s not a SET_OPTIONS but a MODIFY_TRACE command, at runtime, still in iAPI:

# Runtime - Enable
apply,c,NULL,MODIFY_TRACE,SUBSYSTEM,S,fulltext,VALUE,S,all

# Execute a search
?,c,select count(*) from dm_document search document contains 'test';

# Runtime - Disable
apply,c,NULL,MODIFY_TRACE,SUBSYSTEM,S,fulltext,VALUE,S,none

While this trace is enabled, the Repository will log and store all communications and exchanges between the Documentum Server and xPlore and you will be able to see all that inside the file “$DOCUMENTUM/dba/log/fulltext/fttrace_REPO.log“

4. DFC

A very short/quick section about DFC, everybody knows it, so I won’t describe it too much. Here is an example of runtime configuration that can be enabled/disabled at will:

[dmadmin@cs-0 ~]$ cat $DOCUMENTUM/config/dfc.properties
...
# Runtime - Enable/Disable
dfc.tracing.enable=true
#dfc.tracing.enable=false
dfc.tracing.mode=standard
#dfc.tracing.mode=compact
dfc.tracing.include_rpcs=true
dfc.tracing.verbose=true
dfc.tracing.max_stack_depth=0
dfc.tracing.include_session_id=true
dfc.tracing.log.level=DEBUG
dfc.tracing.dir=/tmp/dfc_tracing_DD-MMM-YYYY
dfc.tracing.timing_style=date
dfc.tracing.date_column_width=12
dfc.tracing.date_format=yyyy-MM-dd hh:mm:ss.SSS
dfc.tracing.file_prefix=dfc_tracing
dfc.tracing.max_backup_index=10
dfc.tracing.max_file_size=104857600
dfc.logging.level_to_force_stack=ALL
dfc.tracing.print_exception_stack=true
dfc.tracing.user_name_filter[0]=<user_login_name_1>
dfc.tracing.user_name_filter[1]=<user_login_name_2>
#dfc.tracing.file_creation_mode=user
...
[dmadmin@cs-0 ~]$

Same thing as for the Repository options, you can enable the traces only for a specific user but this time you need to use the “user_login_name” and not “user_name“. DFC properties are reloaded periodically so you can just modify the file and it will be taken into account after a few seconds.

5. Installers

Last but not least I wanted to talk about the installer debug options. It will happen that you are facing some errors while installing/upgrading some components of Documentum. When that happen, you will often face the issue that the logs aren’t very extensive and are missing very important details. That’s when adding debug information on the installers is your only way out. Fortunately, that’s possible and it’s pretty easy, you just have to re-execute the same command but with an additional parameter:

[dmadmin@cs-0 ~]$ # D2
[dmadmin@cs-0 ~]$ tmp_dir="$DOCUMENTUM/D2-Install/tmp"
[dmadmin@cs-0 ~]$ d2_installer="$DOCUMENTUM/D2-Install/${d2_package}/D2-Installer-${d2_version}.jar"
[dmadmin@cs-0 ~]$ d2_install_file="$DOCUMENTUM/D2-Install/silent/d2_install.xml"
[dmadmin@cs-0 ~]$
[dmadmin@cs-0 ~]$ ### Without debug
[dmadmin@cs-0 ~]$ $JAVA_HOME/bin/java \
                        -Djava.io.tmpdir=${tmp_dir} \
                        -jar ${d2_installer} \
                        ${d2_install_file}
[dmadmin@cs-0 ~]$ ### With debug
[dmadmin@cs-0 ~]$ $JAVA_HOME/bin/java \
                        -DTRACE=true -DDEBUG=true \
                        -Djava.io.tmpdir=${tmp_dir} \
                        -jar ${d2_installer} \
                        ${d2_install_file}


[dmadmin@cs-0 ~]$ # Documentum Server - Binaries
[dmadmin@cs-0 ~]$ install_file="${bin_dir}/${cs_version}/install.properties"
[dmadmin@cs-0 ~]$
[dmadmin@cs-0 ~]$ ### Without debug
[dmadmin@cs-0 ~]$ ${bin_dir}/${cs_version}/serverSetup.bin \
                        -f ${install_file}
[dmadmin@cs-0 ~]$ ### With debug
[dmadmin@cs-0 ~]$ ${bin_dir}/${cs_version}/serverSetup.bin \
                        -DLOG_LEVEL=DEBUG \
                        -f ${install_file}


[dmadmin@cs-0 ~]$ # Documentum Server - Repository
[dmadmin@cs-0 ~]$ repo_install_file="${bin_dir}/${cs_version}/repo_install.properties"
[dmadmin@cs-0 ~]$
[dmadmin@cs-0 ~]$ ### Without debug
[dmadmin@cs-0 ~]$ $DM_HOME/install/dm_launch_server_config_program.sh \
                        -f ${repo_install_file}
[dmadmin@cs-0 ~]$ ### With debug
[dmadmin@cs-0 ~]$ $DM_HOME/install/dm_launch_server_config_program.sh \
                        -DLOG_LEVEL=DEBUG \
                        -f ${repo_install_file}


[dmadmin@cs-0 ~]$ # Documentum Server - Remote Repository / CFS
[dmadmin@cs-0 ~]$ cfs_install_file="${bin_dir}/${cs_version}/cfs_install.properties"
[dmadmin@cs-0 ~]$
[dmadmin@cs-0 ~]$ ### Without debug
[dmadmin@cs-0 ~]$ $DM_HOME/install/dm_launch_cfs_server_config_program.sh \
                        -f ${cfs_install_file}
[dmadmin@cs-0 ~]$ ### With debug
[dmadmin@cs-0 ~]$ $DM_HOME/install/dm_launch_cfs_server_config_program.sh \
                        -DLOG_LEVEL=DEBUG \
                        -f ${cfs_install_file}


[xplore@ia-0 ~]$ # Documentum xPlore - IndexAgent
[xplore@ia-0 ~]$ ia_install_file="${bin_dir}/${ft_version}/ia_install.properties"
[xplore@ia-0 ~]$
[xplore@ia-0 ~]$ ### Without debug
[xplore@ia-0 ~]$ $XPLORE_HOME/setup/indexagent/iaConfig.bin \
                        LAX_VM "$JAVA_HOME/bin/java" \
                        -f ${ia_install_file}
[xplore@ia-0 ~]$ ### With debug
[xplore@ia-0 ~]$ $XPLORE_HOME/setup/indexagent/iaConfig.bin \
                        LAX_VM "$JAVA_HOME/bin/java" \
                        -DLOG_LEVEL=DEBUG \
                        -f ${ia_install_file}

Other installers are similar to these ones, it’s either adding the “-DLOG_LEVEL=DEBUG” or “-DTRACE=true -DDEBUG=true” parameters to the command line, depending on if it’s a real installer provided by OpenText or a simple java command-line with a JAR. That completes this blog about useful debug options on the principal components of Documentum. Again, that’s what I end-up using the most on my daily work. If you think I forgot an important piece, don’t hesitate to share!

Post Views: 651
Thumbnail [60x60]
by
Morgan Patou