Oracle Trace File Analyzer (TFA) – 18.2.1 REST services installation and examples

Nesting dolls

(Picture by allysonmiller1969 [CC BY-SA 3.0], via Pixabay)

After having upgraded TFA in version 18.2.1, I really wanted to configure and start using its new REST support feature (since 18.2.0) : “Oracle Trace File Analyzer now includes REST support, allowing invocation & query over HTTPS. […] REST supports printing details, starting a diagcollect and downloading collections”

First, I simply tried to start TFA REST services :

# sudo /grid/infrastructure/home/bin/tfactl rest -start

Configuring TFA REST Services using ORDS :

This might take couple of minutes. Please be patient.

Adding Dependency Jars to ORDS

Adding users to ORDS :

Enter a password for user tfaadmin:
Confirm password for user tfaadmin:

Enter a password for user tfarest:
Confirm password for user tfarest:

Starting TFA REST Services

Failed to start TFA REST Services

URL : https://node01:9090/ords/tfactl/print/status

NOTE : The Standalone Oracle Rest Data Services (ORDS) setup feature utilizes file based user
authentication and is provided solely for use in test and development environments.

But I got an error : Failed to start TFA REST Services. What is the problem ?

After a quick search, I found the related log file :

# cat /grid/infrastructure/home/tfa/node01/rest/ords/log/ords.start.log_34617

Jul 03, 2018 10:18:55 AM oracle.dbtools.standalone.ModifyUser execute
INFO: Created user: tfarest in file: /my/oracle/base/tfa/node01/rest/ords/credentials
2018-07-03 10:18:56.382:INFO::main: Logging initialized @1123ms to org.eclipse.jetty.util.log.StdErrLog
Jul 03, 2018 10:18:57 AM
INFO: HTTPS listening on port: 9090
Jul 03, 2018 10:18:57 AM
INFO: The document root is serving static resources located in: /my/oracle/base/tfa/node01/rest/ords/standalone/doc_root
2018-07-03 10:18:57.865:INFO:oejs.Server:main: jetty-9.4.z-SNAPSHOT
2018-07-03 10:18:57.877:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
2018-07-03 10:18:57.878:INFO:oejs.session:main: No SessionScavenger set, using defaults
2018-07-03 10:18:57.878:INFO:oejs.session:main: Scavenging every 660000ms
Jul 03, 2018 10:18:57 AM
INFO: No encryption key found in configuration, generating key
Jul 03, 2018 10:18:57 AM
INFO: No mac key found in configuration, generating key
Jul 03, 2018 10:18:58 AM
INFO: Updated configurations: defaults
Jul 03, 2018 10:18:58 AM
INFO: Updated configuration with generated keys
Jul 03, 2018 10:18:58 AM
INFO: Using configuration folder: /my/oracle/base/tfa/node01/rest/ords


config.dir
Jul 03, 2018 10:18:58 AM
INFO: Oracle REST Data Services initialized
Oracle REST Data Services version : 17.4.1.353.06.48
Oracle REST Data Services server info: jetty/9.4.z-SNAPSHOT

2018-07-03 10:18:58.328:INFO:oejsh.ContextHandler:main: Started o.e.j.s.ServletContextHandler@2de8284b{/ords,null,AVAILABLE,@Secured}
2018-07-03 10:18:58.328:INFO:oejsh.ContextHandler:main: Started o.e.j.s.h.ContextHandler@396e2f39{/,null,AVAILABLE,@Secured}
2018-07-03 10:18:58.333:INFO:oejs.AbstractConnector:main: Stopped Secured@551bdc27{SSL,[ssl, http/1.1]}{0.0.0.0:9090}
2018-07-03 10:18:58.333:INFO:oejs.session:main: Stopped scavenging
2018-07-03 10:18:58.333:INFO:oejsh.ContextHandler:main: Stopped o.e.j.s.h.ContextHandler@396e2f39{/,null,UNAVAILABLE,@Secured}
2018-07-03 10:18:58.335:INFO:oejsh.ContextHandler:main: Stopped o.e.j.s.ServletContextHandler@2de8284b{/ords,null,UNAVAILABLE,@Secured}
Jul 03, 2018 10:18:58 AM
SEVERE: Could not start Standalone Mode because the listen port: null is already in use by another process. Check if another instance of ords is already running.

Ok, so port: null is already in use by another process … Fortunately, the documentation indicates the default port is 9090.
With the help of netstat, I discovered who the guilty process was :

# netstat -anp | grep 9090
tcp        0      0 0.0.0.0:9090            0.0.0.0:*               LISTEN      12345/guilty

The use of default port 9090 not being mandatory for me, I decided to use another port, like 59090. I launched the following command :

# sudo /grid/infrastructure/home/bin/tfactl rest -start -port 59090

Starting TFA REST Services

Failed to start TFA REST Services

URL : https://node01:9090/ords/tfactl/print/status

NOTE : The Standalone Oracle Rest Data Services (ORDS) setup feature utilizes file based user
       authentication and is provided solely for use in test and development environments.

But hey, it does not work like this, since the output still showed a URL with port 9090.
Then I tried to make thing clean and decided to uninstall and re-install REST service :

# sudo /grid/infrastructure/home/bin/tfactl rest -uninstall

Uninstalling TFA REST Services on node01

TFA REST Services is not running

Successfully uninstalled TFA REST Services
# sudo /grid/infrastructure/home/bin/tfactl rest -start -port 59090

Configuring TFA REST Services using ORDS :

This might take couple of minutes. Please be patient.

Adding Dependency Jars to ORDS

Adding users to ORDS :

Enter a password for user tfaadmin:
Confirm password for user tfaadmin:

Enter a password for user tfarest:
Confirm password for user tfarest:

Starting TFA REST Services

Successfully started TFA REST Services [PID : 42050]

URL : https://node01:59090/ords/tfactl/print/status

NOTE : The Standalone Oracle Rest Data Services (ORDS) setup feature utilizes file based user
       authentication and is provided solely for use in test and development environments.

Good, no errors anymore ! Now it’s time to have some fun !

Let’s type the suggested URL in a browser :

tfa_rest_capture_01

Okay, now let’s sign in with tfarest user configured in the first step :

tfa_rest_capture_02

And here is the result 🙂 :

[ {
  "status" : "CheckOK",
  "hostname" : "node01",
  "pid" : 42622,
  "port" : 1234,
  "version" : "18.2.1.0.0",
  "buildId" : "18210020180529111033",
  "inventoryStatus" : "COMPLETE"
}, {
  "status" : "CheckOK",
  "hostname" : "node02",
  "pid" : 38453,
  "port" : 1234,
  "version" : "18.2.1.0.0",
  "buildId" : "18210020180529111033",
  "inventoryStatus" : "COMPLETE"
}, {
  "status" : "CheckOK",
  "hostname" : "node03",
  "pid" : 56850,
  "port" : 1234,
  "version" : "18.2.1.0.0",
  "buildId" : "18210020180529111033",
  "inventoryStatus" : "COMPLETE"
} ]

For example, we can get the current location and amount of used space of the repository directory with https://node01:59090/ords/tfactl/print/repository :

[ {
  "hostname" : "node01",
  "directory" : "/my/oracle/base/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 2319,
  "freeSpaceMB" : 7921
}, {
  "hostname" : "node02",
  "directory" : "/my/oracle/base/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 1716,
  "freeSpaceMB" : 8524
}, {
  "hostname" : "node03",
  "directory" : "/my/oracle/base/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 1730,
  "freeSpaceMB" : 8510
} ]

An interesting API to use is https://node01:59090/ords/tfactl/diagcollect, which launches a collection … :

{
  "collectionId" : "20180705111426node01",
  "zipName" : "TFA_DEF_ZIP_20180705111426",
  "tagName" : "TFA_DEF_TAG_20180705111426",
  "message" : [ "Diagcollect request will be processed soon by TFA" ]
}

… and this collection can be checked later using its collection id with https://node01:59090/ords/tfactl/print/collections/20180705111426node01 :

{
  "id" : "20180705111426node01",
  "type" : "Manual Collection",
  "requestUser" : "oracle",
  "nodeList" : "[node02, node03]",
  "masterHost" : "node01",
  "startTime" : "Wed Jul 04 23:14:30 CEST 2018",
  "endTime" : "Thu Jul 05 11:14:30 CEST 2018",
  "tag" : "/my/oracle/base/tfa/repository/TFA_DEF_TAG_20180705111426",
  "zipFileName" : "node01.TFA_DEF_ZIP_20180705111426.zip",
  "componentList" : "[emagent, dbclient, acfs, rdbms, os, crs, sundiag, em, chmos, asmproxy, asmio, crsclient, oms, dbwlm, install, tns, ocm, asm, rhp, cha, emplugins, cfgtools, afd, wls]",
  "zipFileSize" : 147623,
  "collectionTime" : 229,
  "events" : null
}

To me the most useful API is certainly the one that allows you to download the collection zipfile : https://node01:59090/ords/tfactl/download/20180705111426node01

And of course it is also possible to use curl :

# curl -k --user tfarest:awesomepassword https://node01:59090/ords/tfactl/print/repository
[ {
  "hostname" : "node01",
  "directory" : "/my/oracle/base/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 2499,
  "freeSpaceMB" : 7741
}, {
  "hostname" : "node02",
  "directory" : "/my/oracle/base/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 2111,
  "freeSpaceMB" : 8129
}, {
  "hostname" : "node03",
  "directory" : "/my/oracle/base/tfa/repository",
  "status" : "OPEN",
  "maxSizeMB" : 10240,
  "currentSizeMB" : 2140,
  "freeSpaceMB" : 8100
} ]
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s